Object Operations

Last updated: 2020-06-17 10:09:54

    Overview

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

    Simple operations

    API Operation Description
    GET Bucket (List Object) Querying an object list Queries all or a subnet of objects in a bucket
    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 Copying an object Copies a file to a destination path
    DELETE Object Deleting a single object Deletes the specified object in the bucket
    DELETE Multiple Objects Deleting multiple objects Deletes multiple objects in a bucket with a single request

    Multipart operations

    API Operation Description
    List Multipart Uploads Querying multipart uploads Queries in-progress multipart uploads
    Initiate Multipart Upload Initializing multipart upload Initializes a multipart upload operation
    Upload Part Uploading parts Uploads file parts
    Upload Part - Copy Copying a part Copies an object as a part
    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 Restoring an archived object Restores an archived object for access
    PUT Object acl Setting object ACL Sets the ACL for the specified object in a bucket
    GET Object acl Querying object ACL Queries the ACL of an object

    Simple Operations

    Querying object list

    Feature

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

    Method prototype

    public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    listObjectsRequest Request for obtaining a file list ListObjectsRequest

    Request member description:

    Request Member Setting Method                     Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    prefix Constructor or set method Limiting the returned result objects, prefixed with prefix. By default, there is no limit, and the default value for all Bucket members
    is empty: ""
    String
    marker Constructor or set method Marking the starting position of the list, which can be set to empty for the first time, and subsequent requests need to be set to the nextMarker in the previous returned listObjects value String
    delimiter Constructor or set method Delimiter. It indicates that the path that starts with "prefix" and ends with delimiter for the first time will be returned. String
    maxKeys Constructor or set method The maximum number of returned members (up to 1,000).
    Default: 1,000
    Integer

    Response

    • Successful: Returns ObjectListing class, including all members and nextMarker.
    • Failure: Throws CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
    // Set bucket name
    listObjectsRequest.setBucketName(bucketName);
    // The prefix indicates the keys of the listed objects started with the prefix
    listObjectsRequest.setPrefix("images/");
    // The delimiter indicates the separator. Set "/" to list objects in the current directory; set to null to list all objects.
    listObjectsRequest.setDelimiter("/");
    // Set the maximum number of traversed objects (up to 1,000 per listobject request)
    listObjectsRequest.setMaxKeys(1000);
    ObjectListing objectListing = null;
    do {
        try {
            objectListing = cosClient.listObjects(listObjectsRequest);
        } catch (CosServiceException e) {
            e.printStackTrace();
            return;
        } catch (CosClientException e) {
            e.printStackTrace();
            return;
        }
        // The common prefix indicates the path truncated by delimiter. If the delimiter is set to "/", the common prefix indicates the paths of all subdirectories
        List<String> commonPrefixs = objectListing.getCommonPrefixes();
    
        // The object summary indicates a list of all listed objects
        List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();
        for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {
            // File path key
            String key = cosObjectSummary.getKey();
            // File Etag
            String etag = cosObjectSummary.getETag();
            // File length
            long fileSize = cosObjectSummary.getSize();
            // File storage class
            String storageClasses = cosObjectSummary.getStorageClass();
        }
    
        String nextMarker = objectListing.getNextMarker();
        listObjectsRequest.setMarker(nextMarker);
    } while (objectListing.isTruncated());

    Uploading an object using simple upload

    Feature

    This API (Put Object) is used to upload objects to the specified bucket. Uploading a local file or an input stream of known length to COS. It is suitable for uploading small image files (below 20MB), a maximum of 5GB (inclusive) is supported, please use Multipart Upload or Advanced API to upload if more than 5GB.

    • The file length and MD5 are checked by default during upload (see the sample code for disabling MD5 check).
    • If an object with the same key already exists in COS, it will be overwritten by the newly-uploaded one.
      The number of access policies is up to 1000. Do not set object ACL control if it is not required. The object inherits the bucket permissions by default.
    • Once uploaded, you can download the file by calling the GetObject API with the same key, or by generating a pre-signed URL, and sending the file to another device for download.

    Method prototype

    // Method 1: Upload a local file to COS
    public PutObjectResult putObject(String bucketName, String key, File file)
                throws CosClientException, CosServiceException;
    // Method 2: Upload an input stream to COS
    public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
                throws CosClientException, CosServiceException;
    // Method 3: Encapsulate the two methods above to support more fine-grained parameter control, such as content-type and content-disposition
    public PutObjectResult putObject(PutObjectRequest putObjectRequest)
                throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    putObjectRequest File upload request PutObjectRequest

    Request members:

    Request Member Setting Method              Description Type Required
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String Yes
    key Constructor or set method The object key 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/picture.jpg, the object key is doc/picture.jpg, see ObjectKey
    String Yes
    file Constructor or set method Local File File No
    input Constructor or set method Input Stream InputStream No
    metadata Constructor or set method Metadata of an object ObjectMetadata No
    trafficLimit set method Traffic limits (in bit/s) on the uploaded object. Default: none int No

    The ObjectMetadata class is used to record the meta information of an object. The main members are described as follows:

    Member Name Description Type
    httpExpiresDate Cache timeout, which is the value of the Expires field in the HTTP response header Date
    ongoingRestore Restoring this object from ARCHIVE Boolean
    userMetadata User-defined metadata prefixed with x-cos-meta- Map <String, String>
    metadata Headers other than user-defined metadata Map<String, String>
    restoreExpirationTime Expiration time for an object copy restored from ARCHIVE Date

    Response

    • Successful: PutObjectResult, including the file ETag and other information.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Response parameters

    The PutObjectResult class is used to return result information, and main members are described as follows:

    Member Name Description Type
    requestId Request ID String
    dateStr Current server time String
    versionId Enabling a versioned bucket and version ID of the object is returned String
    eTag MD5 value of the object returned by simple upload API String
    crc64Ecma The CRC64 value computed by the server based on the object String

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    // Method 1: Upload a local file
    File localFile = new File(localFilePath);
    String key = "exampleobject";
    PutObjectResult putObjectResult = cosClient.putObject(bucketName, key, localFile);
    String etag = putObjectResult.getETag();  // Obtain the file etag
    
    // Method 2: Upload an input stream (The length of a input stream must be known in advance. Otherwise, it may cause oom)
    FileInputStream fileInputStream = new FileInputStream(localFile);
    ObjectMetadata objectMetadata = new ObjectMetadata();
    // Set the length of an input stream to 500
    objectMetadata.setContentLength(500);
    // Set Content type. Default: application/octet-stream
    objectMetadata.setContentType("application/pdf");
    putObjectResult = cosClient.putObject(bucketName, key, fileInputStream, objectMetadata);
    etag = putObjectResult.getETag();
    // Close the input stream...
    
    // Method 3: Provide more fine-grained control. Common settings are as follows
    // 1 Storage-class. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD
    // 2. Content-type. For local file upload, the files are mapped based on the suffix by default. For example, the jpg file is mapped as image/jpeg
    // For input stream upload, the default is application/octet-stream
    // 3. Set permissions when uploading (or by calling API set object acl)
    // 4 To disable MD5 upload verification globally, set the system environment variable. This will affect all upload verification. Verification is performed by default.
    // Disable M5 verification: System.setProperty(SkipMd5CheckStrategy.DISABLE_PUT_OBJECT_MD5_VALIDATION_PROPERTY, "true");
    // Enable M5 verification: System.setProperty(SkipMd5CheckStrategy.DISABLE_PUT_OBJECT_MD5_VALIDATION_PROPERTY, null);
    localFile = new File(localFilePath);
    key = "picture.jpg";
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    // Set the storage class to STANDARD_IA
    putObjectRequest.setStorageClass(StorageClass.Standard_IA);
    // Set custom attributes (such as content-type, content-disposition)
    ObjectMetadata objectMetadata = new ObjectMetadata();
    // Here, set the upload bandwidth limit in bit/s to 10 MB/s
    putObjectRequest.setTrafficLimit(80*1024*1024);
    // Set Content type. Default: application/octet-stream
    objectMetadata.setContentType("image/jpeg");
    putObjectRequest.setMetadata(objectMetadata);
    PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
    // Get Etag of the object
    String etag = putObjectResult.getETag();
    // Get CRC64 value of the object
    String crc64Ecma = putObjectResult.getCrc64Ecma();

    Querying object metadata

    Feature

    This API (HEAD Object) is used to query whether the specified object exists in the bucket.

    Method prototype

    public ObjectMetadata getObjectMetadata(String bucketName, String key)
                throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key The object key 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/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey String

    Response

    • Successful: No value is returned.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    ObjectMetadata objectMetadata = cosClient.getObjectMetadata(bucketName, key);

    Downloading an object

    Feature

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

    Method prototype

    // Method 1: Download the file and get the input stream
    public COSObject getObject(GetObjectRequest getObjectRequest)
                throws CosClientException, CosServiceException;
    // Method 2: Download the file locally.
    public ObjectMetadata getObject(GetObjectRequest getObjectRequest, File destinationFile)
                throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    getObjectRequest File download request GetObjectRequest
    destinationFile Locally saved file File

    Request members:

    Request Member Setting Method                     Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key Constructor or set method The object key 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/picture.jpg, the object key is doc/picture.jpg, see ObjectKey String
    range Set Method Download Range Long[]
    trafficLimit Set Method Traffic limits (in bit/s) on the downloaded object. Default: none. int

    Response

    • Method 1 (Get the input stream of the downloaded file)
      • Successful: Returns COSObject type, including the input stream and file attributes.
      • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.
    • Method 2 (Download the file locally)
      • Successful: Returns the file attribute objectMetadata, including the file's custom header, content-type and other attributes.
      • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Response parameters

    The COSObject class is used to return request results, and includes main members as follows:

    Member Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key The object key 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/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey String
    metadata Object metadata ObjectMetadata
    objectContent Data stream that contains COS object content COSObjectInputStream

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    // Method 1: Get the input stream of the downloaded file
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    // Here, set the download bandwidth limit in bit/s to 10 MB/s
    getObjectRequest.setTrafficLimit(80*1024*1024);
    COSObject cosObject = cosClient.getObject(getObjectRequest);
    COSObjectInputStream cosObjectInput = cosObject.getObjectContent();
    // Download CRC64 value of the object
    String crc64Ecma = cosObject.getObjectMetadata().getCrc64Ecma();
    
    // Method 2 (Download the file locally)
    String outputFilePath = "exampleobject";
    File downFile = new File(outputFilePath);
    getObjectRequest = new GetObjectRequest(bucketName, key);
    ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);

    Setting object replication

    Feature

    This API [PUT Object - Copy] is used to replicate an object. You can replicate an object up to 5 G in size across regions, accounts, and buckets, provided that you have Read access to the source file and Write access to the destination file. To copy files larger than 5 G, use the advanced APIs.

    Method prototype

    public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
                throws CosClientException, CosServiceException

    Parameter description

    Parameter Name Description Type
    copyObjectRequest File copy request CopyObjectRequest

    Request members:

    Member Name Description Type
    sourceBucketRegion Region of the source Bucket. Default: same with the region of the current clientconfig, which represents an intra-region copy String
    sourceBucketName Source bucket name, naming format is BucketName-APPID. For details, see ObjectKey String
    sourceKey Source object key. The object key is the unique identifier of the object in the bucket. For example, in the object's access domain examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey. String
    sourceVersionId Version ID of the source file (for source buckets with versioning enabled). Default: The latest version of the source file String
    destinationBucketName Name of the destination bucket. The bucket should be named in a format of BucketName-APPID, where the name should be comprised of letters, numbers, and dashes. String
    destinationKey Destination object key. The object key is the unique identifier of the object in the bucket. For example, in the object's access domain examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey. String
    storageClass Sets file storage class. Enumerated values: STANDARD and STANDARD_IA. Default: STANDARD String

    Response

    • Successful: Returns CopyObjectResult, including Etag and other information of the new file.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Replicate a file in the same account and region
    // Enter the bucket name in the format of BucketName-APPID.
    String srcBucketName = "sourcebucket-1250000000";
    // The source file to be copied
    String srcKey = "sourceObject";
    // Enter the bucket name in the format of BucketName-APPID.
    String destBucketName = "examplebucket-1250000000";
    // The destination file to be copied into
    String destKey = "exampleobject";
    CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketName, srcKey, destBucketName, destKey);
    CopyObjectResult copyObjectResult = cosClient.copyObject(copyObjectRequest);
    
    // Cross-account and cross-region replication (The read permission to source file and the write permission to destination file are required)
    String srcBucketNameOfDiffAppid = "bucket-own-by-others-1251668577";
    Region srcBucketRegion = new Region("ap-shanghai");
    copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketNameOfDiffAppid, srcKey, destBucketName, destKey);
    copyObjectResult = cosClient.copyObject(copyObjectRequest);
    // Get CRC64 value of the object
    String crc64Ecma = copyObjectResult.getCrc64Ecma();

    Deleting a single object

    Feature

    This API (Delete Object) is used to delete the specified object.

    Method prototype

    public void deleteObject(String bucketName, String key)
                throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key The object key 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/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey String

    Response

    • Successful: No value is returned.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    cosClient.deleteObject(bucketName, key);

    Deleting multiple objects

    Feature

    The API(DELETE Multiple Objects)is used to delete multiple objects.

    Method prototype

    public DeleteObjectsResult deleteObjects(DeleteObjectsRequest deleteObjectsRequest)
        throws MultiObjectDeleteException, CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    deleteObjectsRequest Request DeleteObjectsRequest

    Request member description:

    Member Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    quiet Indicating the method by which the result is returned for the deletion. Available values: true and false. Defaults to false. If it is set to true, only error message for failed deletion is returned. If it is set to false, messages indicating successful and failed deletion are returned. boolean
    keys list of object paths, version number of the object is optional List<DeleteObjectsRequest.KeyVersion>

    DeleteObjectsRequest.KeyVersion members are described as follows:

    Member Name Description Type
    key The key 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/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey String
    version When enabling bucket versioning, specify the version number of the deleted object, optional String

    Response

    • Successful: No value is returned.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    
    DeleteObjectsRequest deleteObjectsRequest = new DeleteObjectsRequest(bucketName);
    // Set the list of keys to be deleted. A maximum of 1,000 keys can be deleted at a time
    ArrayList<DeleteObjectsRequest.KeyVersion> keyList = new ArrayList<DeleteObjectsRequest.KeyVersion>();
    // Enter the names of files to be deleted
    keyList.add(new DeleteObjectsRequest.KeyVersion("project/folder1/picture.jpg"));
    keyList.add(new DeleteObjectsRequest.KeyVersion("project/folder2/text.txt"));
    keyList.add(new DeleteObjectsRequest.KeyVersion("project/folder2/music.mp3"));
    deleteObjectsRequest.setKeys(keyList);
    
    // Delete files in batches
    try {
        DeleteObjectsResult deleteObjectsResult = cosClient.deleteObjects(deleteObjectsRequest);
        List<DeleteObjectsResult.DeletedObject> deleteObjectResultArray = deleteObjectsResult.getDeletedObjects();
    } catch (MultiObjectDeleteException mde) { // If not all the objects are deleted successfully, MultiObjectDeleteException is returned
        List<DeleteObjectsResult.DeletedObject> deleteObjects = mde.getDeletedObjects();
        List<MultiObjectDeleteException.DeleteError> deleteErrors = mde.getErrors();
    } catch (CosServiceException e) { // For other errors such as parameter error, identity authentication will not throw CosServiceException
        e.printStackTrace();
        throw e;
    } catch (CosClientException e) { // For client error, such as COS connection fails
        e.printStackTrace();
        throw e;
    }

    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

    public MultipartUploadListing listMultipartUploads(
                ListMultipartUploadsRequest listMultipartUploadsRequest)
                throws CosClientException, CosServiceException

    Parameter description

    Parameter Name Description Type
    listMultipartUploadsRequest Request ListMultipartUploadsRequest

    Request members:

    Member Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    keyMarker The key value where the entry list starts String
    delimiter Delimiter is a sign. If Prefix exists, the same paths between Prefix and delimiter are grouped as the same type and defined as Common Prefix, and then all Common Prefixes are listed. If Prefix does not exist, the listing process starts from the beginning of the path String
    prefix The returned Object key must be prefixed with Prefix. Note that the returned key will still contain Prefix when querying with prefix. String
    uploadIdMarker The UploadId value where the entry list starts String
    maxUploads Sets the maximum number of multipart returned. Valid values: 1-1000 String
    encodingType Specifies the encoding type of the returned values; valid value: url String

    Response

    • Successful: Returns MultipartUploadListing, which contains information that multipart upload is in progress.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    listMultipartUploadsRequest.setDelimiter("/");
    listMultipartUploadsRequest.setMaxUploads(100);
    listMultipartUploadsRequest.setPrefix("");
    listMultipartUploadsRequest.setEncodingType("url");
    MultipartUploadListing multipartUploadListing = cosClient.listMultipartUploads(listMultipartUploadsRequest);

    Uploading object via multipart upload

    Operations related to multipart uploads include the following:

    • Multipart upload of objects: initializing multipart upload, uploading parts, and completing multipart upload
    • Resuming multipart upload: querying parts uploaded, uploading parts, and completing multipart upload
    • Aborting multipart upload

    Initializing multipart upload

    Feature

    This API (Initiate Multipart Upload) is used to initialize a multipart upload task.

    Method prototype

    public InitiateMultipartUploadResult initiateMultipartUpload(
        InitiateMultipartUploadRequest request) throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    initiateMultipartUploadRequest Request InitiateMultipartUploadRequest

    Request members:

    Member Name Setting Method Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key Constructor or set method The ObjectKey of an object stored in COS String

    Response

    • Successful: Returns InitiateMultipartUploadResult type, including the upload ID required for subsequent multipart upload.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    InitiateMultipartUploadRequest initRequest = new InitiateMultipartUploadRequest(bucketName, key);
    InitiateMultipartUploadResult initResponse = cosClient.initiateMultipartUpload(initRequest);
    uploadId = initResponse.getUploadId();

    Uploading parts

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

    Method prototype

    public UploadPartResult uploadPart(UploadPartRequest uploadPartRequest) throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    uploadPartRequest Request UploadPartRequest

    Request members:

    Member Name Setting Method Description Type
    bucketName Set Method Bucket naming format is BucketName-APPID. For details, see Naming Conventions String
    key Set Method The ObjectKey of an object stored in COS String
    uploadId Set Method Identifies the uploadId of the specified multipart upload String
    partNumber Set Method Identifies the number of the specified multipart, must be>=1 int
    inputStream Set Method Input stream to be uploaded in multi-parts InputStream
    trafficLimit Set Method Traffic limits (in bit/s) on uploaded parts. Not configured by default. int

    Response

    • Successful: Returns UploadPartResult, which contains the eTag information of the uploaded parts.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Response parameters

    The UploadPartResult class is used to return request results, and includes members as follows:

    Member Name Description Type
    partNumber An identifier of the specified part String
    eTag Returns MD5 hash of the part String
    crc64Ecma CRC64 value computed by the server based on the part String

    Request samples

    // Upload up to 10,000 parts with a size ranging from 1 M-5 G.
    // Set the size of each part to 4 MB. If there are a total of n parts, the size of part 1 to part n-1 is the same, and the last part is less than or equal to the size of previous parts.
    partETags = new ArrayList<PartETag>();
    int partNumber = 1;
    int partSize = 4 * 1024 * 1024;
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    byte data[] = new byte[partSize];
    ByteArrayInputStream partStream = new ByteArrayInputStream(data);
    // partStream represents the input stream of the part's data. The length of input stream is partSize.
    UploadPartRequest uploadRequest = new UploadPartRequest().withBucketName(bucketName).
            withUploadId(uploadId).withKey(key).withPartNumber(partNumber).
            withInputStream(partStream).withPartSize(partSize);
    UploadPartResult uploadPartResult = cosClient.uploadPart(uploadRequest);
    // Obtain Etag of the part.
    String etag = uploadPartResult.getETag();
    // Obtain CRC64 value of the part.
    String crc64Ecma = uploadPartResult.getCrc64Ecma();
    partETags.add(new PartETag(partNumber, eTag));  // partETags records the Etags of all uploaded parts
    // ... Upload parts with the partNumber of 2 to n

    Copying parts

    Feature

    This API (Upload Part - Copy) is used to copy the parts of an object from a source path to a destination path.

    Method prototype

    public CopyPartResult copyPart(CopyPartRequest copyPartRequest) throws CosClientException, CosServiceException

    Parameter description

    Parameter Name Description Type
    copyPartRequest Request CopyPartRequest

    Request members:

    Member Name Setting Method Description Type
    destinationBucketName Set Method Destination bucket name, Bucket naming format is BucketName-APPID. For details, see Naming Conventions String
    destinationKey Set Method Destination object key, i.e., the ObjectKey of the object stored in COS String
    uploadId Set Method Identifies the uploadId of the specified multipart upload String
    partNumber Set Method Identifies the number of the specified multipart, must be>=1 int
    sourceBucketRegion Set Method Source bucket region Region
    sourceBucketName Set Method Source bucket name String
    sourceKey Set Method Source object key, i.e., the ObjectKey of the object stored in COS String
    firstByte Set Method First byte offset of the source object Long
    lastByte Set Method Last byte offset of the source object Long

    Response

    • Successful: CopyPartResult is returned, including the ETag information of the part.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Bucket name. Format: BucketName-APPID
    // Set destination bucket name, object name and multipart upload ID
    String destinationBucketName = "examplebucket-1250000000";
    String destinationTargetKey = "exampleobject";
    int partNumber = 1;
    CopyPartRequest copyPartRequest = new CopyPartRequest();
    copyPartRequest.setDestinationBucketName(destinationBucketName);
    copyPartRequest.setDestinationKey(destinationTargetKey);
    copyPartRequest.setUploadId(uploadId);
    copyPartRequest.setPartNumber(partNumber);
    // Set the region and name of the source bucket, object name and offset range
    String sourceBucketRegion = "COS_REGION";
    String sourceBucketName = "sourcebucket-1250000000";
    String sourceKey = "sourceObject";
    Long firstByte = 1L;
    Long lastByte = 1048576L;
    copyPartRequest.setSourceBucketRegion(new Region(sourceBucketRegion));
    copyPartRequest.setSourceBucketName(sourceBucketName);
    copyPartRequest.setSourceKey(sourceKey);
    copyPartRequest.setFirstByte(firstByte);
    copyPartRequest.setLastByte(lastByte);
    
    CopyPartResult copyPartResult = cosClient.copyPart(copyPartRequest);
    partETags = new ArrayList<PartETag>();
    partETags.add(copyPartResult.getPartETag());

    Querying uploaded parts

    Feature

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

    Method prototype

    public PartListing listParts(ListPartsRequest request)
                throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Setting Method Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key Constructor or set method Object Name String
    uploadId Constructor or set method UploadId of the multipart upload to be queried String
    maxParts Maximum number of entries returned at a time. Default value: 1,000 String
    PartNumberMarker By default, entries are listed in UTF-8 binary order starting from the marker String
    - Encoding-type Specifies the encoding type of the returned value String

    Response

    • Successful: Returns PartListing, including the ETag and No. of each part as well as the starting marker of the next list.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // ListPart is used to obtain the information of the uploaded part based on uploadId before the multipart upload is completed or aborted. It can be used to construct partEtags.
    List<PartETag> partETags = new ArrayList<PartETag>();
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, key, uploadId);
    PartListing partListing = null;
    do {
        partListing = cosClient.listParts(listPartsRequest);
        for (PartSummary partSummary : partListing.getParts()) {
            partETags.add(new PartETag(partSummary.getPartNumber(), partSummary.getETag()));
        }
        listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
    } while (partListing.isTruncated());

    Completing multipart upload

    Feature

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

    Method prototype

    public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request) throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Setting Method             Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Bucket Overview String
    key Constructor or set method The ObjectKey of an object stored in COS String
    uploadId Constructor or set method Identifies the specified uploadId for multipart upload String
    partETags Constructor or set method Identifies the number of the parts and the eTag returned by the upload List<PartETag>

    Response

    • Successful: Returns CompleteMultipartUploadResult, including the Etag of the entire file.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Complete multipart upload
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    CompleteMultipartUploadRequest compRequest = new CompleteMultipartUploadRequest(bucketName, key, uploadId, partETags);
    CompleteMultipartUploadResult result = cosClient.completeMultipartUpload(compRequest);

    Aborting multipart upload

    Feature

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

    Method prototype

    public void abortMultipartUpload(AbortMultipartUploadRequest request)  throws CosClientException, CosServiceException;

    Parameter description

    Member Name Setting Method Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key Constructor or set method The ObjectKey of an object stored in COS String
    uploadId Constructor or set method Identifies the specified uploadId for multipart upload string

    Response

    • Successful: No value is returned.
    • Failure: An error occurs (such as authentication failure), with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // abortMultipartUpload is used to abort an uncompleted multipart upload
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    AbortMultipartUploadRequest abortMultipartUploadRequest = new AbortMultipartUploadRequest(bucketName, key, uploadId);
    cosClient.abortMultipartUpload(abortMultipartUploadRequest);

    Other operations

    Restoring an archived object

    Feature

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

    Method prototype

    public void restoreObject(RestoreObjectRequest restoreObjectRequest)
        throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    restoreObjectRequest Request class RestoreObjectRequest

    Request members:

    Member Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key The key is the unique identifier of the object in the bucket. For example, in the object's access examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see Object Overview String
    expirationInDays Specifies the number of days before a restored temporary file expires int
    casJobParameters Describes the restore mode configuration. You can call the setTier API to set one of the three restore modes: Tier.Standard, Tier.Expedited. Tier.Bulk. CASJobParameters

    Response

    • Successful: No value is returned.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    
    // Set the number of days before a restored temporary copy expires to 1
    RestoreObjectRequest restoreObjectRequest = new RestoreObjectRequest(bucketName, key, 1);
    // Set the restore mode to Standard. Other available modes include Expedited and Bulk. The three restore modes have different cost and speed.
    CASJobParameters casJobParameters = new CASJobParameters();
    casJobParameters.setTier(Tier.Standard);
    restoreObjectRequest.setCASJobParameters(casJobParameters);
    cosClient.restoreObject(restoreObjectRequest);

    Setting object ACL

    Feature

    This API is used to set the ACL for the specified object in a bucket.

    The number of access policies is up to 1000. Do not set object ACL control if it is not required. The object inherits the bucket permissions by default.

    ACL includes a predefined permission policy (CannedAccessControlList) or a custom permission control (AccessControlList). If both of them are set, the predefined policy will be ignored and the custom policy prevails. For more information on permissions, please see the permission section.

    Method prototype

    // Method 1 (Set custom policy)
    public void setObjectAcl(String bucketName, String key, AccessControlList acl)
           throws CosClientException, CosServiceException
    // Method 2 (Set predefined policy)
    public void setObjectAcl(String bucketName, String key, CannedAccessControlList acl)
           throws CosClientException, CosServiceException
    // Method 3 (Encapsulation of the two methods above, including setting of these two policies. If both of them are set, the custom policy prevails.)
    public void setObjectAcl(SetObjectAclRequest setObjectAclRequest)
      throws CosClientException, CosServiceException;

    Parameter description

    • Method 3 Its parameters are illustrated because they contain those for Method 1 and 2.
    Parameter Name Description Type
    SetObjectAclRequest Class for requesting permission configuration setObjectAclRequest

    Request members:

    Request Member Setting Method                     Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key Constructor or set method The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg. For more information, see ObjectKey. String
    acl Constructor or set method Custom permission policy AccessControlList
    cannedAcl Constructor or set method Predefined policies, such as public read, public read and write, private read CannedAccessControlList
    Member Name Description Type
    List<Grant> Contains information of all users to be authorized Array
    owner The owner of the Object or Owner Owner class

    Grant class members:

    Member Name Description Type
    grantee Grantee identity information Grantee
    permission Authorized permission information (such as readable, writable, readable & writable) Permission

    Owner class members:

    Member Name Description Type
    id Identity information of an owner String
    displayname Owner's name (same as ID) String

    CannedAccessControlList represents a preset policy for everyone. It is an enumeration type with the following enumerated values.

    Enumerated Value Description
    Private Private read and write (only the owner can read and write)
    PublicRead Public read and private write (the owner can read and write, while other users can read)
    PublicReadWrite Public read and write (everyone can read and write)

    Response

    • Successful: No value is returned.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // The identity information in permissions must be formatted. The format for the root account and sub-accounts is as follows:
    // Both root_uin and sub_uin below must be valid QQ numbers
    // The root account qcs::cam::uin/<root_uin>:uin/<root_uin> indicates that the root_uin is granted to the root account (that is, the first and second uin are the same)
    // For example, qcs::cam::uin/2779643970:uin/2779643970
    // The sub-account qcs::cam::uin/<root_uin>:uin/<sub_uin> indicates that the sub_uin is granted to the root_uin.
    // For example, qcs::cam::uin/2779643970:uin/2779643970 
    Bucket. Format: BucketName-APPID
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    // Set a custom ACL
    AccessControlList acl = new AccessControlList();
    Owner owner = new Owner();
    // Set the owner, which can only be a root account.
    owner.setId("qcs::cam::uin/100000000001:uin/100000000001");
    acl.setOwner(owner);
    
    // Grant the root account 73410000 read and write permissions
    UinGrantee uinGrantee1 = new UinGrantee("qcs::cam::uin/2779643970:uin/2779643970");
    acl.grantPermission(uinGrantee1, Permission.FullControl);
    cosClient.setObjectAcl(bucketName, key, acl);
    
    // Set a predefined ACL
    // Set private read and write (The object inherits bucket permissions by default)
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.Private);
    // Set public read and private write
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicRead);
    // Set public read and write
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicReadWrite);

    Getting object ACL

    Feature

    This API (Get Object ACL) is used to get the ACL of an object.

    Method prototype

    public AccessControlList getObjectAcl(String bucketName, String key)
      throws CosClientException, CosServiceException;

    Parameter description

    Parameter Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key The key is the unique identifier of the object in the bucket. For example, in the object's access examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see Object Overview String

    Response

    • Successful: Returns the ACL to which the Object resides.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    Bucket. Format: BucketName-APPID
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    AccessControlList accessControlList = cosclient.getObjectAcl(bucketName, key);
    // Get file permission in the form of preset ACL. Valid values: Private, PublicRead, Default
    CannedAccessControlList cannedAccessControlList = accessControlList.getCannedAccessControl();

    Advanced APIs (recommended)

    The advanced API encapsulates upload and download APIs using the TransferManger class. It has a thread pool inside to accept users' upload and download requests, so users can choose to submit tasks asynchronously.

    // The size of the thread pool. If client and COS network are sufficient (for example, use Tencent Cloud CVM and upload COS in the same region), we recommended you set it to 16 or 32 to fully utilize network resources.
    // If public network is used for transmission and network bandwidth quality is poor, we recommended you lower this value to avoid timeout caused by slow network speed.
    ExecutorService threadPool = Executors.newFixedThreadPool(32);
    // Input a threadpool. If there is no thread pool, a single-thread pool will be generated in TransferManager by default.
    TransferManager transferManager = new TransferManager(cosClient, threadPool);
    // Set the threshold and size of parts for multipart upload through advanced API to 10 MB
    TransferManagerConfiguration transferManagerConfiguration = new TransferManagerConfiguration();
    transferManagerConfiguration.setMultipartUploadThreshold(10 * 1024 * 1024);
    transferManagerConfiguration.setMinimumUploadPartSize(10 * 1024 * 1024);
    transferManager.setConfiguration(transferManagerConfiguration);

    Closing transferManager manually after use to prevent resource leakage.

    // Close TransferManger
    transferManager.shutdownNow();

    Parameter description

    The TransferManagerConfiguration class is used to record the configuration of advanced APIs. Its main members are described as follows:

    Member Name Setting Method Description Type
    minimumUploadPartSize Set Method Part size in bytes for multipart upload. Default: 5 MB long
    multipartUploadThreshold Set Method If a file is greater than or equal to this value, it will be uploaded in concurrent parts. Unit: byte; default: 5 MB long
    multipartCopyThreshold Set Method If a file is greater than or equal to this value, it will be copied in concurrent parts. Unit: Byte; default: 5 GB long
    multipartCopyPartSize Set Method Part size in bytes for multipart replication. Default: 100 MB long

    Uploading an object

    Feature

    This API (Upload) automatically determines simple or multipart upload depending on the length and data type of your file, as shown below:

    • Determines simple upload for stream uploads below the multipart upload threshold, OR without Content-Length header;
    • Determines multipart upload for stream uploads above the multipart upload threshold, AND without Content-Length header;
    • Determines multipart upload with concurrent threads for files with File as data type.

    For information on other configuration attributes, storage classes, and MD5 check, see PUT Object API.

    Method prototype

    // Upload an object
    public Upload upload(final PutObjectRequest putObjectRequest)
                throws CosServiceException, CosClientException;

    Parameter description

    Parameter Name Description Type
    putObjectRequest File upload request PutObjectRequest

    Request members:

    Request Member Setting Method                     Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key Constructor or set method The object key 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/picture.jpg, the object key is doc/picture.jpg, see ObjectKey
    String
    file Constructor or set method Local File File
    input Constructor or set method Input Stream InputStream
    metadata Constructor or set method Metadata of a file ObjectMetadata
    trafficLimit set method Traffic limits (in bit/s) on the uploaded object. Default: none int

    When concurrent parts are uploaded, trafficLimit is the limits on the upload speed of each part. In this case, you need to adjust the number of threads in the thread pool to control the upload speed.

    Response

    • Successful: Returns Upload. You can query whether the upload is completed, or wait until the upload finishes synchronously.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Response parameters

    The UploadResult class records uploaded objects requested by calling the waitForUploadResult() method from the Upload API. The main class members are as follows:

    Member Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key The object key 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/picture.jpg, the object key is doc/picture.jpg, see ObjectKey
    String
    requestId Request Id String
    dateStr The current server time String
    versionId Returned version ID of an object in a versioning-enabled bucket String
    crc64Ecma The CRC64 computed by the server based on the object String

    Request samples

    // Sample 1:
    // Enter the bucket name in the format of BucketName-APPID
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    File localFile = new File(localFilePath);
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    // Upload a local file
    Upload upload = transferManager.upload(putObjectRequest);
    // Wait for the transfer to finish (call waitForCompletion if you want to wait for the upload to finish synchronously)
    UploadResult uploadResult = upload.waitForUploadResult();
    
    // Sample 2. Use checkpoint restart for files larger than the maximum part size
    // Step 1: Get PersistableUpload
    String bucketName = "examplebucket-1250000000";
    String key = "exmpleobject";
    File localFile = new File("exmpleobject");
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    // Upload a local file
    PersistableUpload persistableUpload = null;
    // Set the speed in bit/s of simple upload or part upload to 8 MB/s in the SDK
    // Note: concurrent parts are uploaded for data that exceeds the part threshold and has File as data type. To control the part upload speed, adjust the size of your thread pool.
    putObjectRequest.setTrafficLimit(64*1024*1024);
    Upload upload = transferManager.upload(putObjectRequest);
    // Wait until the "Initiate multiple upload" operation is completed, and get `persistableUpload` (including uploadId)
    while(persistableUpload == null) {
        persistableUpload = upload.getResumeableMultipartUploadId();
        Thread.sleep(100);
    }
    // Save persistableUpload
    
    // Step 2. If the multipart upload of a large file is interrupted due to network problems, use PersistableUpload to resume the upload only for the remaining parts
    Upload newUpload = transferManager.resumeUpload(persistableUpload);
     // Wait for the transfer to finish (call waitForCompletion if you want to wait for the upload to finish synchronously)
    UploadResult uploadResult = newUpload.waitForUploadResult();
    // The CRC64 value computed by the server for the object
    String crc64Ecma = uploadResult.getCrc64Ecma();

    Downloading an object

    Feature

    This API (GET Object) is used to download a COS object.

    Method prototype

    // Download an object
    public Download download(final GetObjectRequest GetObjectRequest, final File file);

    Parameter description

    Parameter Name Description Type
    getObjectRequest File download request GetObjectRequest
    file File to be downloaded locally File

    Request members:

    Request Member Setting Method                     Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Object Overview String
    key Constructor or set method The object key 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/picture.jpg, the object key is doc/picture.jpg, see ObjectKey String
    range Set Method Download Range Long[]
    trafficLimit Set Method Traffic limits (in bit/s) on the downloaded object. Default: none. int

    Response

    • Successful: Returns Download. You can query whether the download is completed, or wait until the download finishes synchronously.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // Enter the bucket name in the format of BucketName-APPID.  
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    File localDownFile = new File(localFilePath);
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    // Here, set the download bandwidth limit in bit/s to 10 MB/s
    getObjectRequest.setTrafficLimit(80*1024*1024);
    // Download a file
    Download download = transferManager.download(getObjectRequest, localDownFile);
    // Wait for the transfer to finish (call waitForCompletion if you want to wait for the upload to finish synchronously)
    download.waitForCompletion();

    Replicating objects

    Feature

    This API (Copy) supports automatic selection of simple copy or multipart copy based on the size of the object, and the user does not need to worry about the size of the copied file.

    Method prototype

    // Upload an object
    public Copy copy(final CopyObjectRequest copyObjectRequest);

    Parameter description

    Parameter Name Description Type
    copyObjectRequest File copy request CopyObjectRequest

    Request members:

    Member Name Description Type
    sourceBucketRegion Region of the source Bucket. Default: same with the region of the current clientconfig, which represents an intra-region copy String
    sourceBucketName Source bucket name in the format of BucketName-APPID String
    sourceKey Source object key. The object key is the unique identifier of the object in the bucket. For example, in the object's access domain examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see Object Overview String
    sourceVersionId Version ID of the source file (for source buckets with versioning enabled). Default: The latest version of the source file String
    destinationBucketName Destination bucket name in the format of BucketName-APPID String
    destinationKey Destination object key. The object key is the unique identifier of the object in the bucket. For example, in the object's access domain examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey. String
    storageClass Sets file storage class. Enumerated values: STANDARD and STANDARD_IA. Default: STANDARD String

    Response

    • Successful: Returns Copy. You can query whether the copy is completed, or wait until the copy finishes synchronously.
    • Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

    Request samples

    // The region of bucket to copy. Cross-region copy is supported.
    String secretId = "COS_SECRETID";
    String secretKey = "COS_SECRETKEY";
    COSCredentials srcCredentials = new BasicCOSCredentials(secretId, secretKey);
    Region srcBucketRegion = new Region("COS_REGION");
    // Enter the bucket name in the format of BucketName-APPID
    String srcBucketName = "sourcebucket-1250000000";
    // The source file to be copied
    String srcKey = "sourceObject";
    // Enter the destination bucket name in the format of BucketName-APPID
    String destBucketName = "examplebucket-1250000000";
    // The destination file to be copied into
    String destKey = "exampleobject";
    // Generate srcCOSClient to get source file information
    COSClient srcCOSClient = new COSClient(srcCredentials, new ClientConfig(srcBucketRegion));
    CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
            srcKey, destBucketName, destKey);
    try {
        Copy copy = transferManager.copy(copyObjectRequest, srcCOSClient, null);
        // Return an asynchronous result copy. You can synchronously call waitForCopyResult to wait for copy to end. If successful, CopyResult is returned; If failed, an exception will be thrown.
        CopyResult copyResult = copy.waitForCopyResult();
        // Get CRC64 value of the replicated object
        String crc64Ecma = copyResult.getCrc64Ecma();
    } catch (CosServiceException e) {
        e.printStackTrace();
    } catch (CosClientException e) {
        e.printStackTrace();
    } catch (InterruptedException e) {
        e.printStackTrace();
    }

    Client Encryption

    Feature

    Java SDK supports client encryption, encrypting files before uploading and decrypting them when downloading. Client encryption supports symmetric AES and asymmetric RSA encryption.
    The symmetry and asymmetry here are only used to encrypt the generated random keys. AES256 is always used to encrypt file data symmetrically.
    Client encryption is suitable for users who store sensitive data. client encryption may sacrifice certain upload speed, and the SDK may use serial method for multipart upload.

    Preparing for client encryption

    Client encryption uses AES256 internally to encrypt data. By default, earlier versions of JDK6-JDK8 do not support 256-bit encryption. If run, an exception will be reported: java.security.InvalidKeyException: Illegal key size or default parameters. We then need to supplement Oracle's JCE unrestricted permissions file and deploy it in JRE environment. Please download the corresponding files according to the JDK version used, unzip and save them in the jre/lib/security directory under JAVA_HOME.

    1. JDK6 JCE supplement package
    2. JDK7 JCE supplement package
    3. JDK8 JCE supplement package

    Uploading encryption process

    1. Before uploading a file object, we randomly generate a symmetric encryption key. The random key is encrypted by the symmetric or asymmetric key provided by the user, and the encrypted result is encoded with base64 and stored in the metadata of the object.
    2. When the file object is uploaded, AES256 algorithm is used to encrypt the file object in memory.

    Decryption for download

    1. Obtain the necessary encryption information from the metadata of the file, and decrypt the information decoded with Base64 using the user key to obtain the key of the encrypted data.
    2. Use the key to decrypt the downloaded input stream using AES256 to obtain the decrypted file input stream.

    Request samples

    Sample 1: Use symmetric AES256 encryption to generate a random key each time. For the complete sample code, see [Complete Example of Client Symmetric Key Encryption](https://github.com/tencentyun/cos-java-sdk-v5 /blob/master/src/main/java/com/qcloud/cos/demo/SymmetricKeyEncryptionClientDemo.java).

    // Initialize user authentication information (secretId, secretKey).
    String secretId = "COS_SECRETID";
    String secretKey = "COS_SECRETKEY";
    COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
    // Set COS region. For regions and their abbreviations, see https://www..com/document/product/436/6224
    ClientConfig clientConfig = new ClientConfig(new Region("COS_REGION"));
    
    // Generating a symmetric key and you can save it in a file
    KeyGenerator symKeyGenerator = KeyGenerator.getInstance("AES");
    symKeyGenerator.init(256);
    SecretKey symKey = symKeyGenerator.generateKey();
    
    EncryptionMaterials encryptionMaterials = new EncryptionMaterials(symKey);
    // Use the AES/GCM mode and store the encrypted information in file metadata
    CryptoConfiguration cryptoConf = new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)
            .withStorageMode(CryptoStorageMode.ObjectMetadata);
    
    // Generating encryption client (EncryptionClient). The COSEncryptionClient is a subclass of COSClient, and all APIs supported by COSClient are also available.
    // EncryptionClient overwrites the COSClient upload and download logic. It will perform the encryption operation internally. The other operations execution logic is consistent with that of the COSClient.
    COSEncryptionClient cosEncryptionClient =
            new COSEncryptionClient(new COSStaticCredentialsProvider(cred),
                    new StaticEncryptionMaterialsProvider(encryptionMaterials), clientConfig,
                    cryptoConf);
    
    // Uploading the file
    // Here is an example of putObject. For advanced API upload, use the COSEncryptionClient object when generating TransferManager.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    File localFile = new File(localFilePath);
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    cosEncryptionClient.putObject(putObjectRequest);
    cosEncryptionClient.shutdown();

    Sample 2: Use asymmetric RSA encryption to generate a random key each time. For the complete sample code, see [Complete Example of Client Symmetric Key Encryption](https://github.com/tencentyun/cos-java-sdk-v5 /blob/master/src/main/java/com/qcloud/cos/demo/SymmetricKeyEncryptionClientDemo.java).

    // Initialize user authentication information (secretId, secretKey).
    String secretId = "COS_SECRETID";
    String secretKey = "COS_SECRETKEY";
    COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
    // COS region. For regions and their abbreviations, see https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1
    ClientConfig clientConfig = new ClientConfig(new Region("COS_REGION"));
    
    // Generating asymmetric keys
    KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance("RSA");
    SecureRandom srand = new SecureRandom();
    keyGenerator.initialize(1024, srand);
    KeyPair asymKeyPair = keyGenerator.generateKeyPair();
    
    EncryptionMaterials encryptionMaterials = new EncryptionMaterials(asymKeyPair);
    // Use the AES/GCM mode and store the encrypted information in file metadata
    CryptoConfiguration cryptoConf = new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)
            .withStorageMode(CryptoStorageMode.ObjectMetadata);
    
    // Generating encryption client (EncryptionClient). The COSEncryptionClient is a subclass of COSClient, and all APIs supported by COSClient are also available.
    // EncryptionClient overwrites the COSClient upload and download logic. It will perform the encryption operation internally. The other operations execution logic is consistent with that of the COSClient.
    COSEncryptionClient cosEncryptionClient =
            new COSEncryptionClient(new COSStaticCredentialsProvider(cred),
                    new StaticEncryptionMaterialsProvider(encryptionMaterials), clientConfig,
                    cryptoConf);
    
    // Uploading the file
    // Here is an example of putObject. For advanced API upload, use the COSEncryptionClient object when generating TransferManager.
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    File localFile = new File(localFilePath);
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    cosEncryptionClient.putObject(putObjectRequest);
    cosEncryptionClient.shutdown();

    Was this page helpful?

    Was this page helpful?

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