Object Operations

Last updated: 2020-06-12 15:05:23

    Overview

    This document provides an overview of APIs and SDK sample codes related to simple operations, multipart operations, and other object operations.

    Simple operations

    API Operation Description
    GET Bucket (List Object) Querying an object list Queries some or all objects in a bucket
    GET Bucket Object Versions Querying a list objects and their version history Queries some or all objects in a bucket and their version history
    PUT Object Uploads an object using simple upload Uploads an object to a bucket
    HEAD Object Querying object metadata Queries the metadata of an object
    GET Object Downloading an object Downloads an object to the local file system
    PUT Object - Copy Setting object replication Copies a file to the destination path
    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
    POST Object restore Restoring an archived object Restores an archived object for access

    Multipart operations

    API Operation Description
    List Multipart Uploads Querying a multipart upload Queries the information of a multipart upload in progress
    Initiate Multipart Upload Initializing a multipart upload Initializes a multipart upload task
    Upload Part Uploading parts Uploads a file in multiple parts
    Upload Part - Copy Copying a part Copies an object as a part
    List Parts Querying uploaded parts Queries the uploaded parts of a specified multipart upload operation
    Complete Multipart Upload Completing a multipart upload Completes the multipart upload of the entire file
    Abort Multipart Upload Aborting a multipart upload Aborts a multipart upload operation and deletes the uploaded parts

    Simple operations

    Querying an object list

    Feature description

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

    Method prototype

    list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)

    Sample request

    response = client.list_objects(
        Bucket='examplebucket-1250000000',
        Prefix='folder1'
    )

    Sample request for all parameters

    response = client.list_objects(
        Bucket='examplebucket-1250000000',
        Prefix='string',
        Delimiter='/',
        Marker='string',
        MaxKeys=100,
        EncodingType='url'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Prefix Filters the object keys prefixed with the value of this parameter. It is left empty by default. String No
    Delimiter A separator which is left empty by default. For example, you can specify it as / to indicate folders. String No
    Marker Marks the starting point of the returned object list. Entries are listed in UTF-8 binary order by default. String No
    MaxKeys The maximum number of returned objects; the default value is 1000. int No
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String No

    Response description

    The response contains object metadata in dict format:

    {
        'MaxKeys': '1000', 
        'Prefix': 'string',
        'Delimiter': 'string',
        'Marker': 'string',
        'NextMarker': 'string',
        'Name': 'examplebucket-1250000000',  
        'IsTruncated': 'false'|'true',
        'EncodingType': 'url',
        'Contents':[
            {
                'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
                'StorageClass': 'STANDARD', 
                'Key': 'exampleobject',
                'Owner': {
                    'DisplayName': '1250000000',
                    'ID': '1250000000'
                }, 
                'LastModified': '2017-08-08T09:43:35.000Z', 
                'Size': '23'
            },
        ],
        'CommonPrefixes':[
            {
                'Prefix': 'string'
            },
        ],
    }
    Parameter Name Description Type
    MaxKeys Maximum number of returned objects; the default value is 1,000. String
    Prefix Filters objects prefixed with the value of this parameter. It is left empty by default. String
    Delimiter A separator which is left empty by default. For example, you can specify it as / to indicate folders. String
    Marker Marks the starting point of the returned object list. Entries are listed in UTF-8 binary order by default. string
    NextMarker Marks the starting point of the next list of returned objects if IsTruncated is set to true. string
    Name Bucket name in the format: BucketName-APPID String
    IsTruncated Indicates whether the returned object is truncated String
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String
    Contents List of object metadata, including 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', 'Size' List
    CommonPrefixes All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix List

    Querying objects and their version history

    Feature description

    This API is used to query some or all objects in a bucket and their version history.

    Method prototype

    list_objects_versions(Bucket, Prefix="", Delimiter="", KeyMarker="", VersionIdMarker="", MaxKeys=1000, EncodingType="", **kwargs)

    Sample request

    response = client.list_objects_versions(
        Bucket='examplebucket-1250000000',
        Prefix='string'
    )

    Sample request for all parameters

    response = client.list_objects_versions(
        Bucket='examplebucket-1250000000',
        Prefix='string',
        Delimiter='/',
        KeyMarker='string',
        VersionIdMarker='string',
        MaxKeys=100,
        EncodingType='url'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Prefix Filters the object keys prefixed with the value of this parameter. It is left empty by default. String No
    Delimiter A separator which is left empty by default. For example, you can specify it as / to indicate folders. String No
    Marker Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default. String No
    VersionIdMarker Marks the starting VersionId of the returned object list. Entries are listed in UTF-8 binary order by default. String No
    MaxKeys The maximum number of returned objects; the default value is 1000. int No
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String No

    Response description

    The response contains object metadata in dict format:

    {
        'MaxKeys': '1000', 
        'Prefix': 'string',
        'Delimiter': 'string',
        'KeyMarker': 'string',
        'VersionIdMarker': 'string',
        'NextKeyMarker': 'string',
        'NextVersionIdMarker': 'string',
        'Name': 'examplebucket-1250000000',  
        'IsTruncated': 'false'|'true',
        'EncodingType': 'url',
        'Version':[
            {
                'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
                'StorageClass': 'STANDARD', 
                'Key': 'exampleobject',
                'VersionId': 'string',
                'IsLatest': 'true'|'false',
                'Owner': {
                    'DisplayName': '1250000000',
                    'ID': '1250000000'
                }, 
                'LastModified': '2017-08-08T09:43:35.000Z', 
                'Size': '23'
            },
        ],
        'DeleteMarker': [
            {
                'Key': 'exampleobject',
                'VersionId': 'string',
                'IsLatest': 'true'|'false',
                'Owner': {
                    'DisplayName': '1250000000',
                    'ID': '1250000000'
                },
                'LastModified': '2017-08-08T09:43:35.000Z'
            },
        ],
        'CommonPrefixes':[
            {
                'Prefix': 'string'
            },
        ],
    }
    Parameter Name Description Type
    MaxKeys Maximum number of returned objects; the default value is 1,000. String
    Prefix Filters objects prefixed with the value of this parameter. It is left empty by default. String
    Delimiter A separator which is left empty by default. For example, you can specify it as / to indicate folders. String
    Marker Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default. String
    VersionIdMarker Marks the starting VersionId of the returned object list. Entries are listed in UTF-8 binary order by default. String
    NextKeyMarker Marks the starting object key of the next list of returned objects if IsTruncated is set to true. String
    NextVersionIdMarker Marks the starting VersionId of the next list of returned objects if IsTruncated is set to true. String
    Name Bucket name in the format: BucketName-APPID String
    IsTruncated Indicates whether the returned object is truncated String
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url string
    Version List of the metadata of objects with multiple versions, including 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified',and 'Size' List
    DeleteMarker List of the metadata of delete markers, including 'Key','VersionId','IsLatest','Owner',and 'LastModified' List
    CommonPrefixes All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix List

    Uploading an object using simple upload

    Feature description

    This API is used to upload an object to a bucket.

    Method prototype

    put_object(Bucket, Body, Key, **kwargs)

    Sample request

    response = client.put_object(
        Bucket='examplebucket-1250000000',
        Body=b'bytes',
        Key='exampleobject',
        EnableMD5=False
    )

    Sample request for all parameters

    response = client.put_object(
        Bucket='examplebucket-1250000000',
        Body=b'bytes'|file,
        Key='exampleobject',
        EnableMD5=False|True,
        ACL='private'|'public-read',  # Please be aware that by using this parameter, the maximum of 1000 ACLs may be reached
        GrantFullControl='string',
        GrantRead='string',
        StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
        Expires='string',
        CacheControl='string',
        ContentType='string',
        ContentDisposition='string',
        ContentEncoding='string',
        ContentLanguage='string',
        ContentLength='123',
        ContentMD5='string',
        Metadata={
            'x-cos-meta-key1': 'value1',
            'x-cos-meta-key2': 'value2'
        }
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Body Content of the object to be uploaded. It can be a file stream or a byte stream file/bytes Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    EnableMD5 Specifies whether the SDK needs to calculate Content-MD5. This feature is disabled by default. The upload will take longer if it is enabled Bool No
    ACL Sets the object ACL, e.g. 'private','public-read' String No
    GrantFullControl Grants full permission in the format: id="OwnerUin" String No
    GrantRead Grants read permission in the format: id="OwnerUin" String No
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    Expires Sets Expires. String No
    CacheControl Cache policy. Sets Cache-Control. String No
    ContentType Content type. Sets Content-Type. String No
    ContentDisposition File name. Sets Content-Disposition String No
    ContentEncoding Encoding format. Sets Content-Encoding. String No
    ContentLanguage Language type. Sets Content-Language String No
    ContentLength Sets the length of the request content string No
    ContentMD5 Sets the MD5 of the object to be uploaded for verification String No
    Metadata User-defined object metadata. It must start with x-cos-meta; otherwise, it will be ignored Dict No

    Response description

    This response contains attributes of the uploaded object in dict format:

    {
        'ETag': 'string',
        'x-cos-version-id': 'string'
    }
    Parameter Name Description Type
    ETag MD5 of the uploaded object String
    x-cos-version-id Version ID of the object if versioning is enabled String

    Querying object metadata

    Feature description

    This API is used to query object metadata.

    Method prototype

    head_object(Bucket, Key, **kwargs)

    Sample request

    response = client.head_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject'
    )

    Sample request for all parameters

    response = client.head_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        VersionId='string',
        IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    VersionId Version ID of the object if versioning is enabled String No
    IfModifiedSince The object metadata is returned only if the object is modified after the specified time in GMT format String No

    Response description

    The response contains object metadata in dict format:

    {
        'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
        'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
        'Cache-Control': 'max-age=1000000',
        'Content-Type': 'application/octet-stream',
        'Content-Disposition': 'attachment; filename="filename.jpg"',
        'Content-Encoding': 'gzip',
        'Content-Language': 'zh-cn',
        'Content-Length': '16807',
        'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
        'x-cos-meta-test': 'test',
        'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
        'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
    }
    Parameter Name Description Type
    ETag MD5 of the object String
    Last-Modified Last modification time of the object String
    CacheControl Cache policy. HTTP standard header. String
    ContentType Content type. HTTP standard header. String
    ContentDisposition File name. HTTP standard header String
    ContentEncoding Encoding format. HTTP standard header. String
    ContentLanguage Language type. HTTP standard header. String
    Content-Length Object size String
    Expires Cache expiration time. Standard HTTP header. String
    x-cos-meta-* User-defined object metadata. It must start with x-cos-meta; otherwise, it will be ignored String
    x-cos-version-id Version ID of the object if versioning is enabled String

    Downloading an object

    Feature description

    This API is used to download an object.

    Method prototype

     get_object(Bucket, Key, **kwargs)

    Sample request

    response = client.get_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject'
    )
    
    response['Body'].get_stream_to_file('exampleobject')

    Sample request for all parameters

    response = client.get_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        Range='string',
        IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
        IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
        IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
        IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
        ResponseCacheControl='string',
        ResponseContentDisposition='string',
        ResponseContentEncoding='string',
        ResponseContentLanguage='string',
        ResponseContentType='string',
        ResponseExpires='string',
        VersionId='string'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    Range Sets the byte range of the object to be downloaded in the format: bytes=first-last String No
    IfMatch The object is returned only if the Etag matches the specified content String No
    IfModifiedSince The object is returned only if the object is modified after the specified time in GMT format String No
    IfNoneMatch The object is returned only if the Etag does not match the specified content String No
    IfUnmodifiedSince The object is returned only if the object is modified before or at the specified time in GMT format String No
    ResponseCacheControl Sets the Cache-Control in the response header String No
    ResponseContentDisposition Sets the Content-Disposition in the response header String No
    ResponseContentEncoding Sets the Content-Encoding in the response header String No
    ResponseContentLanguage Sets the Content-Language in the response header String No
    ResponseContentType Sets the Content-Type in the response header String No
    Response-expires Sets the Expires in the response header String No
    VersionId Version ID of the object to be downloaded String No

    Response description

    The response contains the content and the metadata of the downloaded object in dict format:

    {
        'Body': StreamBody(),
        'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
        'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
        'Accept-Ranges': 'bytes',
        'Content-Range': 'bytes 0-16086/16087',
        'Cache-Control': 'max-age=1000000',
        'Content-Type': 'application/octet-stream',
        'Content-Disposition': 'attachment; filename="filename.jpg"',
        'Content-Encoding': 'gzip',
        'Content-Language': 'zh-cn',
        'Content-Length': '16807',
        'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
        'x-cos-meta-test': 'test',
        'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
        'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
    }
    Parameter Name Description Type
    Body Content of the downloaded object. The get_raw_stream() method gets a file stream; the get_stream_to_file(local_file_path) method downloads the object content to a specified local file StreamBody
    ETag MD5 of the object String
    Last-Modified Last modified time of the object String
    Accept-Ranges Range. HTTP standard header. String
    Content-Range Content range. HTTP standard header. String
    Cache-Control Cache policy. HTTP standard header. String
    Content-Type Content type. HTTP standard header. String
    Content-Disposition File name. HTTP standard header. String
    Content-Encoding Encoding format. HTTP standard header. String
    Content-Language Language type. HTTP standard header String
    Content-Length Object size String
    Expires Cache expiration time. HTTP standard header String
    x-cos-meta-* User-defined object metadata. It must start with `x-cos-meta`; otherwise, it will be ignored String
    x-cos-version-id Version ID of the object if versioning is enabled String

    Setting object replication

    Feature description

    This API is used to copy a file to a destination path.

    Method prototype

    copy_object(Bucket, Key, CopySource, CopyStatus='Copy', **kwargs)

    Sample request

    response = client.copy_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        CopySource={
            'Bucket': 'sourcebucket-1250000000', 
            'Key': 'exampleobject', 
            'Region': 'ap-guangzhou'
        }
    )

    Sample request for all parameters

    response = client.copy_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        CopySource={
            'Bucket': 'sourcebucket-1250000000', 
            'Key': 'exampleobject', 
            'Region': 'ap-guangzhou',
            'VesionId': 'string'
        },
        CopyStatus='Copy'|'Replaced',
        ACL='private'|'public-read',
        GrantFullControl='string',
        GrantRead='string',
        StorageClass='STANDARD'|'STANDARD_IA',
        Expires='string',
        CacheControl='string',
        ContentType='string',
        ContentDisposition='string',
        ContentEncoding='string',
        ContentLanguage='string',
        Metadata={
            'x-cos-meta-key1': 'value1',
            'x-cos-meta-key2': 'value2'
        }
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    CopySource Describes the path to the source object, including Bucket, Key, Region, VersionId Dict Yes
    XCosMetadataDirective Valid values: 'Copy': ignore the configured metadata and copy the file directly; 'Replaced': modify the metadata according to the configured metadata. If the destination path is identical to the source path, this parameter must be set to ‘Replaced’. String Yes
    ACL Sets the object ACL, e.g. 'private', 'public-read' String No
    GrantFullControl Grants full permission in the format: id="OwnerUin" String No
    GrantRead Grants read access in the format: id="OwnerUin" String No
    XCosStorageClass Sets the object storage class: STANDARD or STANDARD_IA. Default value: STANDARD String No
    Expires Sets Expires. String No
    CacheControl Cache policy. Sets Cache-Control. String No
    ContentType Content type. Sets Content-Type. String No
    ContentDisposition File name. Sets Content-Disposition. String No
    ContentEncoding Encoding format. Sets Content-Encoding. String No
    ContentLanguage Language type. Sets Content-Language String No
    Metadata User-defined object metadata Dict No

    Response description

    This response contains attributes of the uploaded object in dict format:

    {
        'ETag': 'string',
        'LastModified': 'string',
        'VersionId': 'string',
        'x-cos-copy-source-version-id': 'string'
    }
    Parameter Name Description Type
    ETag MD5 of the copied object String
    LastModified Time the copied object was last modified String
    VersionId Version ID of the copied object if versioning is enabled String
    x-cos-copy-source-version-id Version ID of the source object String

    Deleting a single object

    Feature description

    This API is used to delete a specified object.

    Method prototype

    delete_object(Bucket, Key, **kwargs)

    Sample request

    response = client.delete_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject'
    )

    Sample request for all parameters

    response = client.delete_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        VersionId='string',
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    VersionId Version ID of the object if versioning is enabled String No

    Response description

    This response contains information on the deleted object in dict format:

    {
        'x-cos-version-id': 'string',
        'x-cos-delete-marker': 'true'|'false',
    }
    Parameter Name Description Type
    x-cos-version-id Version ID of the deleted object String
    x-cos-delete-marker Identifies whether the deleted object is a delete marker String

    Deleting multiple objects

    Feature description

    The API is used to delete multiple objects.

    Method prototype

    delete_objects(Bucket, Delete={}, **kwargs)

    Sample request

    response = client.delete_objects(
        Bucket='examplebucket-1250000000',
        Delete={
            'Object': [
                {
                    'Key': 'exampleobject1'
                },
                {
                    'Key': 'exampleobject2'
                }
            ]
        }
    )

    Sample request for all parameters

    response = client.delete_objects(
        Bucket='examplebucket-1250000000',
        Delete={
            'Object': [
                {
                    'Key': 'exampleobject1',
                    'VersionId': 'string'
                },
                {
                    'Key': 'exampleobject2',
                    'VersionId': 'string'
                },
            ],
            'Quiet': 'true'|'false'
        }
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Delete Describes the objects to be deleted and the way the deletion results are returned Dict Yes
    Objects Information on the objects to be deleted List Yes
    Key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String
    VersionId Version IDs of the objects to be deleted if versioning is enabled. String No
    Quiet Specifies how the deletion results are returned. Valid values: 'true', only information on failed deletions is returned; 'false', information on all deletions is returned. Default value: 'false' String No

    Response description

    This response contains results of the deletions in dict format:

    {
        'Deleted': [
            {
                'Key': 'string',
                'VersionId': 'string',
                'DeleteMarker': 'true'|'false',
                'DeleteMarkerVersionId': 'string'
            },
            {
                'Key': 'string',
            },
        ],
        'Error': [
            {
                'Key': 'string',
                'VersionId': 'string',
                'Code': 'string',
                'Message': 'string'
            },
        ]
    }
    Parameter Name Description Type
    Deleted Information on the objects successfully deleted List
    Key Path to the objects successfully deleted String
    VersionId Version IDs of the successfully deleted objects String
    DeleteMarker Identifies whether the successfully deleted object is a delete marker String
    DeleteMarkerVersionId Version IDs of the delete markers of the successfully deleted objects String
    Error Information on the objects that failed to be deleted List
    Key Paths to the objects that failed to be deleted string
    VersionId Version IDs of the objects that failed to be deleted String
    Code Error codes for the objects that failed to be deleted string
    Message Error messages for the objects that failed to be deleted string

    Restoring an archived object

    Feature description

    This API is used to retrieve an archived object for access.

    Method prototype

    restore_object(Bucket, Key, RestoreRequest={}, **kwargs)

    Sample request

    response = client.restore_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        RestoreRequest={
            'Days': 100,
            'CASJobParameters': {
                'Tier': 'Standard'
            }
        }
    )

    Sample request for all parameters

    response = client.restore_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        RestoreRequest={
            'Days': 100,
            'CASJobParameters': {
                'Tier': 'Expedited'|'Standard'|'Bulk'
            }
        }
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    RestoreRequest Describes the rules of the retrieved temporary object Dict Yes
    Days Describes the expiration time of the temporary object Int Yes
    CASJobParameters Describes the configuration of the restoration type Dict No
    Tier Describes the object’s restoration mode. Valid values: 'Expedited', 'Standard', and 'Bulk' String No

    Response description

    This method returns None.

    Multipart operations

    Operations related to multipart uploads include the following:

    • Uploading objects with multipart upload: initializing a multipart upload, uploading parts, and completing a multipart upload
    • Resuming a multipart upload: querying uploaded parts, uploading remaining parts, and completing a multipart upload
    • Deleting uploaded parts.

    Querying a multipart upload

    Feature description

    This API is used to query ongoing multipart uploads in a specified bucket.

    Method prototype

    list_multipart_uploads(Bucket, Prefix="", Delimiter="", KeyMarker="", UploadIdMarker="", MaxUploads=1000, EncodingType="", **kwargs)

    Sample request

    response = client.list_multipart_uploads(
        Bucket='examplebucket-1250000000',
        Prefix='dir'
    )

    Sample request for all parameters

    response = client.list_multipart_uploads(
        Bucket='examplebucket-1250000000',
        Prefix='string',
        Delimiter='string',
        KeyMarker='string',
        UploadIdMarker='string',
        MaxUploads=100,
        EncodingType='url'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Prefix Filters the multipart upload keys prefixed with the value of this parameter. It is left empty by default. String No
    Delimiter A separator which is left empty by default. String No
    KeyMarker Specifies the starting key of the multipart upload list. It is used together with UploadIdMarker. String No
    UploadIdMarker Specifies the starting UploadId of the multipart upload list. It is used together with KeyMarker. If KeyMarker is not specified, UploadIdMarker will be ignored. String No
    MaxUploads Maximum number of multipart uploads returned at a time; the default value is 1000. Int No
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String No

    Response description

    This response contains information on the obtained multipart uploads in dict format:

    {
        'Bucket': 'examplebucket-1250000000',
        'Prefix': 'string',
        'Delimiter': 'string',
        'KeyMarker': 'string',
        'UploadIdMarker': 'string',
        'NextKeyMarker': 'string',
        'NextUploadIdMarker': 'string',
        'MaxUploads': '1000',
        'IsTruncated': 'true'|'false',,
        'EncodingType': 'url',
        'Upload':[
            {
                'UploadId': 'string',
                'Key': 'string',
                'Initiated': 'string',
                'StorageClass': 'STANDARD',
                'Owner': {
                    'DisplayName': 'string',
                    'ID': 'string'
                },
                'Initiator': {
                    'ID': 'string',
                    'DisplayName': 'string'
                }
            },
        ],
        'CommonPrefixes':[
            {
                'Prefix': 'string'
            },
        ],
    }
    Parameter Name Description Type
    Bucket Bucket name in the format: BucketName-APPID String
    Prefix Filters the multipart upload keys prefixed with the value of this parameter. It is left empty by default. String
    Delimiter A separator which is left empty by default. String
    KeyMarker Specifies the starting key of the multipart upload list. It is used together with UploadIdMarker. Sring
    UploadIdMarker Specifies the starting UploadId of the multipart upload list. It is used together with KeyMarker. If KeyMarker is not specified, UploadIdMarker will be ignored. String
    NextKeyMarker Specifies the starting key of the next multipart upload list if IsTruncated is true. String
    NextUploadIDMarker Specifies the starting UploadId of the next multipart upload list if IsTruncated is true. String
    MaxUploads Maximum number of multipart uploads returned at a time; the default value is 1000. int
    IsTruncated Indicates whether the returned multipart upload list is truncated String
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String
    Upload List of information on the returned multipart uploads, including 'UploadId', 'StorageClass', 'Key', 'Owner', 'Initiator', 'Initiated', etc. List
    CommonPrefixes All keys starting with a particular prefix and ending with the delimiter are grouped as a common prefix List

    Initializing a multipart upload

    Feature description

    This API is used to initialize a multipart upload and obtain the corresponding uploadId.

    Method prototype

    create_multipart_upload(Bucket, Key, **kwargs):

    Sample request

    response = client.create_multipart_upload(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        StorageClass='STANDARD'
    )

    Sample request for all parameters

    response = client.create_multipart_upload(
        Bucket='examplebucket-1250000000',
        Key='multipart.txt',
        StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
        Expires='string',
        CacheControl='string',
        ContentType='string',
        ContentDisposition='string',
        ContentEncoding='string',
        ContentLanguage='string',
        Metadata={
            'x-cos-meta-key1': 'value1',
            'x-cos-meta-key2': 'value2'
        },
        ACL='private'|'public-read',
        GrantFullControl='string',
        GrantRead='string'
    )
    # Obtain UploadId for use by other APIs
    uploadid = response['UploadId']

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    Expires Sets Expires. String No
    CacheControl Cache policy. Sets Cache-Control. String No
    ContentType Content type. Sets Content-Type. String No
    ContentDisposition File name. Sets Content-Disposition. String No
    ContentEncoding Encoding format. Sets Content-Encoding. String No
    ContentLanguage Language type. Sets Content-Language String No
    Metadata User-defined object metadata Dict No
    ACL Sets the object ACL, e.g. 'private','public-read' String No
    GrantFullControl Grants full permission in the format: id="OwnerUin" String No
    GrantRead Grants read permission in the format: id="OwnerUin" String No

    Response description

    This response contains information on the initialization of the multipart upload in dict format:

    {
        'UploadId': '150219101333cecfd6718d0caea1e2738401f93aa531a4be7a2afee0f8828416f3278e5570',
        'Bucket': 'examplebucket-1250000000', 
        'Key': 'exampleobject' 
    }
    
    Parameter Name Description Type
    UploadId ID of the multipart upload String
    Bucket Bucket name in the format: BucketName-APPID String
    Key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String

    Uploading parts

    This API is used to upload parts.

    Method prototype

    upload_part(Bucket, Key, Body, PartNumber, UploadId, **kwargs)

    Sample request

    # Note: The maximum number of parts that can be uploaded is 10,000.
    response = client.upload_part(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        Body=b'b'*1024*1024,
        PartNumber=1,
        UploadId='exampleUploadId'
    )

    Sample request for all parameters

    # Note: The maximum number of parts that can be uploaded is 10,000.
    response = client.upload_part(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        Body=b'bytes'|file,
        PartNumber=1,
        UploadId='string',
        EnableMD5=False|True,
        ContentLength='123',
        ContentMD5='string'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    Body Content of the parts to be uploaded. It can be a local file stream or an input stream file/bytes Yes
    PartNumber Identifies the part number int Yes
    UploadId ID of the multipart upload string Yes
    EnableMD5 Specifies whether the SDK needs to calculate Content-MD5. This feature is disabled by default. The upload will take longer if it is enabled Bool No
    ContentLength Sets the length of the request content string No
    ContentMD5 Sets the MD5 of the object to be uploaded for verification String No

    Response description

    This response contains attributes of the uploaded parts in dict format:

    {
        'ETag': 'string'
    }
    Parameter Name Description Type
    ETag MD5 of the uploaded part String

    Copying parts

    This API is used to copy an object as a part.

    Method prototype

    upload_part_copy(Bucket, Key, PartNumber, UploadId, CopySource, CopySourceRange='', **kwargs)

    Sample request

    response = client.upload_part_copy(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        PartNumber=1,
        UploadId='exampleUploadId',
        CopySource={
            'Bucket': 'sourcebucket-1250000000', 
            'Key': 'exampleobject', 
            'Region': 'ap-guangzhou'
        }
    )

    Sample request for all parameters

    response = client.upload_part_copy(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        PartNumber=100,
        UploadId='string',
        CopySource={
            'Bucket': 'sourcebucket-1250000000', 
            'Key': 'sourceObject', 
            'Region': 'COS_REGION', #replace with source bucket’s Region
            'VersionId': 'string'
        },
        CopySourceRange='string',
        CopySourceIfMatch='string',
        CopySourceIfModifiedSince='string',
        CopySourceIfNoneMatch='string',
        CopySourceIfUnmodifiedSince='string'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    PartNumber Identifies the part number int Yes
    UploadId ID of the multipart upload string Yes
    CopySource Describes the path to the source object, including Bucket, Key, Region, VersionId Dict Yes
    CopySourceRange Describes the range of the source object to be copied in the format of bytes=first-last. The entire source will be copied by default if no range is specified String No
    CopySourceIfMatch The source object is copied only if the Etag of the source object matches the specified value String No
    CopySourceIfModifiedSince The source object is copied only if it is modified after the specified time String No
    CopySourceIfNoneMatch The source object is copied only if the Etag of the source object does not match the specified value String No
    CopySourceIfUnmodifiedSince The source object is copied only if it is not modified after the specified time String No

    Response description

    This response contains the attributes of the copied part in dict format:

    {
        'ETag': 'string',
        'LastModified': 'string',
        'x-cos-copy-source-version-id': 'string',
    }
    Parameter Name Description Type
    ETag MD5 of the copied part string
    LastModified Time the copied part was last modified string
    x-cos-copy-source-version-id Version ID of the source object String

    Querying uploaded parts

    Feature description

    This API is used to query the uploaded parts of a specific multipart upload.

    Method prototype

    list_parts(Bucket, Key, UploadId, MaxParts=1000, PartNumberMarker=0, EncodingType='', **kwargs)

    Sample request

    response = client.list_parts(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        UploadId='exampleUploadId'
    )

    Sample request for all parameters

    response = client.list_parts(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        UploadId=uploadid,
        MaxParts=1000,
        PartNumberMarker=100,
        EncodingType='url'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    UploadId ID of the multipart upload String Yes
    MaxParts Maximum number of parts returned at a time; the default value is 1,000. Int No
    PartNumberMarker The parts are listed starting from the one following PartNumberMarker. Default value: 0, which means the parts are listed from the first one. int No
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String No

    Response description

    This response contains information on all the uploaded parts in dict format:

    {
        'Bucket': 'examplebucket-1250000000', 
        'Key': 'exampleobject', 
        'UploadId': '1502192444bdb382add546a35b2eeab81e06ed84086ca0bb75ea45ca7fa073fa9cf74ec4f2', 
        'EncodingType': None, 
        'MaxParts': '1000',
        'IsTruncated': 'true',
        'PartNumberMarker': '0', 
        'NextPartNumberMarker': '1000', 
        'StorageClass': 'Standard',
        'Part': [
            {
                'LastModified': '2017-08-08T11:40:48.000Z',
                'PartNumber': '1',
                'ETag': '"8b8378787c0925f42ccb829f6cc2fb97"',
                'Size': '10485760'
            },
        ], 
        'Initiator': {
            'DisplayName': '3333333333', 
            'ID': 'qcs::cam::uin/3333333333:uin/3333333333'
        }, 
        'Owner': {
            'DisplayName': '124564654654',
            'ID': '124564654654'
        }
    }
    Parameter Name Description Type
    Bucket Bucket name in the format: BucketName-APPID String
    Key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String
    UploadId ID of the multipart upload String
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url String
    MaxParts Maximum number of parts returned at a time; the default value is 1000. String
    IsTruncated Indicates whether the returned list is truncated String
    PartNumberMarker The parts are listed starting from the one following PartNumberMarker. Default value: 0, which means the parts are listed from the first one. String
    NextPartNumberMarker Marks the starting part of the next part list String
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String
    Part Information on the uploaded parts, including ETag, PartNumber, Size, LastModified String
    Initiator Creator of the multipart upload, including DisplayName, and ID Dict
    Owner Information on the object owner, including DisplayName and ID Dict

    Completing a multipart upload

    Feature description

    This API is used to complete a multipart upload.

    Method prototype

    complete_multipart_upload(Bucket, Key, UploadId, MultipartUpload={}, **kwargs)

    Sample request

    response = client.complete_multipart_upload(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        UploadId='exampleUploadId',
        MultipartUpload={
            'Part': [
                {
                    'ETag': 'string',
                    'PartNumber': 1
                },
                {
                    'ETag': 'string',
                    'PartNumber': 2
                },
            ]
        },
    )
    

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    UploadId ID of the multipart upload String Yes
    MultipartUpload Information on all parts, including ETag and PartNumber Dict

    Response description

    This response contains information on the merged object in dict format:

    {
        'ETag': '"3f866d0050f044750423e0a4104fa8cf-2"', 
        'Bucket': 'examplebucket-1250000000', 
        'Location': 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject', 
        'Key': 'exampleobject'
    }
    Parameter Name Description Type
    ETag The unique tag of a merged object. It is not the MD5 checksum of the object content; it is only used to check the uniqueness of the object. To verify the object content, you can check the ETag of each part during the upload process. string
    Bucket Bucket name in the format: BucketName-APPID String
    Location URL address String
    Key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String

    Aborting a multipart upload

    Feature description

    This API is used to abort a multipart upload and delete the uploaded parts.

    Method prototype

    abort_multipart_upload(Bucket, Key, UploadId, **kwargs)

    Sample request

    response = client.abort_multipart_upload(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        UploadId='exampleUploadId'
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg string Yes
    UploadId ID of the multipart upload String Yes

    Response description

    This method returns None.

    Advanced APIs (recommended)

    Uploading objects (checkpoint restart)

    Feature description

    This API can automatically select between simple upload and multipart upload according to the file size. It uses simple upload for files smaller than or equal to 20 MB and multipart upload for files larger than 20 MB. It also supports automatic checkpoint restart for incomplete multipart uploads.

    Method prototype

    upload_file(Bucket, Key, LocalFilePath, PartSize=1, MAXThread=5, **kwargs)

    Sample request

    response = client.upload_file(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        LocalFilePath='local.txt',
        EnableMD5=False
    )

    Sample request for all parameters

    response = client.upload_file(
        Bucket='examplebucket-1250000000',
        Key='exampleobject',
        LocalFilePath='local.txt',
        PartSize=1,
        MAXThread=5,
        EnableMD5=False|True,
        ACL='private'|'public-read', # Please be aware that by using this parameter, the maximum of 1000 ACLs may be reached
        GrantFullControl='string',
        GrantRead='string',
        StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
        Expires='string',
        CacheControl='string',
        ContentType='string',
        ContentDisposition='string',
        ContentEncoding='string',
        ContentLanguage='string',
        ContentLength='123',
        ContentMD5='string',
        Metadata={
            'x-cos-meta-key1': 'value1',
            'x-cos-meta-key2': 'value2'
        }
    )

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    key ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg String Yes
    LocalFilePath Path to the local file String Yes
    PartSize Part size. Default value: 1 MB Int No
    MAXThread Maximum number of concurrent multipart upload tasks. Default value: 5 Int No
    EnableMD5 Specifies whether the SDK needs to calculate Content-MD5. This feature is disabled by default. The upload will take longer if it is enabled Bool No
    ACL Sets the object ACL, e.g. 'private','public-read' String No
    GrantFullControl Grants full permission in the format: id="OwnerUin" String No
    GrantRead Grants read permission in the format: id="OwnerUin" String No
    StorageClass Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    Expires Sets Expires. String No
    CacheControl Cache policy. Sets Cache-Control. String No
    ContentType Content type. Sets Content-Type. String No
    ContentDisposition File name. Sets Content-Disposition. String No
    ContentEncoding Encoding format. Sets Content-Encoding. String No
    ContentLanguage Language type. Sets Content-Language String No
    ContentLength Sets the length of the request content string No
    ContentMD5 Sets the MD5 of the object to be uploaded for verification String No
    Metadata User-defined object metadata Dict No

    Response description

    This response contains attributes of the uploaded object in dict format:

    {
        'ETag': 'string'
    }
    Parameter Name Description Type
    ETag MD5 of the uploaded object String

    Was this page helpful?

    Was this page helpful?

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