Object Storage Service (OSS) allows you to configure object tags to classify objects. This topic describes how to add tags to an object, query the tags of an object, and delete the tags of an object.
Usage notes
Before you run the sample code in this topic, you must create an OSSClient instance by using methods such as using a custom domain name or Security Token Service (STS). For more information, see Initialization.
Configure object tagging
Add tags to an object when you upload the object
Note
If an object that has the same name as the object that you want to upload already exists in the specified path, the existing object is overwritten by the uploaded object. If you do not want to overwrite the existing object, you can configure parameters. For more information, see Prevent objects from being overwritten by objects with the same names.
The following sample code provides an example on how to add tags to an object when you upload the object:
// Create an object upload request.
// Specify the name of the bucket, the full path of the object, and the full path of the local file. In this example, the name of the bucket is examplebucket, the full path of the object is exampledir/exampleobject.txt, and the full path of the local file is /storage/emulated/0/oss/examplefile.txt.
// Do not include the bucket name in the full path of the object.
PutObjectRequest put = new PutObjectRequest("examplebucket", "exampledir/exampleobject.txt", "/storage/emulated/0/oss/examplefile.txt");
Map<String, String> tags = new HashMap<String, String>();
// Configure the tags that you want to add to the object.
tags.put("key1", "value1");
tags.put("Key2", "value2");
String tagHeader = OSSUtils.paramToQueryString(tags, "UTF-8");
ObjectMetadata metadata = new ObjectMetadata();
metadata.setHeader("x-oss-tagging", tagHeader);
put.setMetadata(metadata);
// If you upload the local file in asynchronous mode, you can configure the progress callback.
put.setProgressCallback(new OSSProgressCallback<PutObjectRequest>() {
@Override
public void onProgress(PutObjectRequest request, long currentSize, long totalSize) {
Log.d("PutObject", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
OSSAsyncTask task = oss.asyncPutObject(put, new OSSCompletedCallback<PutObjectRequest, PutObjectResult>() {
@Override
public void onSuccess(PutObjectRequest request, PutObjectResult result) {
Log.d("PutObject", "UploadSuccess");
Log.d("ETag", result.getETag());
Log.d("RequestId", result.getRequestId());
}
@Override
public void onFailure(PutObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
// Handle request exceptions.
if (clientExcepion != null) {
// Handle client-side exceptions, such as network exceptions.
clientExcepion.printStackTrace();
}
if (serviceException != null) {
// Handle server-side exceptions.
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});Add tags to or modify the tags of an existing object
The following sample code provides an example on how to add tags to or modify the tags of an existing object:
// Specify the name of the bucket. Example: examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path of the object.
String objectName = "exampledir/exampleobject.txt";
Map<String, String> tags = new HashMap<String, String>();
// Configure the tags that you want to add to the object.
tags.put("owner", "John");
tags.put("type", "document");
PutObjectTaggingRequest putObjectTaggingRequest = new PutObjectTaggingRequest(bucketName, objectName, tags);
oss.asyncPutObjectTagging(putObjectTaggingRequest, new OSSCompletedCallback<PutObjectTaggingRequest, PutObjectTaggingResult>() {
@Override
public void onSuccess(PutObjectTaggingRequest request, PutObjectTaggingResult result) {
Log.d("PutTagging", "PutTaggingSuccess");
}
@Override
public void onFailure(PutObjectTaggingRequest request, ClientException clientException, ServiceException serviceException) {
// Handle request exceptions.
if (clientException != null) {
// Handle client-side exceptions, such as network exceptions.
clientException.printStackTrace();
}
if (serviceException != null) {
// Handle server-side exceptions.
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});Add tags to an object when you copy the object
The following sample code provides an example on how to add tags to an object when you copy the object:
// Create a CopyObject request.
// Specify the name of the source bucket, the full path of the source object, the name of the destination bucket, and the full path of the destination object. In this example, the name of the source bucket is examplebucket, the full path of the source object is exampledir/exampleobject.txt, the name of the destination bucket is destexamplebucket, and the full path of the destination object is destexampledir/exampleobject.txt.
// Do not include the bucket name in the full path of the object.
CopyObjectRequest copyObjectRequest = new CopyObjectRequest("examplebucket", "exampledir/exampleobject.txt",
"destexamplebucket", "destexampledir/exampleobject.txt");
ObjectMetadata objectMetadata = new ObjectMetadata();
Map<String, String> tags = new HashMap<String, String>();
// Configure tags for the destination object.
tags.put("key1", "value1");
tags.put("key2", "value2");
String tagHeader = OSSUtils.paramToQueryString(tags, "UTF-8");
objectMetadata.setHeader("x-oss-tagging", tagHeader);
// Add the tags specified in the request to the destination object and ignore the tags of the source object.
objectMetadata.setHeader("x-oss-tagging-directive", "REPLACE");
copyObjectRequest.setNewObjectMetadata(objectMetadata);
OSSAsyncTask copyTask = oss.asyncCopyObject(copyObjectRequest, new OSSCompletedCallback<CopyObjectRequest, CopyObjectResult>() {
@Override
public void onSuccess(CopyObjectRequest request, CopyObjectResult result) {
Log.d("copyObject", "copy success!");
}
@Override
public void onFailure(CopyObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
// Handle request exceptions.
if (clientExcepion != null) {
// Handle client-side exceptions, such as network exceptions.
clientExcepion.printStackTrace();
}
if (serviceException != null) {
// Handle service exceptions.
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});Add tags to a symbolic link
The following sample code provides an example on how to add tags to a symbolic link:
PutSymlinkRequest putSymlink = new PutSymlinkRequest();
// Specify the name of the bucket. Example: examplebucket.
putSymlink.setBucketName("examplebucket");
// Specify the name of the symbolic link.
putSymlink.setObjectKey("yourSymLink");
// Specify the name of the object.
putSymlink.setTargetObjectName("yourTargetObjectName");
Map<String, String> tags = new HashMap<String, String>();
// Configure the tags that you want to add to the object.
tags.put("key1", "value1");
tags.put("key2", "value2");
String tagHeader = OSSUtils.paramToQueryString(tags, "UTF-8");
ObjectMetadata metadata = new ObjectMetadata();
metadata.setHeader("x-oss-tagging", tagHeader);
putSymlink.setMetadata(metadata);
OSSAsyncTask task = oss.asyncPutSymlink(putSymlink, new OSSCompletedCallback<PutSymlinkRequest,
PutSymlinkResult>() {
@Override
public void onSuccess(PutSymlinkRequest request, PutSymlinkResult result) {
OSSLog.logInfo("code:"+result.getStatusCode());
}
@Override
public void onFailure(PutSymlinkRequest request, ClientException clientException,
ServiceException serviceException) {
OSSLog.logError("error: "+serviceException.getRawMessage());
}
});Query the tags of an object
The following sample code provides an example on how to query the tags of an object:
// Specify the name of the bucket. Example: examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path of the object.
String objectName = "exampledir/exampleobject.txt";
// Query the tags of the object.
GetObjectTaggingRequest getObjectTaggingRequest = new GetObjectTaggingRequest(bucketName, objectName);
oss.asyncGetObjectTagging(getObjectTaggingRequest, new OSSCompletedCallback<GetObjectTaggingRequest, GetObjectTaggingResult>() {
@Override
public void onSuccess(GetObjectTaggingRequest request, GetObjectTaggingResult result) {
for (Map.Entry<String, String> s : result.getTags().entrySet()) {
Log.d("tag", "key: " + s.getKey() + ", value: " + s.getValue());
}
}
@Override
public void onFailure(GetObjectTaggingRequest request, ClientException clientException, ServiceException serviceException) {
// Handle request exceptions.
if (clientException != null) {
// Handle client-side exceptions, such as network exceptions.
clientException.printStackTrace();
}
if (serviceException != null) {
// Handle server-side exceptions.
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});Delete the tags of an object
The following sample code provides an example on how to delete the tags of an object:
// Specify the name of the bucket. Example: examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path of the object.
String objectName = "exampledir/exampleobject.txt";
// Delete the tags of the object.
DeleteObjectTaggingRequest deleteObjectTaggingRequest = new DeleteObjectTaggingRequest(bucketName, objectName);
oss.asyncDeleteObjectTagging(deleteObjectTaggingRequest, new OSSCompletedCallback<DeleteObjectTaggingRequest, DeleteObjectTaggingResult>() {
@Override
public void onSuccess(DeleteObjectTaggingRequest request, DeleteObjectTaggingResult result) {
Log.d("deleteTagging", "deleteTagging success");
}
@Override
public void onFailure(DeleteObjectTaggingRequest request, ClientException clientException, ServiceException serviceException) {
// Handle request exceptions.
if (clientException != null) {
// Handle client-side exceptions, such as network exceptions.
clientException.printStackTrace();
}
if (serviceException != null) {
// Handle server-side exceptions.
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});References
For the complete sample code of object tagging, visit GitHub.
For more information about the API operation that you can call to configure tags for an object, see PutObjectTagging.
For more information about the API operation that you can call to query the tags of an object, see GetObjectTagging.
For more information about the API operation that you can call to delete the tags of an object, see DeleteObjectTagging.
For more information about how to prevent existing objects from being overwritten, see Prevent objects from being overwritten by objects with the same names.
For more information about how to initialize an OSSClient instance, see Initialization.