Modifying object metadata

Last updated: 2023-09-13 14:35:24

Feature Overview

This document provides SDK code samples related to object metadata modification.
Object metadata modification uses the object replication API and sets new metadata during object replication.
API
Operation
Description
Copying an object
Copies a file to a destination path

Simple Operations

Requests for simple operations need to be initiated through COSClient instances. You need to create a COSClient instance before performing simple operations.
COSClient instances are concurrency-safe. You are advised to create only one COSClient instance for a process and then close it when it is no longer used to initiate requests.

Creating a COSClient instance

Before calling the COS API, first create a COSClient instance.
// Create a COSClient instance, which is used to initiate requests later.
COSClient createCOSClient() {
// Set user identity information.
// To view and manage SECRETID and SECRETKEY, please log in to the Access Management Console at https://console.cloud.tencent.com/cam/capi
String secretId = System.getenv("secretId"); // User's SecretId, it is recommended to use a sub-account key, following the principle of least privilege to reduce usage risks. For obtaining a sub-account key, please refer to https://cloud.tencent.com/document/product/598/37140
String secretKey = System.getenv("secretKey"); // User's SecretKey, it is recommended to use a sub-account key, following the principle of least privilege to reduce usage risks. For obtaining a sub-account key, please refer to https://cloud.tencent.com/document/product/598/37140
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);

// ClientConfig contains the client settings for subsequent requests to COS:
ClientConfig clientConfig = new ClientConfig();

// Set the bucket region
// For more information on COS regions, visit https://cloud.tencent.com/document/product/436/6224.
clientConfig.setRegion(new Region("COS_REGION"));

// Set the request protocol, either HTTP or HTTPS
// For versions 5.6.53 and below, it is recommended to use the HTTPS protocol.
// Version 5.6.54 and higher, HTTPS is used by default.
clientConfig.setHttpProtocol(HttpProtocol.https);

// The following settings are optional:

// Set socket read timeout, default is 30 seconds
clientConfig.setSocketTimeout(30*1000);
// Set connection establishment timeout, default is 30 seconds
clientConfig.setConnectionTimeout(30*1000);

// Set the HTTP proxy, IP, and port if needed.
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);

// Create a COS client.
return new COSClient(cred, clientConfig);
}

Creating a COSClient instance with a temporary key

To request COS using temporary keys, create a COSClient with the temporary keys. This SDK cannot generate temporary keys; additional operations are required for generating them. For more information, please refer to Temporary Key Generation.

// Create a COSClient instance, which is used to initiate requests later.
COSClient createCOSClient() {
// Here, the temporary key must have already been obtained.
// For generating temporary keys, refer to https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk
String tmpSecretId = "TMPSECRETID";
String tmpSecretKey = "TMPSECRETKEY";
String sessionToken = "SESSIONTOKEN";

COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);

// ClientConfig contains the client settings for subsequent requests to COS:
ClientConfig clientConfig = new ClientConfig();

// Set the bucket region
// For COS_REGION, please refer to https://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region("COS_REGION"));

// Set the request protocol, either HTTP or HTTPS
// For versions 5.6.53 and below, it is recommended to use the HTTPS protocol.
// Version 5.6.54 and higher, HTTPS is used by default.
clientConfig.setHttpProtocol(HttpProtocol.https);

// The following settings are optional:

// Set socket read timeout, default is 30 seconds
clientConfig.setSocketTimeout(30*1000);
// Set connection establishment timeout, default is 30 seconds
clientConfig.setConnectionTimeout(30*1000);

// Set the HTTP proxy, IP, and port if needed.
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);

// Create a COS client.
return new COSClient(cred, clientConfig);
}

Modifying object metadata

This API uses the object replication API and sets new metadata during object replication. In the object replication API, only metadata is modified, and object data is not copied.

Method prototype

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws CosClientException, CosServiceException

Sample Request

// Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.
// For the detailed code, see "Simple Upload -> Creating a COSClient instance" on the current page.
COSClient cosClient = createCOSClient();

// Region where the bucket resides
// For more information on COS regions, visit https://cloud.tencent.com/document/product/436/6224.
Region region = new Region("ap-beijing");
// Enter the bucket name in the format of BucketName-APPID.
String bucketName = "examplebucket-1250000000";
// The Object Key is the unique identifier for an object within a bucket. For more information, please refer to [Object Key](https://cloud.tencent.com/document/product/436/13324).
String key = "exampleobject";

// Get the current object metadata.
ObjectMetadata objectMetadata = cosClient.getObjectMetadata(bucketName, key);
// Replaced must be set if you modify object metadata.
objectMetadata.setHeader("x-cos-metadata-directive", "Replaced");

// Set the new object metadata.
// Note: For Content-Disposition, custom metadata, or other header fields with Chinese characters, call UrlEncoderUtils.encode(String) for encoding before setting to avoid signature issues.
objectMetadata.setHeader("x-cos-storage-class", "STANDARD_IA");
objectMetadata.setContentType("text/plain");

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(region, bucketName, key, bucketName, key);
copyObjectRequest.setNewObjectMetadata(objectMetadata);

try {
CopyObjectResult copyObjectResult = cosClient.copyObject(copyObjectRequest);
System.out.print(copyObjectResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}

// After confirming that the current process no longer uses the cosClient instance, close it.
cosClient.shutdown();

Description

Parameter name
Description
Local Disk Types
copyObjectRequest
File copy request
CopyObjectRequest
Description of the Request member:
Parameter name
Description
Local Disk Types
sourceBucketRegion
Region of the source bucket. Default: same as the region value in the current clientConfig, which represents intra-region replication
String
sourceBucketName
Source bucket name in the format: BucketName-APPID. For details, see Naming Conventions
String
sourceKey
Source object key. The object key is the unique identifier of the object in the bucket. For example, in the object endpoint 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. It should contain letters, numbers, and hyphens.
String
destinationKey
Destination object key. The object key is the unique identifier of the object in the bucket. For example, in the object endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey
String
storageClass
The storage type of the destination file for the copy operation. Enumerated values: Standard, Standard_IA. Default value: Standard. For more information on storage types, see Storage Class Overview.
String

Response description

Success: returns CopyObjectResult, including the Etag and other information on the new file.
Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.