Help & Documentation>Cloud Object Storage>SDK Documentation>Node.js SDK>Data Management>Inventory

Inventory

Last updated: 2023-09-13 11:39:59

On this page:

Feature Overview

This document provides an overview of APIs and SDK code samples for COS inventory.
API
Operation
Description
Setting an inventory job
Sets an inventory job for a bucket
Querying Inventory Jobs
Queries the inventory jobs of a bucket
Deleting an Inventory Job
Deletes an inventory job from a bucket

Setting an inventory job

Note

This API is used to create an inventory job for a bucket. For more information, see Inventory Overview.
Note
Up to 1,000 inventory tasks can be configured in one COS bucket.
You must write a bucket policy to the destination bucket for COS to put the result file of the inventory task in it.
When calling this request, make sure that you have sufficient permission to manipulate the bucket's inventory tasks, which is granted to the bucket owner by default. If you do not have it, apply for it to the bucket owner first.

Sample Request

Sample 1. Creating an inventory job with server-side encryption.
cos.putBucketInventory({
    Bucket: 'sourcebucket-1250000000', /* Required */
    Region: 'ap-beijing',               /* Required */
    Id: 'inventory_test',       // Required
    InventoryConfiguration: {
        Id: 'inventory_test',
        IsEnabled: 'true',
        Destination: {
            COSBucketDestination: {
                Format: 'CSV',
                AccountId: '100000000001',
                Bucket: 'qcs::cos:ap-beijing::targetbucket-1250000000',
                Prefix: 'inventory_test_prefix',
                Encryption: {
                    SSECOS: ''
}
}
        },
        Schedule: {
            Frequency: 'Daily'
        },
        Filter: {
            Prefix: 'filter_prefix'
        },
        IncludedObjectVersions: 'All',
        OptionalFields: [
            'Size',
            'LastModifiedDate',
            'StorageClass',
            'ETag'
        ]
}
}, function(err, data) {
    console.log(err || data);
});
Sample 2. Creating an inventory job without server-side encryption.
cos.putBucketInventory({
    Bucket: 'sourcebucket-1250000000', /* Required */
    Region: 'ap-beijing',               /* Required */
    Id: 'inventory_test',       // Required
    InventoryConfiguration: {
        Id: 'inventory_test',
        IsEnabled: 'true',
        Destination: {
            COSBucketDestination: {
                Format: 'CSV',
                AccountId: '100000000001',
                Bucket: 'qcs::cos:ap-beijing::targetbucket-1250000000',
                Prefix: 'inventory_test_prefix'
}
        },
        Schedule: {
            Frequency: 'Daily'
        },
        Filter: {
            Prefix: 'filter_prefix'
        },
        IncludedObjectVersions: 'All',
        OptionalFields: [
            'Size',
            'LastModifiedDate',
            'StorageClass',
            'ETag'
        ]
}
}, function(err, data) {
    console.log(err || data);
});

Description

Parameter name
Description
Local Disk Types
Required
Bucket
Name of the bucket for which the inventory job is configured in the format: BucketName-APPID
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Id
Name of the inventory job.
Default value: None
Valid characters: a-z, A-Z, 0-9, -, _, .
String
Required
InventoryConfiguration
This contains configuration parameters of the inventory
Object
Required
- Id
Name of the inventory job.
Default value: None
Valid characters: a-z, A-Z, 0-9, -, _, .
String
Required
- IsEnabled
Indicates whether inventory is enabled. true indicates it is enabled; false indicates no inventory list will be generated.
String
Required
- IncludedObjectVersions
Whether to include object versions in the inventory
If set to "All", the inventory will include all object versions and will add the fields "VersionId", "IsLatest", and "DeleteMarker" to the inventory.
If set to Current, the inventory will not include object version information.
String
Required
- Filter
Filters the objects subject to the inventory job with the prefix specified in this parameter
Object
Not required
- - Prefix
Prefix of the objects to analyze
String
Not required
- OptionalFields
Name of the analysis items that can be optionally included in the inventory result. Optional fields include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus
Array
Not required
- Schedule
Inventory job cycle
Object
Required
- - Frequency
Frequency of the inventory job. Enumerated values: Daily, Weekly
String
Required
- Destination
Information about the inventory result destination
Object
Required
- - COSBucketDestination
Information about the bucket that stores the exported inventory result
Object
Required
- - - Bucket
Bucket name
String
Required
- - - AccountId
ID of the bucket owner, for example, 100000000001
String
Not required
- - - Prefix
The prefix for shipping inventory reports. COS automatically adds a '/' after the prefix you specify. For example, if you specify 'Prefix' as the prefix, COS will ship inventory reports to the path 'Prefix/inventory_report'.
String
Not required
- - - Format
Format of the inventory result. Valid value: CSV
String
Required
- - - Encryption
Server-side encryption for the inventory result
Object
Not required
- - - - SSECOS
Encryption with a COS-managed key. Left empty.
String
Not required

Callback function description

function(err, data) { ... }
Parameter name
Description
Local Disk Types
err
Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object returned when the request is successful. If the request fails, this parameter is empty.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object

Querying Inventory Jobs

Note

This API is used to query the inventory jobs of a bucket. To initiate this request, you need to provide the inventory job ID, and a request signature that indicates that the request has been permitted. For more information, see Inventory Overview.
Note
When calling this request, make sure that you have sufficient permission to manipulate the bucket's inventory tasks.
This permission is granted to the bucket owner by default. If you do not have it, apply for it to the bucket owner first.

Sample Request

cos.getBucketInventory({
    Bucket: 'sourcebucket-1250000000', /* Required */
    Region: 'ap-beijing',               /* Required */
    Id: 'inventory_test'                // Required
}, function(err, data) {
    console.log(err || data);
});

Sample response

{
    "InventoryConfiguration": {
        "Id":"inventory_test",
        "IsEnabled":"true",
        "Destination":{
            "COSBucketDestination": {
                "Format":"CSV",
                "AccountId":"100000000001",
                "Bucket":"qcs::cos:ap-beijing::targetbucket-1250000000",
                "Prefix":"inventory_test_prefix",
                "Encryption": {
                    "SSECOS":""
}
}
        },
        "Schedule": {
            "Frequency":"Daily"
        },
        "Filter": {
            "Prefix":"filter_prefix"
        },
        "IncludedObjectVersions":"All",
        "OptionalFields": [
            "Size",
            "LastModifiedDate",
            "StorageClass",
            "ETag"
        ]
}
    "statusCode": 200,
    "headers": {}
}

Description

Parameter name
Description
Local Disk Types
Required
Bucket
Name of the bucket for which the inventory job is queried in the format: BucketName-APPID
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Id
Name of the inventory job.
Default value: None
Valid characters: a-z, A-Z, 0-9, -, _, .
String
Required

Callback function description

function(err, data) { ... }
Parameter name
Description
Local Disk Types
err
Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Data returned when the request is successful. If the request fails, this is null.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
- InventoryConfiguration
This contains configuration parameters of the inventory
Object
- - Id
Name of the inventory job.
Default value: None
Valid characters: a-z, A-Z, 0-9, -, _, .
String
- - IsEnabled
Indicates whether inventory is enabled. true indicates it is enabled; false indicates no inventory list will be generated.
String
- - IncludedObjectVersions
Whether to include object versions in the inventory
If set to "All", the inventory will include all object versions and will add the fields "VersionId", "IsLatest", and "DeleteMarker" to the inventory.
If set to Current, the inventory will not include object version information.
String
- - Filter
Filters the objects subject to the inventory job with the prefix specified in this parameter
Object
- - - Prefix
Prefix of the objects to analyze
String
- - OptionalFields
Name of the analysis items that can be optionally included in the inventory result. Optional fields include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus
Array
- - Schedule
Inventory job cycle
Object
- - - Frequency
Frequency of the inventory job. Enumerated values: Daily, Weekly
String
- - Destination
Information about the inventory result destination
Object
- - - COSBucketDestination
Information about the bucket that stores the exported inventory result
Object
- - - - Bucket
Bucket name
String
- - - - AccountId
ID of the bucket owner, for example, 100000000001
String
- - - - Prefix
The prefix for shipping inventory reports. COS automatically adds a '/' after the prefix you specify. For example, if you specify 'Prefix' as the prefix, COS will ship inventory reports to the path 'Prefix/inventory_report'.
String
- - - - Format
Format of the inventory result. Valid value: CSV
String
- - - - Encryption
Server-side encryption for the inventory result
Object
- - - - - SSECOS
Encryption with a COS-managed key. Left empty.
String

Deleting an Inventory Job

Note

DELETE Bucket inventory is used to delete a specified inventory job in the storage bucket. Users must provide the name of the inventory job to be deleted. For a detailed introduction to inventory, please refer to Inventory Feature Overview.
Note
When calling this request, make sure that you have sufficient permission to manipulate the bucket's inventory tasks.
This permission is granted to the bucket owner by default. If you do not have it, apply for it to the bucket owner first.

Sample Request

cos.deleteBucketInventory({
    Bucket: 'sourcebucket-1250000000', /* Required */
    Region: 'ap-beijing',               /* Required */
    Id: 'inventory_test'                // Required
}, function(err, data) {
    console.log(err || data);
});

Description

Parameter name
Description
Local Disk Types
Required
Bucket
Name of the bucket from which the inventory job is deleted in the format: BucketName-APPID
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Domain Names
String
Required
Id
Inventory job name. Default value: None
Valid characters: a-z, A-Z, 0-9, -, _, .
String
Required

Callback function description

function(err, data) { ... }
Parameter name
Description
Local Disk Types
err
Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object returned when the request is successful. If the request fails, this parameter is empty.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object

中国站 - English