Object Operations

Last updated: 2020-06-12 15:07:38

    Introduction

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

    Simple Operations

    API Operation Description
    GET Bucket(List Object) Querying object list Queries a part of or all objects in a bucket
    PUT Object Uploads an object Uploads an object (file) to the bucket
    HEAD Object Gets object metadata Gets the meta information of an object
    GET Object Gets an object Downloads an object (file) locally
    PUT Object - Copy Sets object replication Copies a file to the destination path
    DELETE Object Deletes a single object Deletes the specified object in the bucket
    DELETE Object Deletes a single object Deletes multiple objects in the bucket

    Multipart Upload Operations

    API Operation Description
    List Multipart Uploads Querying a multipart upload Queries the information of a multipart upload in progress
    Initiate Multipart Upload Initializes multipart upload Initializes a multipart upload operation
    Upload Part Uploading parts Uploads file parts
    List Parts Querying uploaded parts Queries uploaded parts in the 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

    Other Operations

    API Operation Description
    POST Object restore Restores an archived object Restores an archived object for access
    PUT Object acl Sets the object ACL Sets an ACL for an object (file) in the bucket
    GET Object acl Gets the object ACL Gets the ACL of an object (file)

    Simple Operations

    Querying the object list

    Feature

    This API (GET Bucket (List Object)) is used to query some or all objects in a bucket.

    Method Prototype

    func (s *BucketService) Get(ctx context.Context, opt *BucketGetOptions) (*BucketGetResult, *Response, error)

    Request Samples

    opt := &cos.BucketGetOptions{
        Prefix:  "test",
        MaxKeys: 100,
    }
    v, _, err := c.Bucket.Get(context.Background(), opt)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type BucketGetOptions struct {
        Prefix       string 
        Delimiter='string', 
        EncodingType string 
        Marker='string', 
        MaxKeys      int    
    }
    Parameter Name Description Type Required
    Prefix Filters object keys prefixed with the value of this parameter. It is left empty by default. string No
    Delimiter Sets a delimiter. It is left empty by default. string No
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url string No
    Marker Marks the starting point of the list of returned objects. Entries are listed using UTF-8 binary order by default. string No
    MaxKeys Maximum number of returned objects. It defaults to 1000. int No

    Returned Result

    type BucketGetResult struct {
        Name           string
        Prefix         string 
        Marker='string', 
        'NextMarker': 'string', 
        Delimiter='string', 
        MaxKeys        int
        IsTruncated    bool
        Contents       []Object 
        CommonPrefixes []string 
        EncodingType   string   
    }
    Parameter Name Description Type
    String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    Prefix Filters the object keys prefixed with the value of this parameter. It is left empty by default. string
    Marker Marks the starting point of the list of returned objects. Entries are listed using UTF-8 binary order by default. string
    NextMarker Marks the starting point of the next list of returned objects if IsTruncated is true. string
    Delimiter A separator which is left empty by default. For example, you can specify it as / to indicate folders. string
    MaxKeys Maximum number of returned objects. It defaults to 1000. int
    IsTruncated Indicates whether the returned objects are truncated bool
    Contents The list containing the meta information of all objects, including ETag, StorageClass, Key, Owner, LastModified, and Size. []Object
    CommonPrefixes All keys starting with Prefix and ending with Delimiter are grouped into the same type. []string
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url string

    Uploading an object using simple upload

    Feature

    Upload an object or file to the bucket (PUT Object). Up to 5GM (inclusive) is supported, please use [multipart upload (#.E5.88.86.E5.9D.97.E4.B8.8A.E4.BC.A0.E5.AF.B9.E8.B1.A1) or Advanced APIs if more than 5GB。

    Method Prototype

    func (s *ObjectService) Put(ctx context.Context, key string, r io.Reader, opt *ObjectPutOptions) (*Response, error)

    Request Samples

    $key = "exampleobject";
    f, err := os.Open("../test")
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentType: "text/html",
        },
        ACLHeaderOptions: &cos.ACLHeaderOptions{
            We recommend you not to set permissions on individual files when uploading so as to avoid reaching the limit. Bucket permission sets the default limit.
            XCosACL: "private",
        },
    }
    _, err = client.Object.Put(context.Background(), key, f, opt)
    if err != nil {
        panic(err)
    }
    type ObjectPutOptions struct {
        *ACLHeaderOptions       
        *ObjectPutHeaderOptions 
    }
    type ACLHeaderOptions struct {
        XCosACL              string                           
        XCosGrantRead        string
        XCosGrantWrite       string 
        XCosGrantFullControl string                                           
    } 
    type ObjectPutHeaderOptions struct {
        CacheControl='string', 
        ContentDisposition='string', 
        ContentEncoding='string', 
        ContentType='string', 
        'ContentLength' => 'int',   
        'Expires' => 'string', 
        Custom x-cos-meta-* header
        XCosMetaXXX        *http.Header 
        XCosStorageClass   string      
    }
    Parameter Name Description Type Required
    r The content of the uploaded file, which can be a file stream or a byte stream. When r is not bytes.Buffer/bytes.Reader/strings.Reader, opt.ObjectPutHeaderOptions.ContentLength must be specified. io.Reader Yes
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    XCosACL Sets the file ACL, such as private, public-read, and public-read-write string No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No
    GrantRead Grants the grantee the read permission in the format of id="[OwnerUin]" String No
    StorageClass Sets the object storage class; value range: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    Expires Sets Content-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
    ContentLength Sets transmission length string No
    XCosMetaXXX User-defined file meta information. It must start with x-cos-meta. Otherwise, it will be ignored. http.Header No

    Returned Result

    {
        'ETag': 'string',
        'x-cos-expiration': 'string'
    }
    Parameter Name Description Type
    ETag MD5 of the upload File string
    x-cos-expiration After the lifecycle is set, the file expiration rule is returned. string

    Querying object metadata

    Feature

    The API (HEAD Object) is used to query object metadata.

    Method Prototype

    func (s *ObjectService) Head(ctx context.Context, key string, opt *ObjectHeadOptions) (*Response, error)

    Request Samples

    $key = "exampleobject";
    _, err := client.Object.Head(context.Background(), key, nil)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectHeadOptions struct {
        IfModifiedSince string 
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    IfModifiedSince The file is returned only if it has been modified after the specified time string No

    Returned Result

    {
        'Content-Type': 'application/octet-stream',
        'Content-Length': '16807',
        'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
        'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
        'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
    }
    Parameter Name Description Type
    File meta information The meta information of the file obtained, including Etag and X-Cos-Request-Id. The meta information of the configured file is also included. string

    Downloading an object

    Feature

    This API (Get Object) is used to download an object.

    Method Prototype

    func (s *ObjectService) Get(ctx context.Context, key string, opt *ObjectGetOptions) (*Response, error)
    
    func (s *ObjectService) GetToFile(ctx context.Context, key, localfile string, opt *ObjectGetOptions) (*Response, error)

    Request Samples

    $key = "exampleobject";
    opt := &cos.ObjectGetOptions{
        ResponseContentType: "text/html",
        Range:               "bytes=0-3",
    }
    "opt" is optional. It can be set to nil unless otherwise specified.
    // 1. Obtain the object from response body
    resp, err := c.Object.Get(context.Background(), name, nil)
    if err != nil {
        panic(err)
    }
    bs, _ := ioutil.ReadAll(resp.Body)
    resp.Body.Close()
    
    // 2. Download the object to local files
    _, err = c.Object.GetToFile(context.Background(), name, "example", nil)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectGetOptions struct {
        ResponseContentType='string', 
        ResponseContentLanguage='string', 
        ResponseExpires='string', 
        ResponseCacheControl='string', 
        ResponseContentDisposition='string', 
        ResponseContentEncoding='string', 
        Range                      string 
        IfModifiedSince            string 
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    localfile Sets the Content-Type in the response header string Yes
    ResponseContentType Sets the Content-Type in the response header string No
    ResponseContentLanguage Sets the Content-Language in the response header string No
    ResponseExpires Sets the Content-Expires in the response header 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
    Range Sets the range of bytes of the file to be downloaded in the format of bytes=first-last string No
    IfModifiedSince The file is returned only if it has been modified after the specified time string No

    Returned Result

    {
        Body: '',
        'Accept-Ranges': 'bytes',
        'Content-Type': 'application/octet-stream',
        'Content-Length': '16807',
        'Content-Disposition': 'attachment; filename="filename.jpg"',
        'Content-Range': 'bytes 0-16086/16087',
        'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
        'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
        'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
    }
    Parameter Name Description Type
    Body The content of the downloaded file StreamBody
    File meta information The meta information of the downloaded file, including Etag and X-Cos-Request-Id. The meta information of the configured file is also returned. string

    Set object Replication

    This API (PUT Object - Copy) is used to copy files to the destination path.

    Method Prototype

    func (s *ObjectService) Copy(ctx context.Context, key, sourceURL string, opt *ObjectCopyOptions) (*ObjectCopyResult, *Response, error)

    Request Samples

    name := "exampleobject"
    // Uploading the source object
    f := strings.NewReader("test")
    _, err := c.Object.Put(context.Background(), name, f, nil)
    assert.Nil(s.T(), err, "Test Failed")
    
    sourceURL := fmt.Sprintf("%s/%s", client.BaseURL.BucketURL.Host, name)
    dest := "example_dest"
    We recommend you not to set permissions on individual files when uploading so as to avoid reaching the limit. Bucket permission sets the default limit.
    // opt := &cos.ObjectCopyOptions{}
    _, _, err = client.Object.Copy(context.Background(), dest, sourceURL, nil)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectCopyOptions struct {
        *ObjectCopyHeaderOptions 
        *ACLHeaderOptions        
    }
    type ACLHeaderOptions struct {
        XCosACL              string 
        XCosGrantRead        string 
        XCosGrantWrite       string 
        XCosGrantFullControl string 
    }
    type ObjectCopyHeaderOptions struct {
        XCosMetadataDirective           string 
        XCosCopySourceIfModifiedSince   string 
        XCosCopySourceIfUnmodifiedSince string 
        XCosCopySourceIfMatch           string 
        XCosCopySourceIfNoneMatch       string 
        XCosStorageClass                string 
        Custom x-cos-meta-* header
        XCosMetaXXX                        *http.Header 
        XCosCopySource                     string      
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    sourceURL The URL of the copied source file string Yes
    XCosACL Sets the file ACL, such as private, public-read, and public-read-write string No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No
    GrantRead Grants the grantee the read permission in the format of id="[OwnerUin]" String No
    XCosMetadataDirective Available values: Copy and Replaced. When it is set to Copy, ignore the configured user metadata information and copy the file directly. When it is set to Replaced, modify the metadata according to the configured meta information. If the destination path is identical to the source path, it must be set to Replaced. string Yes
    XCosCopySourceIfModifiedSince The operation is performed if the object is modified after the specified time, otherwise error code 412 is returned. It can be used with XCosCopySourceIfNoneMatch. Using it with other conditions can cause a conflict. string No
    XCosCopySourceIfUnmodifiedSince The operation is performed if the object is not modified after the specified time, otherwise error code 412 is returned. It can be used with XCosCopySourceIfMatch. Using it with other conditions can cause a conflict. string No
    XCosCopySourceIfMatch The operation is performed if the Etag of the object is the same as the given one, otherwise error code 412 is returned. It can be used with XCosCopySourceIfUnmodifiedSince. Using it with other conditions can cause a conflict. string No
    XCosCopySourceIfNoneMatch The operation is performed if the Etag of the object is different from the given one, otherwise error code 412 is returned. It can be used with XCosCopySourceIfModifiedSince. Using it with other conditions can cause a conflict. string No
    XCosStorageClass Sets file storage type: STANDARD, STANDARD_IA and ARCHIVE. Default: STANDARD string No
    XCosMetaXXX User-defined file meta information. http.Header No
    XCosCopySource Source file URL path. You can specify the history version with the versionid subresource. string No

    Returned Result

    Attributes of the uploaded file:

    type ObjectCopyResult struct {
        'ETag': 'string', 
        'LastModified': 'string',
    }
    Parameter Name Description Type
    ETag MD5 of the copied file string
    LastModified The time when the copied file was last modified. string

    Deleting a single object

    Feature

    This API is used to delete a specified object in the bucket.

    Method Prototype

    func (s *ObjectService) Delete(ctx context.Context, key string) (*Response, error)

    Request Samples

    $key = "exampleobject";
    _, err := c.Object.Delete(context.Background(), name)
    if err != nil {
        panic(err)
    }

    Parameter Description

    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes

    Deleting multiple objects

    Feature

    The API is used to delete multiple objects in a bucket. Up to 1000 objects can be deleted in a batch in one request.

    Method Prototype

    func (s *ObjectService) DeleteMulti(ctx context.Context, opt *ObjectDeleteMultiOptions) (*ObjectDeleteMultiResult, *Response, error)

    Request Samples

    var objects []string
    objects = append(objects, []string{"a", "b", "c"}...)
    obs := []cos.Object{}
    for _, v := range objects {
        obs = append(obs, cos.Object{Key: v})
    }
    opt := &cos.ObjectDeleteMultiOptions{
        Objects: obs,
        Boolean. Indicates whether the Quiet mode is enabled.
        True means Quiet mode is enabled, and False means Verbose mode is enabled. The default is False | No |
        // Quiet: true,
    }
    
    _, _, err := client.Object.DeleteMulti(context.Background(), opt)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectDeleteMultiOptions struct {
        Quiet   bool
        Objects []Object   
    }
    // Object stores object information
    type Object struct {
        Key          string
        // Other parameters are not related to this API
    }
    Parameter Name Description Type Required
    Quiet Boolean value determines whether to enable Quiet mode. For the response result, COS offers Verbose and Quiet modes:
  • Verbose mode returns the deletion result of each object
  • Quiet mode only returns information about object errors
    If the value is true, Quiet mode is enabled; If the value is false, Verbose mode is enabled. The value is false by default.
  • Boolean No
    Objects Provides the information of each target object to be deleted List Yes
    Key Destination object file name String Yes

    Returned Result

    Attributes of the uploaded file:

    // ObjectDeleteMultiResult saves the DeleteMulti result
    type ObjectDeleteMultiResult struct {    
        DeletedObjects []Object
        Errors         []struct {
            Key     string
            'Code': 'string',
            'Message': 'string'
        }
    }
    Parameter Name Description Type
    Object DELETE Information on the objects to be deleted
    Error DeleteResult Information on objects that have not been deleted in this operation
    Key The path of the object that failed to be deleted string
    - - Code Error code of the deletion failure String
    - - Message Error message of the deletion failure String

    Multipart Operations

    Querying multipart upload

    Feature

    This API (List Multipart Uploads) is used to query in-progress multipart uploads in the specified bucket.

    Method Prototype

    func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *Response, error)

    Request Samples

    _, _, err := client.Bucket.ListMultipartUploads(context.Background(), nil)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ListMultipartUploadsOptions struct {
        Delimiter='string',
        EncodingType   string
        Prefix         string
        MaxUploads     int
        KeyMarker='string',
        UploadIdMarker='string',                                         
    }
    Parameter Name Description Type Required
    delimiter The delimiter is a symbol. The delimiter is a symbol. The identical paths between prefix or, if no prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix String No
    EncodingType Specifies the encoding method of the return value; value range: url String No
    prefix The returned Object key must be prefixed with Prefix. Note that the returned key will still contain Prefix when querying with prefix. NSString * No
    max-uploads Sets the maximum number of multipart uploads returned. Value range: [1, 1,000]. Default value: 1,000 String No
    key-marker Used together with upload-id-marker.
    If upload-id-marker is not specified, only the multipart uploads whose ObjectName is lexicographically greater than key-marker will be listed;
    If upload-id-marker is specified, the multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed, and any multipart upload whose ObjectName lexicographically equals key-marker and whose UploadID is greater than upload-id-marker will also be listed
    String No
    upload-id-marker Used together with key-marker.
    If key-marker is not specified, upload-id-marker will be ignored;
    If key-marker is specified, the multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed, and any multipart upload whose ObjectName lexicographically equals key-marker and whose UploadID is greater than upload-id-marker will also be listed
    String No

    Returned Result

    // ListMultipartUploadsResult saves ListMultipartUploads results
    type ListMultipartUploadsResult struct {
        Bucket             string
        EncodingType       string
        KeyMarker          string
        UploadIDMarker     string
        'NextKeyMarker': 'string',
        NextUploadIDMarker string
        MaxUploads         int
        IsTruncated        bool
        Uploads            []struct {
            Key          string
            UploadID     string
            StorageClass string
            Initiator    *Initiator
            Owner        *Owner
            Initiated    string
        }
        Prefix         string
        Delimiter      string
        CommonPrefixes []string 
    }
    // Use the same type as the owner
    type Initiator Owner
    // Owner defines the Bucket/Object's owner
    type Owner struct {
        ID          string
        DisplayName string
    }
    Parameter Name Description Type
    Bucket Target bucket for multipart upload, format is BucketName. For example, examplebucket-1250000000 string
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url string
    - KeyMarker The key value where the entry list starts String
    - UploadIdMarker The UploadId value where the entry list starts String
    - NextKeyMarker If the returned list is truncated, the NextKeyMarker returned will be the starting point of the subsequent list String
    - NextUploadIdMarker If the returned list is truncated, the UploadId returned will be the starting point of the subsequent list String
    MaxUploads The maximum number of returned multipart uploads. It defaults to 1000. int
    IsTruncated Indicates whether the returned parts are truncated bool
    Uploads Information for each upload Container
    - - Key Object name String
    - UploadId Identifies the ID of this multipart upload String
    Key Indicates whether the returned parts are truncated bool
    - - StorageClass Indicates part storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE String
    Initiator Indicates information about the initiator of this upload Container
    Owner Indicates information about the owner of these parts Container
    - - Initiated Starting time of the multipart upload String
    prefix The returned Object key must be prefixed with Prefix. Note that the returned key will still contain Prefix when querying with prefix. NSString *
    delimiter The delimiter is a symbol. The delimiter is a symbol. The identical paths between prefix or, if no prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix String
    - CommonPrefixes The identical paths between Prefix and Delimiter are grouped and defined as a common prefix ObjectArray
    ID Unique CAM ID of users string
    DisplayName User Identifier (UIN) string

    Uploading the object via multipart upload

    This includes the following operations:

    • Multipart upload objects: Initializing multipart upload, uploading parts, and completing all multipart uploads
    • Delete the part uploaded

    Uploading the object via multipart upload, you can also use Advanced APIs to upload (recommended).

    -Initializing-multipart-upload">

    Initializing multipart upload

    Feature

    Initializing multipart upload, obtaining corresponding uploadId (Initiate Multipart Upload).

    Method Prototype

    func (s *ObjectService) InitiateMultipartUpload(ctx context.Context, name string, opt *InitiateMultipartUploadOptions) (*InitiateMultipartUploadResult, *Response, error)

    Request Samples

    name := "exampleobject"
    We recommend you not to set permissions on individual files when uploading so as to avoid reaching the limit. Bucket permission sets the default limit.
    v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
    if err != nil {
        panic(err)
    }
    UploadId=uploadid,

    Parameter Description

    type InitiateMultipartUploadOptions struct {
        *ACLHeaderOptions       
        *ObjectPutHeaderOptions 
    }
    type ACLHeaderOptions struct {
        XCosACL              string                           
        XCosGrantRead        string
        XCosGrantWrite       string 
        XCosGrantFullControl string                                           
    } 
    type ObjectPutHeaderOptions struct {
        CacheControl='string', 
        ContentDisposition='string', 
        ContentEncoding='string', 
        ContentType='string', 
        'ContentLength' => 'int',   
        'Expires' => 'string', 
        Custom x-cos-meta-* header
        XCosMetaXXX        *http.Header 
        XCosStorageClass   string      
    }
    
    Parameter Name Description Type Required
    r The content of the uploaded file, which can be a file stream or a byte stream. When r is not bytes.Buffer/bytes.Reader/strings.Reader, opt.ObjectPutHeaderOptions.ContentLength must be specified. io.Reader Yes
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    XCosACL Sets file ACL, such as private,public-read string No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No
    GrantRead Grants the grantee the read permission in the format of id="[OwnerUin]" String No
    StorageClass Sets the object storage class; value range: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String No
    Expires Sets Content-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
    ContentLength Sets transmission length string No
    XCosMetaXXX User-defined file meta information. It must start with x-cos-meta. Otherwise, it will be ignored. http.Header No

    Returned Result

    <InitiateMultipartUploadResult>
        Bucket   string
        Key      string
        UploadID string
    } 
    Parameter Name Description Type
    UploadId Indicates the ID of multipart upload string
    Bucket Bucket name, which is in a format of bucket-appid string
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string

    -Uploading-parts">

    Uploading parts

    This API (Upload Part) is used to upload a part.

    Method Prototype

    func (s *ObjectService) UploadPart(ctx context.Context, key, uploadID string, partNumber int, r io.Reader, opt *ObjectUploadPartOptions) (*Response, error)

    Request Samples

    # Note: The maximum number of parts to be uploaded is 10,000.
    $key = "exampleobject";
    f := strings.NewReader("test")
    "opt" is optional.
    resp, err := client.Object.UploadPart(
        context.Background(), key, UploadID, 1, f, nil,
    )
    if err != nil {
        panic(err)
    }
    PartETag = resp.Header.Get("ETag")

    Parameter Description

    type ObjectUploadPartOptions struct {
        'ContentLength' => 'int',
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    UploadId Indicates the ID of multipart upload, which is generated by InitiateMultipartUpload. string Yes
    PartNumber Indicates the number of the uploaded part int Yes
    r The content of the uploaded part, which can be a local file stream or an input stream. When r is not bytes.Buffer/bytes.Reader/strings.Reader, opt.ContentLength must be specified. io.Reader Yes
    ContentLength Sets transmission length. int No

    Returned Result

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

    -Querying-uploaded-parts">

    Querying uploaded parts

    Feature

    This API (List Parts) is used to query the uploaded parts in a specific multipart upload process.

    Method Prototype

    func (s *ObjectService) ListParts(ctx context.Context, name, uploadID string, opt *ObjectListPartsOptions) (*ObjectListPartsResult, *Response, error)
    

    Request Samples

    $key = "exampleobject";
    _, _, err := client.Object.ListParts(context.Background(), key, UploadID, nil)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectListPartsOptions struct {
        EncodingType     string
        MaxParts         string
        PartNumberMarker string                                      
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    UploadId Indicates the ID of multipart upload, which is generated by InitiateMultipartUpload. string Yes
    EncodingType Specifies the encoding type of the returned value String No
    MaxParts Maximum number of entries returned at a time. Default is 1,000. String No
    PartNumberMarker By default, entries are listed in UTF-8 binary order starting from the marker String No

    Returned Result

    type ObjectListPartsResult struct {
        Bucket               string
        EncodingType         string
        Key                  string
        UploadID             string
        Initiator            *Initiator
        Owner                *Owner
        StorageClass         string
        PartNumberMarker     string
        NextPartNumberMarker string
        MaxParts             string
        IsTruncated          bool
        Parts                []Object
    }
    type Initiator struct {
        UIN         string
        ID          string
        DisplayName string
    }
    type Owner struct {
        UIN         string
        ID          string
        DisplayName string
    }
    type Object struct {
        Key          string
        ETag         string
        Size         int
        PartNumber   int
        LastModified string
        StorageClass string 
        Owner        *Owner
    }
    Parameter Name Description Type
    String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url string
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string
    UploadId Indicates the ID of multipart upload, which is generated by InitiateMultipartUpload. string
    Initiator Creator of the multipart upload, including DisplayName, UIN and ID struct
    Owner Information of the file owner, including DisplayName, UIN and ID struct
    StorageClass Sets the object storage class; value range: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD String
    PartNumberMarker Indicates that the parts are listed from the one following PartNumberMarker. It defaults to 0, which means the parts are listed from the first one. String
    NextPartNumberMarker Marks the starting point of the next list of parts int
    MaxParts The maximum number of returned parts. It defaults to 1000. int
    IsTruncated Indicates whether the returned parts are truncated bool
    Part Information of the uploaded part, including ETag, PartNumber, Size, and LastModified struct

    Completing-multipart-upload">

    Completing multipart upload

    Feature

    This API (Complete Multipart Upload) is used to complete the entire multipart upload.

    Method Prototype

    func (s *ObjectService) CompleteMultipartUpload(ctx context.Context, key, uploadID string, opt *CompleteMultipartUploadOptions) (*CompleteMultipartUploadResult, *Response, error)
    

    Request Samples

    # Complete the multipart upload
    $key = "exampleobject";
    UploadId=uploadid
    
    opt := &cos.CompleteMultipartUploadOptions{}
    opt.Parts = append(opt.Parts, cos.Object{
        PartNumber: 1, ETag: PartETag},
    )
    
    _, _, err := client.Object.CompleteMultipartUpload(
        context.Background(), key, uploadID, opt,
    )
    if err != nil {
        panic(err)
    }

    Parameter Description

    type CompleteMultipartUploadOptions struct {
        Parts   []Object 
    }
    type Object struct { 
        'ETag': 'string', 
        PartNumber   int     
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    UploadId Indicates the ID of multipart upload, which is generated by InitiateMultipartUpload. string Yes
    CompleteMultipartUploadOptions ETag and PartNumber information for all parts struct Yes

    Returned Result

    <CompleteMultipartUploadResult>
        Location string
        Bucket   string
        Key      string
        ETag     string
    }
    
    Parameter Name Description Type
    Location URL address string
    String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string
    ETag The unique tag of the resulting object. It is not the MD5 check value for the object content, but is only used to check the uniqueness of the object. To verify the file content, you can check the ETag of each part during the process of upload. string

    -Terminating-multipart-upload">

    Terminating multipart upload

    Feature

    This API (Abort Multipart Upload) is used to abort a multipart upload operation and delete the uploaded parts.

    Method Prototype

    func (s *ObjectService) AbortMultipartUpload(ctx context.Context, key, uploadID string) (*Response, error)

    Request Samples

    $key = "exampleobject";
    Abort
    _, err := client.Object.AbortMultipartUpload(context.Background(), key, UploadID)
    if err != nil {
        panic(err)
    }

    Parameter Description

    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    UploadId Indicates the ID of multipart upload string Yes

    Other Operations

    Restoring an archived object

    Feature

    This API (POST Object restore) is used to restore an archived object.

    Method Prototype

    func (s *ObjectService) PostRestore(ctx context.Context, key string, opt *ObjectRestoreOptions) (*Response, error) 

    Request Samples

    key := "example_restore"
    f, err := os.Open("../test")
    if err != nil {
        panic(err)
    }
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentType:      "text/html",
            XCosStorageClass: "ARCHIVE", //Archive type
        },
        ACLHeaderOptions: &cos.ACLHeaderOptions{
            We recommend you not to set permissions on individual files when uploading so as to avoid reaching the limit. Bucket permission sets the default limit.
            XCosACL: "private",
        },
    }
    // Uploading an archived object
    _, err = client.Object.Put(context.Background(), key, f, opt)
    if err != nil {
        panic(err)
    }
    
    opts := &cos.ObjectRestoreOptions{
        Days: 2,
        Tier: &cos.CASJobParameters{
            // Standard, Exepdited and Bulk
            Tier: 'Expedited'
        },
    }
    ### Restoring an archived object
    _, err = client.Object.PostRestore(context.Background(), key, opts)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ObjectRestoreOptions struct {        
        Days    int               
        Tier    *CASJobParameters 
    }
    type CASJobParameters struct {
        Tier    string 
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    ObjectRestoreOptions Describes rules for retrieved temporary files struct Yes
    Days Describes the expiration time of the temporary object int Yes
    CASJobParameters Describes the configuration of the restoration type struct No
    Tier Describes the mode for retrieving temporary files. Possible values are "Expedited", "Standard", and "Bulk", which correspond to speed mode, standard mode, and batch mode string No

    Setting object ACL

    Feature

    This API (Put Object ACL) is used to set an ACL for an object.

    Method Prototype

    func (s *ObjectService) PutACL(ctx context.Context, key string, opt *ObjectPutACLOptions) (*Response, error)

    Request Samples

    // 1. Configuration via request header
    opt := &cos.ObjectPutACLOptions{
        Header: &cos.ACLHeaderOptions{
            XCosACL: "private",
        },
    }
    $key = "exampleobject";
    _, err := client.Object.PutACL(context.Background(), key, opt)
    if err != nil {
        panic(err)
    }
    // 2. Configuration via request body
    opt = &cos.ObjectPutACLOptions{
        Body: &cos.ACLXml{
            Owner: &cos.Owner{
                "ID": "qcs::cam::uin/100000000001:uin/100000000001",
            },
            AccessControlList: []cos.ACLGrant{
                {
                    Grantee: &cos.ACLGrantee{
                        Type: "RootAccount",
                        "ID": "qcs::cam::uin/100000000001:uin/100000000001",
                    },
    
                    Permission: "FULL_CONTROL",
                },
            },
        },
    }
    
    _, err = client.Object.PutACL(context.Background(), key, opt)
    if err != nil {
        panic(err)
    }

    Parameter Description

    type ACLHeaderOptions struct {
        XCosACL              string 
        XCosGrantRead        string 
        XCosGrantWrite       string 
        XCosGrantFullControl string 
    }
    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    XCosACL Sets object ACL, such as private, public-read string No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No
    GrantRead Grants the grantee the read permission in the format of id="[OwnerUin]" String No
    ACLXML Grants the specified account the access to buckets. For more information on the format, see the response for "get object acl". struct No

    Querying object ACL

    Feature

    This API (GET Object acl) is used to query object (or file) ACL.

    Method Prototype

    func (s *ObjectService) GetACL(ctx context.Context, key string) (*ObjectGetACLResult, *Response, error)

    Request Samples

    $key = "exampleobject";
    _, _, err := client.Object.GetACL(context.Background(), key)
    if err != nil {
        panic(err)
    }

    Parameter Description

    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes

    Returned Result

    type ACLXml struct {
        Owner             *Owner
        AccessControlList []ACLGrant 
    }
    type Owner struct { 
        ID          string 
        DisplayName string
    }
    type ACLGrant struct {
        Grantee    *ACLGrantee
        Permission string
    }
    type ACLGrantee struct {
        Type        string 
        ID          string 
        DisplayName string
        UIN         string 
    }
    Parameter Name Description Type
    Owner Information of the bucket owner, including DisplayName and ID struct
    AccessControlList Information of the user granted the bucket permissions, including Grantee and Permission struct
    Grantee Information of grantee, including DisplayName, Type, ID and UIN struct
    Type Type of grantee: CanonicalUser or Group string
    ID ID of grantee when Type is CanonicalUser string
    DisplayName Name of grantee string
    UIN UIN of grantee when Type is Group string
    Permission Bucket permissions of grantee. Available values: FULL_CONTROL (read and write permissions), WRITE (write permission), and READ (read permission) string

    Advanced APIs (Recommended)

    Uploading an object

    Feature

    The upload API automatically divides the data based on the length of the user file to facilitate usage, and the user does not need to worry about every step of the multipart upload.

    Method Prototype

    func (s *ObjectService) Upload(ctx context.Context, key string, filepath string, opt *MultiUploadOptions) (*CompleteMultipartUploadResult, *Response, error)

    Request Samples

    $key = "exampleobject";
    file := "../test"
    
    _, _, err := client.Object.Upload(
        context.Background(), key, file, nil,
    )
    if err != nil {
        panic(err)
    }

    Parameter Description

    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string Yes
    filepath Name of the local file string Yes
    opt Object attributes Struct No
    OptIni Sets object attributes and ACL. For details, refer to InitiateMultipartUploadOptions Struct No
    PartSize Size of parts, unit in MB, Go SDK automatically divides the parts if not specified by users or specified as partSize <= 0 int No
    ThreadPoolSize Size of the thread pool, default size is 1 int No

    Returned Result

    <CompleteMultipartUploadResult>
        Location string
        Bucket   string
        Key      string
        ETag     string
    }
    
    Parameter Name Description Type
    Location URL address string
    String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    key ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the ObjectKey is doc/pic.jpg string
    ETag The unique tag of the resulting object. It is not the MD5 check value for the object content, but is only used to check the uniqueness of the object. To verify the file content, you can check the ETag of each part during the process of upload. string

    Was this page helpful?

    Was this page helpful?

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