PutBucketInventory: Configure an inventory rule - Object Storage Service

Use PutBucketInventory para configurar una regla de inventario en un bucket.

Notas

Un inventario le permite obtener información sobre los objetos de un bucket, como la cantidad de objetos, el tamaño, la clase de almacenamiento y el estado de cifrado. Al configurar las reglas de inventario, tenga en cuenta lo siguiente:

Antes de configurar una regla de inventario, debe crear un rol de RAM. Este rol necesita permisos para leer todos los objetos del bucket de origen y escribir objetos en el bucket de destino. Se recomienda usar la consola de OSS para configurar su primera regla de inventario, ya que la consola le ayuda a crear un rol de RAM con los permisos necesarios. Para más detalles sobre los permisos que requiere el rol de RAM, consulte bucket inventory.
Se pueden configurar hasta 1,000 reglas de inventario por bucket.
Los buckets de origen y de destino para los archivos de inventario exportados deben estar en la misma región.
Para habilitar el inventario incremental, póngase en contacto con soporte técnico. Esta función solo es compatible con la región de México.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene permisos completos. Los usuarios o roles de RAM asociados a una cuenta de Alibaba Cloud no cuentan con ningún permiso de manera predeterminada. La cuenta de Alibaba Cloud o el administrador de la cuenta deben otorgar los permisos de operación mediante RAM policies o Bucket Policy.

API	Acción	Descripción
PutBucketInventory	oss:PutBucketInventory	Configura inventarios para un bucket.

Sintaxis de la solicitud

Importante

El parámetro de cadena de consulta inventoryId es obligatorio. Su valor debe coincidir con el del elemento Id en el cuerpo de la solicitud.
Las opciones LastModifyBeginTimeStamp, LastModifyEndTimeStamp, LowerSizeBound, UpperSizeBound y StorageClass solo se pueden utilizar en las regiones China (Qingdao), China (Hohhot) y Germany (Frankfurt).

  PUT /?inventory&inventoryId=report1 HTTP/1.1
  Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
    <InventoryConfiguration>
     <Id>report1</Id>
     <IsEnabled>true</IsEnabled>
     <Destination>
        <OSSBucketDestination>
           <Format>CSV</Format>
           <AccountId>1000000000000000</AccountId>
           <RoleArn>acs:ram::1000000000000000:role/AliyunOSSRole</RoleArn>
           <Bucket>acs:oss:::destination-bucket</Bucket>
           <Prefix>prefix1</Prefix>
           <Encryption>
              <SSE-KMS>
                 <KeyId>keyId</KeyId>
              </SSE-KMS>
           </Encryption>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Monthly</Frequency>
        <DayOfMonth>1</DayOfMonth>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>TransitionTime</Field>        
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
     <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </InventoryConfiguration>

Elementos de la solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Id	String	Sí	report1	Nombre personalizado del inventario. Debe cumplir con los siguientes requisitos: El nombre debe ser único dentro del bucket. El nombre no puede superar los 192 caracteres.
IsEnabled	Boolean	Sí	true	Indica si el inventario está habilitado. Valores válidos: true: habilita el inventario. false: deshabilita el inventario.
Filter	Container	No	N/A	Contenedor del filtro que especifica los criterios de los objetos que se incluirán en el inventario.
Prefix	String	No	Pics/	Prefijo para filtrar objetos. Nodo principal: Filter
LastModifyBeginTimeStamp	String	No	1637883649	Inicio del intervalo de tiempo de última modificación de los objetos. El valor es una marca de tiempo UNIX en segundos. Intervalo de valores: [1262275200, 253402271999]
LastModifyEndTimeStamp	String	No	1638347592	Fin del intervalo de tiempo de última modificación de los objetos. El valor es una marca de tiempo UNIX en segundos. Intervalo de valores: [1262275200, 253402271999]
LowerSizeBound	String	No	1024	Tamaño mínimo (en bytes) de los objetos que se incluirán en el inventario. El valor debe ser mayor o igual a 0 B y menor o igual a 48.8 TB.
UpperSizeBound	String	No	1048576	Tamaño máximo (en bytes) de los objetos que se incluirán en el inventario. El valor debe ser mayor que 0 B y menor o igual a 48.8 TB.
StorageClass	String	No	Standard,IA	Clases de almacenamiento de los objetos que se incluirán en el inventario. Puede especificar varias clases de almacenamiento. Valores válidos: Standard IA Archive ColdArchive All (predeterminado): todas las clases de almacenamiento
Destination	Container	Sí	N/A	Contenedor con la información del destino donde se almacenan los informes de inventario.
OSSBucketDestination	Container	Sí	N/A	Contenedor con la información del bucket donde se almacenan los informes de inventario. Nodo principal: Destination
Format	String	Sí	CSV	Formato del informe de inventario. El informe es un archivo CSV comprimido con GZIP. Valores válidos: CSV, Parquet (actualmente, el formato Parquet solo es compatible con la región UK (London)). Nodo principal: OSSBucketDestination
AccountId	String	Sí	100000000000000	ID de la cuenta de Alibaba Cloud propietaria del bucket de destino. Nodo principal: OSSBucketDestination
RoleArn	String	Sí	acs:ram::100000000000000:role/AliyunOSSRole	ARN (Alibaba Cloud Resource Name) del rol de RAM con permisos para leer todos los objetos del bucket de origen y escribir objetos en el bucket de destino. El formato es `acs:ram::uid:role/rolename`. Nodo principal: OSSBucketDestination
Bucket	String	Sí	acs:oss:::bucket_0001	Bucket de destino del informe de inventario. Nodo principal: OSSBucketDestination
Prefix	String	No	prefix1/	Prefijo de la ruta donde se almacenan los archivos del informe de inventario. Nodo principal: OSSBucketDestination
Encryption	Container	No	N/A	Contenedor de la configuración de cifrado del lado del servidor para el informe de inventario. Valores válidos: SSE-OSS: usa claves administradas por OSS para el cifrado y descifrado. SSE-KMS: usa una clave maestra del cliente (CMK) predeterminada o especificada, administrada por Key Management Service (KMS), para el cifrado y descifrado. Nodo principal: OSSBucketDestination Para obtener más información sobre el cifrado del lado del servidor, consulte Server-side encryption.
SSE-OSS	Container	No	N/A	Contenedor de la configuración de cifrado SSE-OSS. Nodo principal: Encryption
SSE-KMS	Container	No	N/A	Contenedor de la configuración de cifrado SSE-KMS. Nodo principal: Encryption
KeyId	String	No	keyId	ID de la CMK administrada por KMS. Nodo principal: SSE-KMS
Schedule	Container	Sí	N/A	Contenedor de la programación para generar el informe de inventario.
Frequency	String	Sí	Daily	Especifica la frecuencia con la que se genera el informe de inventario. Valores válidos: Daily: los informes de inventario se generan diariamente. Weekly: los informes de inventario se generan semanalmente. Monthly: los informes de inventario se generan mensualmente. Once: el informe de inventario se genera una sola vez. Nodo principal: Schedule
DayOfMonth	Entero positivo	No	1	Si Frequency se establece en Monthly, especifica el día del mes en que se generará el inventario. El valor debe ser un entero positivo del 1 al 31. Si no especifica DayOfMonth, el inventario se genera en un intervalo fijo de 30 días. El primer escaneo comienza el día en que se configura la regla y los informes posteriores se generan cada 30 días. Si el valor está entre 1 y 28, la tarea de inventario comienza el día especificado de cada mes. Si el valor está entre 29 y 31, la tarea comienza ese día siempre que el mes lo tenga. De lo contrario, la tarea comienza el último día del mes. Por ejemplo, si establece el valor en 31, la tarea comenzará el 30 de abril. Nota Esta fecha indica cuándo inicia la tarea de inventario, no cuándo se entrega el informe. Dado que la generación del inventario es una tarea asíncrona cuya duración depende de la cantidad de objetos, el informe se entrega después de esta fecha. Nodo principal: Schedule
AutoDelete	Boolean	No	true	Especifica si se elimina la configuración de inventario después de generar un inventario de una sola vez. Este elemento solo es válido cuando Frequency se establece en Once. Valores válidos: true, false Nodo principal: Schedule
IncludedObjectVersions	String	Sí	All	Especifica si se incluyen las versiones de los objetos en el inventario. Valores válidos: All: incluye todas las versiones de los objetos. Current: incluye únicamente la versión actual de los objetos.
OptionalFields	Container	No	N/A	Contenedor de los campos opcionales que se incluirán en el informe de inventario.
Field	String	No	Size	Campos opcionales que se incluirán en el informe de inventario. Key: nombre del objeto en el bucket, codificado en URL. VersionId: ID de versión del objeto. Este campo solo se incluye si IncludedObjectVersions se establece en All. Si el control de versiones no está habilitado para el bucket, este campo queda vacío. Si el control de versiones está habilitado para el bucket, este campo contiene el ID de versión del objeto. IsDeleteMarker: indica si la versión del objeto es un marcador de eliminación. Este campo solo se incluye si IncludedObjectVersions se establece en All. Si el control de versiones no está habilitado para el bucket, este campo se establece en false de forma predeterminada. Si el control de versiones está habilitado y el objeto es un marcador de eliminación, este campo se establece en true. Si el objeto no es un marcador de eliminación, el campo se establece en false. Size: tamaño del objeto. StorageClass: clase de almacenamiento del objeto. TransitionTime: momento en que el objeto pasó a la clase de almacenamiento Archive o Cold Archive mediante una regla de ciclo de vida. LastModifiedDate: fecha de la última modificación del objeto. ETag: ETag del objeto. Se genera cuando se crea un objeto e identifica su contenido. Para un objeto creado mediante la operación PutObject, el ETag es el hash MD5 del contenido del objeto. Para un objeto creado con otros métodos, el ETag es un valor único calculado según una regla específica y no corresponde al hash MD5 del contenido. IsMultipartUploaded: indica si el objeto se cargó mediante una carga multiparte. ObjectType: tipo del objeto. ObjectAcl: lista de control de acceso (ACL) del objeto. Crc64: valor CRC-64 del objeto. EncryptionStatus: indica si el objeto está cifrado. TaggingCount: número de etiquetas.
IncrementalInventory	Container	No	N/A	Contenedor de la configuración del inventario incremental.
IsEnabled	Boolean	Sí	true	Especifica si se habilita el inventario incremental. Valores válidos: true: habilita el inventario incremental. false: deshabilita el inventario incremental. Si este elemento se establece en true, el inventario incremental se habilita y entra en vigor incluso si InventoryConfiguration/IsEnabled se establece en false. Nodo principal: IncrementalInventory
Schedule	Container	Sí	N/A	Contenedor de la programación para generar el inventario incremental. Nodo principal: IncrementalInventory
Frequency	Entero positivo	Sí	600	Frecuencia de generación del inventario incremental, en segundos. El sistema utiliza una frecuencia fija de 600 segundos. En cada periodo se crea automáticamente un prefijo de directorio, junto con un archivo de manifiesto correspondiente y varios archivos CSV generados durante dicho periodo. No se admiten frecuencias personalizadas. Nodo principal: Schedule
OptionalFields	Container	No	N/A	Contenedor de las propiedades que se incluirán en el archivo de inventario incremental. Nodo principal: IncrementalInventory
Field	String	No	Size	Campos que se incluirán en el inventario incremental. Nodo principal: OptionalFields SequenceNumber: número de secuencia único para cada registro. En los registros del mismo objeto dentro de un mismo bucket, puede ordenarlos por SequenceNumber. Los registros ordenados suelen seguir un orden cronológico. RecordType: tipo de evento. Valores válidos: CREATE, UPDATE_METADATA y DELETE. CREATE: incluye todos los métodos de carga de objetos bajo el prefijo seleccionado, como Put, Post, Append, MultipartUpload y Copy. UPDATE_METADATA: incluye todas las actualizaciones de metadatos de los objetos bajo el prefijo seleccionado. DELETE: incluye todos los métodos de eliminación de objetos bajo el prefijo seleccionado, como DeleteObject, DeleteMultipleObjects, la generación de marcadores de eliminación tras habilitar el control de versiones y la eliminación basada en el ciclo de vida. Las eliminaciones abarcan tanto los marcadores de eliminación como las eliminaciones permanentes. En los registros de eliminación permanente solo se conservan los campos principales `Bucket`, `Key`, `SequenceNumber`, `RecordType`, `RecordTimestamp` y `VersionId`; las demás columnas quedan como null. RecordTimestamp: marca de tiempo del registro, en GMT y con precisión de milisegundos. Ejemplo: "2024-08-25 18:08:01.024". Requester: ID de Alibaba Cloud o ID de entidad principal del solicitante. RequestId: identificador único de la solicitud. SourceIp: dirección IP de origen del solicitante. Key: nombre del objeto en el bucket, codificado en URL. VersionId: ID de versión del objeto. Este campo solo se incluye si la regla de inventario está configurada para exportar todas las versiones. Si el control de versiones no está habilitado para el bucket, este campo queda vacío. Si el control de versiones está habilitado para el bucket, este campo contiene el ID de versión del objeto. IsDeleteMarker: indica si la versión del objeto es un marcador de eliminación. Este campo solo se incluye si la regla de inventario está configurada para exportar todas las versiones. Si el control de versiones no está habilitado para el bucket, este campo se establece en false de forma predeterminada. Si el control de versiones está habilitado y el objeto es un marcador de eliminación, este campo se establece en true. Si el objeto no es un marcador de eliminación, el campo se establece en false. Size: tamaño del objeto. StorageClass: clase de almacenamiento del objeto. LastModifiedDate: fecha de la última modificación del objeto. ETag: ETag del objeto. Se genera cuando se crea un objeto e identifica su contenido. Para un objeto creado mediante la operación PutObject, el ETag es el hash MD5 del contenido del objeto. Para un objeto creado con otros métodos, el ETag es un valor único calculado según una regla específica y no corresponde al hash MD5 del contenido. IsMultipartUploaded: indica si el objeto se cargó mediante una carga multiparte. ObjectType: tipo del objeto. ObjectAcl: lista de control de acceso (ACL) del objeto. Crc64: valor CRC-64 del objeto. EncryptionStatus: indica si el objeto está cifrado.

Encabezados de respuesta

Esta interfaz devuelve únicamente encabezados de respuesta comunes, como Content-Length y Date. Para más detalles, consulte Common response headers.

Ejemplos

Configuración de inventario

Ejemplo de solicitud

  PUT /?inventory&inventoryId=report1 HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
  <InventoryConfiguration>
     <Id>report1</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
         <Prefix>Pics/</Prefix>
         <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
         <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
         <LowerSizeBound>1024</LowerSizeBound>
         <UpperSizeBound>1048576</UpperSizeBound>
         <StorageClass>Standard,IA</StorageClass>
     </Filter>
     <Destination>
        <OSSBucketDestination>
          <Format>CSV</Format>
          <AccountId>100000000000000</AccountId>
          <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
          <Bucket>acs:oss:::destbucket</Bucket>
          <Prefix>prefix1/</Prefix>
          <Encryption>
             <SSE-KMS>
                <KeyId>keyId</KeyId>
             </SSE-KMS>
           </Encryption>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Daily</Frequency>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>TransistionTime</Field>   
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
  </InventoryConfiguration>

Ejemplo de respuesta

  HTTP/1.1 200 OK
  x-oss-request-id: 56594298207FB3044385****
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Content-Length: 0
  Server: AliyunOSS

Configuración de inventario mensual

A continuación se muestra una solicitud que configura un inventario para generar un reporte el día 3 de cada mes.

Solicitud de ejemplo

  PUT /?inventory&inventoryId=monthly-report HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
  <InventoryConfiguration>
     <Id>monthly-report</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
         <Prefix>logs/</Prefix>
     </Filter>
     <Destination>
        <OSSBucketDestination>
          <Format>CSV</Format>
          <AccountId>100000000000000</AccountId>
          <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
          <Bucket>acs:oss:::destbucket</Bucket>
          <Prefix>monthly-inventory/</Prefix>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Monthly</Frequency>
        <DayOfMonth>3</DayOfMonth>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
  </InventoryConfiguration>

Respuesta de ejemplo

  HTTP/1.1 200 OK
  x-oss-request-id: 56594298207FB3044385****
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Content-Length: 0
  Server: AliyunOSS

Configuración de inventario de una sola vez

Solicitud de ejemplo

  PUT /?inventory&inventoryId=once-report HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
  <InventoryConfiguration>
     <Id>once-report</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
         <Prefix>log/</Prefix>
     </Filter>
     <Destination>
        <OSSBucketDestination>
          <Format>CSV</Format>
          <AccountId>100000000000000</AccountId>
          <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
          <Bucket>acs:oss:::destbucket</Bucket>
          <Prefix>once-inventory/</Prefix>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Once</Frequency>
        <AutoDelete>true</AutoDelete>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>StorageClass</Field>
     </OptionalFields>
  </InventoryConfiguration>

Respuesta de ejemplo

  HTTP/1.1 200 OK
  x-oss-request-id: 56594298207FB3044385****
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Content-Length: 0
  Server: AliyunOSS

Configuración de inventario incremental

Solicitud de ejemplo

  PUT /?inventory&inventoryId=report1 HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
  <InventoryConfiguration>
    <Id>Report-1</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>test</Prefix>
    </Filter>
    <Destination>
      <OSSBucketDestination>
        <Format>CSV</Format>
        <AccountId>12xxxxxx29</AccountId>
        <RoleArn>acs:ram::12xxxxxx29:role/bucket-inventory-role</RoleArn>
        <Bucket>acs:oss:::test-inc-bi-bj</Bucket>
        <Prefix>Report-1</Prefix>
      </OSSBucketDestination>
    </Destination>
    <Schedule>
      <Frequency>Weekly</Frequency>
    </Schedule>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
      <Field>Size</Field>
      <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
      <Field>StorageClass</Field>
    </OptionalFields>
    <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </InventoryConfiguration>

Respuesta de ejemplo

  HTTP/1.1 200 OK
  x-oss-request-id: 56594298207FB3044385****
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Content-Length: 0
  Server: AliyunOSS

SDK

Puede invocar esta operación mediante los SDK de los siguientes lenguajes:

CLI de ossutil

El comando de ossutil correspondiente a la operación PutBucketInventory es put-bucket-inventory.

Códigos de error

Código de error	Código de estado HTTP	Descripción
InvalidArgument	400	Uno o más parámetros especificados no son válidos.
InventoryExceedLimit	400	La cantidad de reglas de inventario configuradas supera el límite permitido.
AccessDenied	403	Faltan las credenciales de autenticación en la solicitud PutBucketInventory. No cuenta con autorización para ejecutar esta operación.
InventoryAlreadyExist	409	La regla de inventario ya existe.