All Products
Search

This Product

    Object Storage Service:GetBucketInventory

    Document Center

    Object Storage Service:GetBucketInventory

    Last Updated:Jun 11, 2026

    The GetBucketInventory operation returns a specified inventory configuration for a bucket.

    Usage notes

    By default, the owner of an Alibaba Cloud account can retrieve an inventory configuration. To perform this operation as a RAM user or by using an STS token, you must have the oss:GetBucketInventory permission.

    Request syntax

    GET /?inventory&inventoryId=inventoryId HTTP/1.1

    Request parameters

    Parameter

    Type

    Required

    Description

    inventoryId

    string

    Yes

    The ID of the inventory configuration to query.

    Response elements

    Parameter

    Type

    Description

    Id

    string

    The user-specified name for the inventory configuration. The name must be unique within the bucket.

    IsEnabled

    boolean

    Indicates whether the inventory is enabled.

    Valid values: true, false

    • true: The inventory is generated.

    • false: No inventory is generated.

    Filter

    container

    A container for the prefix that is used to filter objects. Only objects whose names match the specified prefix are included in the inventory.

    Prefix

    string

    The prefix used to filter objects.

    Ancestor: Filter

    Destination

    container

    A container for information about where to publish the inventory results.

    OSSBucketDestination

    container

    A container for the OSS bucket where the inventory results are stored.

    Ancestor: Destination

    Format

    string

    The format of the inventory file.

    Valid value: CSV

    Ancestor: OSSBucketDestination

    AccountId

    string

    The ID of the Alibaba Cloud account that owns the destination bucket.

    Ancestor: OSSBucketDestination

    RoleArn

    string

    The Alibaba Cloud Resource Name (ARN) of the RAM role that OSS assumes to write to the destination bucket.

    Format: acs:ram::uid:role/rolename

    Ancestor: OSSBucketDestination

    Bucket

    string

    The destination bucket where the inventory file is stored.

    Ancestor: OSSBucketDestination

    Prefix

    string

    The prefix to use for the inventory file path.

    Ancestor: OSSBucketDestination

    Encryption

    container

    A container for the server-side encryption configuration for the inventory file.

    Valid values: SSE-OSS, SSE-KMS, or empty

    Ancestor: OSSBucketDestination

    SSE-OSS

    container

    A container for the server-side encryption configuration that uses OSS-managed keys (SSE-OSS).

    Ancestor: Encryption

    SSE-KMS

    container

    A container for the server-side encryption configuration that uses KMS-managed keys (SSE-KMS).

    Ancestor: Encryption

    KeyId

    string

    The ID of the KMS master key.

    Ancestor: SSE-KMS

    Schedule

    container

    A container for the schedule for generating the inventory.

    Frequency

    string

    Determines how often the inventory is generated.

    Valid values: Daily, Weekly, Monthly, Once

    Ancestor: Schedule

    DayOfMonth

    positive integer

    The day of the month to generate the inventory when Frequency is set to Monthly. Valid values are positive integers from 1 to 31.

    Ancestor: Schedule

    AutoDelete

    boolean

    Indicates whether to automatically delete the inventory configuration after it runs once. This parameter is valid only when Frequency is set to Once.

    Valid values: true, false

    Ancestor: Schedule

    IncludedObjectVersions

    string

    Determines which object versions to include in the inventory.

    Valid values: All, Current

    • All: Includes all versions of an object.

    • Current: Includes only the current version of an object.

    OptionalFields

    container

    A container for the optional fields to include in the inventory.

    Field

    string

    The optional fields to include in the inventory.

    Optional fields: Size, LastModifiedDate, TransitionTime, ETag, StorageClass, IsMultipartUploaded, EncryptionStatus, ObjectAcl, TaggingCount, ObjectType, and Crc64

    Ancestor: OptionalFields

    IncrementalInventory

    container

    A container for the incremental inventory configuration.

    IsEnabled

    boolean

    Indicates whether to enable incremental inventory.

    Valid values:

    • true: Enables incremental inventory.

    • false: Disables incremental inventory.

    If this parameter is set to true, incremental inventory is enabled even if the parent IsEnabled parameter is false.

    Ancestor: IncrementalInventory

    Schedule

    container

    A container for the schedule for generating the incremental inventory.

    Ancestor: IncrementalInventory

    Frequency

    positive integer

    The frequency, in seconds, at which the incremental inventory is generated.

    The system currently uses a fixed period of 600 seconds. During each period, the system automatically creates a directory prefix and generates a manifest file and multiple CSV files for that period. Custom frequency settings are not supported.

    Ancestor: Schedule

    OptionalFields

    container

    A container for the optional fields to include in the incremental inventory.

    Ancestor: IncrementalInventory

    Field

    string

    The optional fields to include in the incremental inventory.

    Ancestor: OptionalFields

    • SequenceNumber: The sequence number. It is a unique identifier for each record. Records that belong to the same bucket and object can be sorted by SequenceNumber, which typically places them in chronological order.

    • RecordType: Record type: CREATE, UPDATE_METADATA, DELETE

      • CREATE: Includes all upload operations under the selected prefix, such as PutObject, PostObject, AppendObject, MultipartUpload, and CopyObject.

      • UPDATE_METADATA: Includes all metadata updates for objects under the selected prefix.

      • DELETE: Includes all delete operations for objects under the selected prefix, such as DeleteObject, DeleteMultipleObjects, the creation of a delete marker when versioning is enabled, and lifecycle-based deletions. Deletions can be either creating a delete marker or permanently deleting an object. For permanent deletions, the record retains only the following core fields: Bucket, Key, SequenceNumber, RecordType, RecordTimestamp, and VersionId. All other columns are null.

    • RecordTimestamp: The timestamp is in Greenwich Mean Time and is accurate to the millisecond. Example: "2024-08-25 18:08:01.024".

    • Requester: The Alibaba Cloud ID or Principal ID of the requester.

    • RequestId: The unique identifier for the request.

    • SourceIp: The source IP address of the requester.

    • Key: The name of the object in the bucket, which is URL-encoded.

    • VersionId: The version ID of the Object. This field is included only if the inventory rule is configured to export all versions.

      • If versioning is not enabled on the bucket, this field is empty.

      • If versioning is enabled on the bucket, this field contains the object's version ID.

    • IsDeleteMarker: Specifies whether the object version is a delete marker. This field is included only when the inventory rule is configured to export all versions.

      • If versioning is not enabled on the bucket, this field defaults to false.

      • If versioning is enabled on the bucket, this field is true for a delete marker and false otherwise.

    • Size: The size of the Object.

    • StorageClass: The storage class of the object.

    • LastModifiedDate: The last modified time of the object.

    • ETag: The ETag of an object. An ETag is generated when the object is created to identify the content of the object.

      • For an object created by using the PutObject operation, the ETag is the MD5 hash of the object content.

      • For an object created by using other methods, the ETag is a unique value generated based on specific rules and is not the MD5 hash of the object's content.

    • IsMultipartUploaded: Indicates whether the Object was uploaded by using multipart upload.

    • ObjectType: The object type.

    • ObjectAcl: The read and write permissions of the Object.

    • Crc64: The CRC64 of the Object.

    • EncryptionStatus: Indicates whether the Object is encrypted.

    Examples

    • Example request 

      GET /?inventory&inventoryId=list1 HTTP/1.1

    • Example response 

        HTTP/1.1 200 OK
  x-oss-request-id: 56594298207FB304438516F9
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Server: AliyunOSS
  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:::bucket_0001</Bucket>
           <Prefix>prefix1</Prefix>
           <Encryption>
              <SSE-OSS/>
           </Encryption>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Daily</Frequency>
     </Schedule>
     <Filter>
       <Prefix>myprefix/</Prefix>
     </Filter>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
  </InventoryConfiguration>

    SDKs

    This operation is available in the following SDKs:

    ossutil CLI

    For information about the corresponding ossutil command, see get-bucket-inventory.