Object Operations

Last updated: 2020-06-17 17:34:30

    Overview

    This document provides an overview of APIs and SDK code samples related to simple operations and other object operations.

    Simple operations

    API Operation Description
    GET Bucket (List Objects) Querying an object list Queries some or all objects in a bucket
    PUT Object Uploads an object using simple upload Uploads an object to a bucket
    POST Object Uploading an object using a form Uploads an object using a form request
    HEAD Object Querying object metadata Queries the metadata of an object
    GET Object Downloading an object Downloads an object
    OPTIONS Object Configuring pre-flight requests for cross-origin access Sends a pre-flight request to confirm whether a real cross-origin access request can be sent
    PUT Object - Copy Copying an object Copies an object to a destination path (object key)
    DELETE Object Deleting a single object Deletes a specified object from a bucket
    DELETE Multiple Objects Deleting multiple objects Deletes multiple objects from a bucket in a single request

    Other operations

    API Operation Description
    POST Object restore Restoring an archived object Restores an archived object for access
    PUT Object acl Setting object ACL Sets the ACL of a specified object in a bucket
    GET Object acl Querying object ACL Queries the ACL of an object

    Simple operations

    Querying an object list

    Feature description

    This API is used to query some or all objects in a bucket.

    Use case

    Sample 1. List all the files in directory a.

    cos.getBucket({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',     /* Required */
        Prefix: 'a/', /*Optional*/
    }, function(err, data) {
        console.log(err || data.Contents);
    });

    Response:

    {
        "Name": "examplebucket-1250000000",
        "Prefix": "",
        "Marker": "a/",
        "MaxKeys": "1000",
        "Delimiter": "",
        "IsTruncated": "false",
        "Contents": [{
            "Key": "a/3mb.zip",
            "LastModified": "2018-10-18T07:08:03.000Z",
            "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
            "Size": "3145728",
            "Owner": {
                "ID": "1250000000",
                "DisplayName": "1250000000"
            },
            "StorageClass": "STANDARD"
        }],
        "statusCode": 200,
        "headers": {}
    }

    Sample 2. List the files in directory a without deep traversal.

    cos.getBucket({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Prefix: 'a/', /*Optional*/
        Delimiter: '/',            /* Optional */
    }, function(err, data) {
        console.log(err || data.CommonPrefixes);
    });

    Response:

    {
        "Name": "examplebucket-1250000000",
        "Prefix": "a/",
        "Marker": "",
        "MaxKeys": "1000",
        "Delimiter": "/",
        "IsTruncated": "false",
        "CommonPrefixes": [{
            "Prefix": "a/1/"
        }],
        "Contents": [{
            "Key": "a/3mb.zip",
            "LastModified": "2018-10-18T07:08:03.000Z",
            "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
            "Size": "3145728",
            "Owner": {
                "ID": "1250000000",
                "DisplayName": "1250000000"
            },
            "StorageClass": "STANDARD"
        }],
        "statusCode": 200,
        "headers": {}
    }

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    - Prefix Matching prefix for object keys, which sets that the response only contains object keys with the specified prefix. String No
    Delimiter A separating symbol (usually \) used to group object keys. The identical paths between a prefix or, if no prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix. All common prefixes will be listed. String No
    Marker Marks the starting object key. Object key entries will be returned in UTF-8 lexicographical order starting from the first object key after the marker String No
    MaxKeys Maximum number of entries returned at a time; the default value is 1,000 String No
    encoding-type Inidcates the encoding method of the returned value. Valid value: url, which means that the returned object keys are URL-encoded (percent-encoded) values. For example, "Tencent Cloud" will be encoded as Tencent%20Cloud. String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Object returned when the request is successful. If the request fails, this is null. Object
    - headers Headers returned by the request Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - Name Bucket name in the format: BucketName-APPID, such as examplebucket-1250000000 String
    - Prefix Matching prefix for object keys. Object key entries will be returned in UTF-8 lexicographical order starting from the first object key after the prefix String
    - Marker Marks for the starting object key. Object key entries will be returned in UTF-8 lexicographical order starting from the first object key after the marker String
    - MaxKeys Maximum number of results returned in one response String
    - Delimiter Delimiter String
    - IsTruncated Indicates whether the returned request entries are truncated. Valid values: true, false String
    - NextMarker If the returned entries are truncated, then NextMarker is the starting point of the next entry String
    - CommonPrefixes The identical paths between a specified prefix and the delimiter are grouped and defined as a common prefix ObjectArray
    - - Prefix A single common prefix String
    - EncodingType Indicates the encoding method of the returned value, which is effective for Delimiter, Marker, Prefix, NextMarker, and Key String
    - Contents Metadata ObjectArray
    - - Key Object name, i.e., object key String
    - - ETag MD5 checksum of the file, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end String
    - - Size Part size in bytes String
    - - LastModified Describes the time the object was last modified in ISO8601 format, such as 2019-05-24T10:56:40Z String
    - - Owner Object owner information Object
    - - - ID Complete ID of the object owner. Format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], such as qcs::cam::uin/100000000001:uin/100000000001,where 100000000001 is uin String
    - - - DisplayName Part owner name String
    - - StorageClass Sets the object storage class. Enumerated values: STANDARD, STANDARD_IA and ARCHIVE. For more information, see Storage Class String

    Uploading an object using simple upload

    Feature description

    This API is used to upload an object to a bucket. To make this request, you need to have write permission for the bucket.

    1. The Key (file name) cannot end with /; otherwise, it will be identified as a folder.
    2. Each root account (APPID) can have up to 1,000 bucket ACL rules, and an unlimited number of object ACL rules. If you do not need access control for an object, do not make the configuration when uploading it, and the object will inherit the permissions of its bucket.
    3. After an object is uploaded, you can use the same key to generate a pre-signed link, which can be shared with others for download. However, please note that if your file is set to private-read, the pre-signed link will only be valid for a certain period of time. To download, please specify the method as GET. For API details, see below.

    Use case

    Upload a string as the file content:

    cos.putObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        Body: 'hello!',
    }, function(err, data) {
        console.log(err || data);
    });

    Create a directory:

    cos.putObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'a/', /*Required*/
        Body: '',
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview String Yes
    Body Text content of the created file, which can be a string String Yes
    CacheControl Cache policy as defined in RFC 2616, which will be stored in the object metadata String No
    ContentDisposition Filename as defined in RFC 2616, which will be stored in the object metadata String No
    ContentEncoding Encoding format as defined in RFC 2616, which will be stored in the object metadata String No
    ContentLength HTTP request length in bytes as defined in RFC 2616 String No
    ContentType Content type (MIME) as defined in RFC 2616, which will be stored in the object metadata String No
    Expires Expiration time as defined in RFC 2616, which will be stored in the object metadata String No
    Expect If Expect: 100-continue is used, the request content will be sent only after confirmation from the server is received String No
    ACL Defines the access control list (ACL) attribute of the object. For the enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set default for this parameter or simply leave it blank, and the object will inherit the permissions of the bucket
    String No
    GrantRead Grants the user read access in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantReadAcp Grants the user read access to the object’s ACL in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
  • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    GrantWriteAcp Grants the user write access to the object’s ACL in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
  • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    GrantFullControl Grants the user full permission in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
  • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    x-cos-meta-* Headers that allow user customization; they will be stored in the object metadata; maximum size: 2 KB String No
    TaskReady Callback function when an upload task is created. The callback returns a taskId, which uniquely identifies the task and can be used to cancel (cancelTask), pause (pauseTask), or restart (restartTask) the task Function No
    - taskId Upload task number String No
    onProgress Progress callback function. Attributes of the progress callback response object, progressData, are as follows Function No
    - progressData.loaded Size of the file part that has been uploaded in bytes Number No
    - progressData.total Total file size in bytes Number No
    - progressData.speed File upload speed in bytes/s Number No
    - progressData.percent Percentage of the file upload progress in decimal form; for example, 0.5 means 50% downloaded Number No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ETag Returns the MD5 checksum of the file. The value of ETag can be used to check whether the object was corrupted during upload.
    For example, "09cba091df696af91549de27b8e7d0f6". Note: double quotation marks are required at the beginning and the end of the ETag value string
    String
    - Location Creates an object's access domain name for external networks String
    - VersionId The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned String

    Uploading an object using a form

    This API is used to upload a file (object) selected by the user through wx.chooseImage to a specified bucket. To make this request, you need to have write permission for the bucket.

    Use case

    Upload a file using simple upload

    cos.postObject({
        Bucket: 'examplebucket-1250000000',
        Region: 'ap-beijing',
        Key: filename,
        FilePath: tmpFilePath, // tmpFilePath obtained when you select the file through wx.chooseImage
        onProgress: function (info) {
            console.log(JSON.stringify(info));
        }
    }, function (err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview String Yes
    ContentLength HTTP request length in bytes as defined in RFC 2616 String Yes
    CacheControl Cache policy as defined in RFC 2616, which will be stored in the object metadata String No
    ContentDisposition Filename as defined in RFC 2616, which will be stored in the object metadata String No
    ContentEncoding Encoding format as defined in RFC 2616, which will be stored in the object metadata String No
    ContentType Content type (MIME) as defined in RFC 2616, which will be stored in the object metadata String No
    Expires Expiration time as defined in RFC 2616, which will be stored in the object metadata String No
    Expect If Expect: 100-continue is used, the request content will be sent only after confirmation from the server is received String No
    ACL Defines the access control list (ACL) attribute of the object. For the enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set default for this parameter or simply leave it blank, and the object will inherit the permissions of the bucket
    String No
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    x-cos-meta-* Headers that allow user customization; they will be stored as the object metadata; maximum size: 2 KB String No
    FilePath Temporary file path of the file to be uploaded, which can be obtained by selecting the file through wx.chooseImage String Yes
    onProgress Progress callback function. The first parameter in a callback is the progressData object Function No
    - progressData.loaded Size of the file part that has been downloaded in bytes Number No
    - progressData.total Total file size in bytes Number No
    - progressData.speed File download speed in bytes/s Number No
    - progressData.percent Percentage of the file download progress in decimal form; for example, 0.5 means 50% downloaded Number No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ETag Returns the MD5 checksum of the object. The value of ETag can be used to check whether the object was corrupted during upload.
    For example, "09cba091df696af91549de27b8e7d0f6". Note: double quotation marks are required at the beginning and the end of the ETag value string
    - Location Creates an object's access domain name for external networks String
    - VersionId The version ID of the returned object in a versioning-enabled bucket String

    Querying object metadata

    Feature description

    This API is used to query the metadata of an object.

    Use case

    cos.headObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',               /* Required */
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    IfModifiedSince Returns the object metadata if the object is modified after the specified time, otherwise an HTTP 304 (Not Modified) status code is returned String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200 and 304. If no modification is made after the specified time, 304 will be returned Number
    - headers Headers returned by the request Object
    - x-cos-object-type Indicates whether an object can be appended to an upload operation. Enumerated values: normal, appendable String
    - x-cos-storage-class Object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD, which is not displayed in the response String
    - x-cos-meta-* User-defined metadata String
    - NotModified Indicates whether an object is unmodified after the specified time Boolean
    - ETag Returns the MD5 checksum of the file. The value of ETag can be used to check whether the object was corrupted during upload.
    For example, "09cba091df696af91549de27b8e7d0f6". Note: double quotation marks are required at the beginning and the end of the ETag value string
    String
    - VersionId The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned String

    Downloading an object

    This API is used to get the content, in string format, of a specified file in a bucket.

    Use case

    cos.getObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
    }, function(err, data) {
        console.log(err || data.Body);
    });

    Get file content with Range specified:

    cos.getObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        Range: 'bytes=1-3', /*Optional*/
    }, function(err, data) {
        console.log(err || data.Body);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    ResponseContentType Sets the Content-Type parameter in the response headers String No
    ResponseContentLanguage Sets the Content-Language parameter in the response headers String No
    ResponseExpires Sets the Content-Expires parameter in the response headers String No
    ResponseCacheControl Sets the Cache-Control parameter in the response headers String No
    ResponseContentDisposition Sets the Content-Disposition parameter in the response headers String No
    ResponseContentEncoding Sets the Content-Encoding parameter in the response headers String No
    Range Byte range of the object as defined in RFC 2616. This value must be in the format of bytes=first-last, where both first and last are offsets starting from 0. For example, bytes=0-9 means that you want to download the first 10 bytes of data of the source object. If this parameter is not specified, the entire object will be downloaded String No
    IfModifiedSince Returns the object metadata if the object is modified after the specified time; otherwise, an HTTP 304 (Not Modified) status code is returned String No
    IfUnmodifiedSince Returns the object if the object is not modified after the specified time; otherwise, an HTTP 412 (Precondition Failed) status code is returned String No
    IfMatch Returns the object only if the ETag matches the specified content; otherwise, an HTTP 412 (Precondition Failed) status code is returned String No
    IfNoneMatch Returns the object only if the ETag does not match the specified content; otherwise, an HTTP 304 (Not Modified) status code is returned String No
    VersionId Version ID of the object to be downloaded String No
    onProgress Progress callback function. Attributes of the progress callback response object, progressData, are as follows Function No
    - progressData.loaded Size of the file part that has been downloaded; unit: byte Number No
    - progressData.total Size of the entire object in bytes Number No
    - progressData.speed Object download speed in bytes/s Number No
    - progressData.percent Percentage of the file download progress; for example, 0.5 means 50% downloaded Number No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    Cache-Control Cache directives as defined in RFC 2616, which will be returned only if it is contained in the object metadata or specified through the request parameter string
    Content-Disposition Filename as defined in RFC 2616, which will be returned only if it is contained in the object metadata or specified through the request parameter string
    Content-Encoding Encoding format as defined in RFC 2616, which will be returned only if it is contained in the object metadata or specified through the request parameter string
    Expires Cache expiration time as defined in RFC 2616, which will be returned only if it is contained in the object metadata or specified through the request parameter string
    - x-cos-storage-class Storage class of the object. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE
    Note: if this header is not returned, it means the file storage class is STANDARD (standard storage)
    String
    - x-cos-meta-* User-defined metadata String
    - NotModified If the request contains IfModifiedSince, then the attributes of IfModifiedSince will be returned. If the file has been modified, false will be returned. If not, true will be returned Boolean
    - ETag Returns the MD5 checksum of the file. The value of ETag can be used to check whether the object was corrupted during upload.
    For example, "09cba091df696af91549de27b8e7d0f6". Note: double quotation marks are required at the beginning and the end of the ETag value string
    String
    - VersionId The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned String
    - Body Returned file content. Uses the String format by default. String

    Configuring pre-flight requests for cross-origin access

    Feature description

    This API (OPTIONS Object) is used to implement a pre–flight request for the cross-origin access configuration of an object. Before making a real cross-origin resource sharing (CORS) request, you can send an OPTIONS request carrying the specific source origin, HTTP method, and header information to COS for it to determine whether a real request can be sent. If there is no CORS configuration, an HTTP 403 Forbidden status code be returned. You can enable CORS for a bucket using the PUT Bucket cors API.

    Use case

    cos.optionsObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        Origin: 'https://www.qq.com', /*Required*/
        AccessControlRequestMethod: 'PUT', /*Required*/
        AccessControlRequestHeaders: 'origin,accept,content-type' /*Optional*/
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    Origin Source origin of the simulated cross-origin access request String Yes
    AccessControlRequestMethod HTTP method of the simulated cross-origin access request String Yes
    AccessControlRequestHeaders Headers of the simulated cross-origin access request String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - headers Headers returned by the request Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - AccessControlAllowOrigin Source origins of the simulated cross-origin access request separated by commas. This header will not be returned if the origins are not allowed. Example: * String
    - AccessControlAllowMethods HTTP methods of the simulated cross-origin access request separated by commas, such as PUT, GET, POST, DELETE, and HEAD. This header will not be returned if the request method is not allowed String
    - AccessControlAllowHeaders Headers of the simulated cross-origin access request separated by commas, such as accept, content-type, origin, and authorization. This request header will not be returned if any of the simulated headers is not allowed String
    - AccessControlExposeHeaders Response headers supported by CORS, such as ETag. The headers are separated by commas String
    - AccessControlMaxAge Sets the validity period of the OPTIONS request result, such as 3600 String
    - OptionsForbidden Indicates whether the OPTIONS request is forbidden; if the returned HTTP status code is 403, this value is true. Boolean

    Copying an object

    Feature description

    This API is used to create a copy of an existing COS object, that is, an object is copied from the source path (object key) to the destination path (object key). During replication, object metadata and access control lists (ACLs) can be modified.
    Users can use this API to create a copy, modify object metadata (the source object and destination file have the same attributes), and move or rename the object (first copy the object, and then call the delete API separately).

    We recommend an object size between 1MB-5GB. For objects greater than 5GB, please use the advanced APIs to copy the object [Slice Copy File] (#. E5.A4.8D.E5.88.B6.E5.AF.B9.E8.B1.A12) .

    Use case

    cos.putObjectCopy({
        Bucket: 'examplebucket-1250000000', /*Required*/
        Region: 'ap-beijing',                                  /* Required */
        Key: 'picture.jpg',                                            /* Required */
        CopySource: 'test-1250000000.cos.ap-guangzhou.myqcloud.com/2.jpg', /* Required */
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    CopySource URL path to the source object. A past object version can be specified with the URL parameter ?versionId=&lt;versionId> String Yes
    ACL Defines the access control list (ACL) attribute of the object. For the enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set default for this parameter or simply leave it blank, and the object will inherit the permissions of the bucket
    String No
    GrantRead Grants the user read permission in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantWrite Grants the user write permission in the format: id="[OwnerUin]".
    You can use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantFullControl Grants the user full permission in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    MetadataDirective Indicates whether to copy the metadata. Enumerated values: Copy, Replaced. Default value: Copy. If you specify this parameter as Copy, the user metadata in the corresponding header will be ignored and the copy operation will be performed; if you specify this parameter as Replaced, the metadata will be replaced by the information in the corresponding header. If the destination path is the same as the source path, which means you want to modify the metadata, you must specify this parameter as Replaced String No
    CopySourceIfModifiedSince If the object is modified after the specified time, the operation will be performed; otherwise, an HTTP 412 status code will be returned. This parameter can be used together with CopySourceIfNoneMatch. If it is used together with other conditions, a conflict will be returned String No
    CopySourceIfUnmodifiedSince If the object is not modified after the specified time, the operation will be performed; otherwise, an HTTP 412 status code will be returned. This parameter can be used together with CopySourceIfMatch. If it is used together with other conditions, a conflict will be returned String No
    CopySourceIfMatch If the Etag of the object is the same as the specified one, the operation will be performed; otherwise, a an HTTP 412 status code will be returned. This parameter can be used together with CopySourceIfUnmodifiedSince. If it is used together with other conditions, a conflict will be returned String No
    CopySourceIfNoneMatch If the Etag of the object is different from the specified one, the operation will be performed; otherwise, an HTTP 412 status code will be returned. This parameter can be used together with CopySourceIfModifiedSince. If it is used together with other conditions, a conflict will be returned string No
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    x-cos-meta-* Other user-defined file headers String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ETag MD5 checksum of the file, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end String
    - LastModified Describes the time the object was last modified, such as 2017-06-23T12:33:27.000Z String
    - VersionId The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned String

    Deleting a single object

    Feature description

    This API is used to delete an object from a COS bucket. To make this request, you need to have write permission for the bucket.

    Use case

    cos.deleteObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg'                            /* Required */
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID. String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    - VersionId Version ID of the object or delete marker to be deleted String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 204, 403, and 404. If the deletion is successful or the file does not exist, an HTTP 204 or 200 status code will be returned; if the specified bucket is not found, an HTTP 404 status code will be returned Number
    - headers Headers returned by the request Object

    Deleting multiple objects

    Feature description

    This API is used to delete multiple objects from a bucket in a single request. You can delete up to 1,000 objects in a single request. For the response, there are two modes for you to choose from: Verbose and Quiet. Verbose mode returns the information on the deletion of each object, whereas Quiet mode only returns the information on objects for which errors are reported.

    Use case

    Deleting multiple files:

    cos.deleteMultipleObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Objects: [
            {Key: 'picture.jpg'},
            {Key: '2.zip'},
        ]
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Quiet A boolean value which determines whether to use Quiet mode. If the value is true, Quiet mode will be used; if it is false, Verbose mode will be used. Default value: false Boolean No
    Objects List of files to be deleted ObjectArray Yes
    - Key ObjectKey (object name) is the unique identifier of an object in a bucket. For more information, see Object Overview. String Yes
    - VersionId Version ID of the object or delete marker to be deleted String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - Deleted List of object information indicating successful deletion ObjectArray
    - - Key ObjectKey (object name) is the unique identifier of an object in a bucket. For more information, see Object Overview. String
    - - VersionId If the VersionId parameter is passed in, it will also be included in the response, indicating the version of the object or delete marker String
    - - DeleteMarker If versioning is enabled and the VersionId parameter is not specified, the deletion will not actually erase the content of the file; instead, it will only add a new delete marker, indicating that the visible file has been deleted. Enumerated values: true, false String
    - - DeleteMarkerVersionId If the value of the returned DeleteMarker is true, this parameter will be returned, representing the VersionId of the newly added delete marker String
    - Error List of object information indicating deletion failure ObjectArray
    - - Key ObjectKey (object name) is the unique identifier of an object in a bucket. For more information, see Object Overview. String
    - - Code Deletion failure error codes String
    - - Message Deletion failure error messages String

    Other Operations

    Restoring an archived object

    Feature description

    This API is used to restore an object archived by COS. The restored readable object is temporary, and you can configure the object to keep it readable and set the time when you want it to be deleted. You can use the Days parameter to specify the expiration time of the temporary object. If the object expires and you have not initiated any operation to copy the object or extend its validity period before it expires, the temporary object will be automatically deleted. A temporary object is only a copy of the source archived object and the source object will exist throughout this period.

    Use case

    cos.restoreObject({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',
        RestoreRequest: {
            Days: 1,
            CASJobParameters: {
                Tier: 'Expedited'
            }
        },
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name                              Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    RestoreRequest Container for data restoration Object Yes
    - Days Sets the expiration time of a temporary copy Number Yes
    - CASJobParameters Container of the Cloud Archive Storage job parameters Object Yes
    - - Tier This parameter can be specified as one of the three data restoration modes supported by COS: Standard, which completes a restoration job in 3-5 hours; Expedited, which completes a restoration job in 15 minutes; and Bulk, which completes multiple restoration jobs in 5-12 hours. String Yes

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object

    Setting object ACL

    Feature description

    This API is used to set the access control list (ACL) of an object in a specific bucket.

    The total number of policies associated with bucket ACL, Policy, and CAM under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, do not make any configuration, and the object will inherit the permissions of its bucket.

    Use case

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        ACL: 'public-read', /*Optional*/
    }, function(err, data) {
        console.log(err || data);
    });

    Grant a user all permissions to an object:

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        GrantFullControl: 'id="100000000001"' // 100000000001 is the UIN of the root account
    }, function(err, data) {
        console.log(err || data);
    });

    Grant an object write permissions via AccessControlPolicy:

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
        AccessControlPolicy: {
            "Owner": { // `Owner` is required in `AccessControlPolicy`
                "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
            },
            "Grants": [{
                "Grantee": {
                    "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
                },
                "Permission": "WRITE"
            }]
        }
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes
    ACL Defines the access control list (ACL) attribute of the object. For the enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set default for this parameter or simply leave it blank, and the object will inherit the permissions of the bucket
    String No
    GrantRead Grants the user read permission in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
  • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    GrantFullControl Grants the user full permission in the format: id="[OwnerUin]". You can use a comma (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
  • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    AccessControlPolicy Sets an object's access control list (ACL) attributes Object No
    - Owner Object owner information Object No
    - - - ID Object owner ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    For root accounts, &lt;OwnerUin> and &lt;SubUin> have the same value
    String No
    - - - DisplayName Object owner name String
    - Grants List of information on the authorized user and granted permissions ObjectArray No
    - - Permission Specifies the permission granted to the authorized user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String No
    - - Grantee Authorized user’s information Object No
    - - - DisplayName Grantee Name String No
    - - - ID Authorized user’s ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    For root accounts, &lt;OwnerUin> and &lt;SubUin> have the same value.
    String No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object

    Querying object ACL

    Feature description

    This API is used to query the access permissions of a specified object in a specified bucket. Only the bucket owner has the permission to perform this operation.

    Use case

    cos.getObjectAcl({
        Bucket: 'examplebucket-1250000000',  /* Required */
        Region: 'ap-beijing',    /* Required */
        Key: 'picture.jpg',              /* Required */
    }, function(err, data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String Yes

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Object returned when the request is successful. If the request fails, this is null. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ACL Defines the access control list (ACL) attributes of the object. For the enumerated values such as private and public-read, see the “Preset ACL for buckets” section in ACL Overview. Default value: private String
    - Owner Identifies the owner of the resource Object
    - - - ID Object owner ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    For root accounts, &lt;OwnerUin> and &lt;SubUin> have the same value
    String
    - - DisplayName Object owner name String
    - Grants List of information on the authorized user and granted permissions ObjectArray
    - - Permission Specifies the permission granted to the authorized user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String
    - - Grantee Authorized user’s information Object
    - - - DisplayName User Name String
    - - - ID User ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    For root accounts, &lt;OwnerUin> and &lt;SubUin> have the same value
    String

    Advanced APIs (recommended)

    The following methods encapsulate the native methods mentioned above. They can be used to implement the complete multipart replication process and support concurrent multipart replications, checkpoint restart, as well as cancelling, pausing, and restarting replication tasks.

    Copying an object

    Feature description

    This API (Slice Copy File) is used to copy a file from a source path to a destination path through multipart copy. Object metadata and ACL can be modified during the copy process. You can use this API to move, rename, and copy a file or modify its attributes.

    Method prototype

    Call Slice Copy File:

    cos.sliceCopyFile({
        Bucket: 'examplebucket-1250000000', /*Required*/
        Region: 'ap-beijing',                                  /* Required */
        Key: '1.zip',                                            /* Required */
        CopySource: 'test-1250000000.cos.ap-guangzhou.myqcloud.com/2.zip', /* Required */
        onProgress:function (progressData) { /*Optional*/
            console.log(JSON.stringify(progressData));
        }
    },function (err,data) {
        console.log(err || data);
    });

    Parameter description

    Parameter Name                              Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
    Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview String Yes
    CopySource URL path to the source object. A past object version can be specified with the URL parameter ?versionId=\<versionId> String Yes
    ChunkSize Size of each part in the multipart copy in bytes. Default value: 1,048,576 (1 MB) Number No
    SliceSize Indicates the file size threshold in bytes for a multipart replication operation. Default value: 5 G. If a file is smaller than or equal to 5 G, it will be uploaded using putObjectCopy; otherwise, sliceCopyFile will be used. Number No
    onProgress File upload progress callback function. The callback parameter is the object in progress progressData Function No
    - progressData.loaded Size of the file part that has been uploaded in bytes Number No
    - progressData.total Total file size in bytes Number No
    - progressData.speed File upload speed in bytes/s Number No
    - progressData.percent Percentage of the file upload progress in decimal form; for example, 0.5 means 50% uploaded Number No

    Callback function description

    function(err, data) { ... }
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Data returned when the request is successful. If the request fails, this is null Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - Location Creates an object's access domain name for external networks String
    - Bucket Destination bucket for the multipart upload String
    - Key ObjectKey (object name) is the unique identifier of an object in a bucket. For more information, see Object Overview. String
    - ETag MD5 checksum of the merged file.
    Example: "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end
    String
    - VersionId The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned String

    Upload queue

    The SDK for Wechat Mini Programs records all the putObject upload tasks in a queue; relevant queue operations are as follows:

    1. Use cos.getTaskList to get the task list.
    2. Use cos.pauseTask, cos.restartTask, and cos.cancelTask to perform operations on upload tasks.
    3. Use cos.on('list-update', callback); to monitor changes in the list and the upload progress.

    For a complete example of queue usage, see the [demo] (https://github.com/tencentyun/cos-js-sdk-v5/tree/master/demo/queue).

    Canceling an upload task

    This API cancels an upload task by taskId.

    Use case

    var taskId = 'xxxxx';                   /* Required */
    cos.cancelTask(taskId);

    Parameter description

    Parameter Name Description Type Required
    taskId ID of an upload task. When putObject is called, the TaskReady callback will return the taskId of the upload task. String Yes

    Suspending an upload task

    This API suspends an upload task by taskId.

    Use case

    var taskId = 'xxxxx';                   /* Required */
    cos.pauseTask(taskId);

    Parameter description

    Parameter Name Description Type Required
    taskId ID of an upload task. When putObject is called, the TaskReady callback will return the taskId of the upload task. String Yes

    Restarting an upload task

    This API restarts an upload task by taskId. You can restart tasks that have been manually suspended through the pauseTask API, or automatically suspended due to an upload error.

    Use case

    var taskId = 'xxxxx';                   /* Required */
    cos.restartTask(taskId);

    Parameter description

    Parameter Name Description Type Required
    taskId ID of an upload task. When putObject is called, the TaskReady callback will return the taskId of the upload task. String Yes

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help