Manage object tags using the Android SDK - Object Storage Service

Object Storage Service (OSS) lets you attach key-value tags to objects to classify and manage them. This topic shows how to add, query, and delete object tags using the OSS Android SDK.

Prerequisites

Before you begin, ensure that you have:

An initialized OSSClient instance. For more information, see Initialization.

Add tags to an object

Add tags when uploading an object

Tags are attached via the x-oss-tagging header on a PutObjectRequest. The OSSUtils.paramToQueryString() helper encodes the tag map into the required query-string format.

Note

If an object with the same name already exists at the specified path, the upload overwrites it. To prevent this, see Prevent objects from being overwritten by objects with the same names.

// Create an upload request.
// Specify the bucket name, the full path of the object, and the full path of the local file.
// The full path of the object cannot contain the bucket name.
PutObjectRequest put = new PutObjectRequest("examplebucket", "exampledir/exampleobject.txt",
        "/storage/emulated/0/oss/examplefile.txt");

Map<String, String> tags = new HashMap<>();
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);

// Track upload progress.
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 clientException,
                          ServiceException serviceException) {
        if (clientException != null) {
            // Client-side error, such as a network error.
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Server-side error.
            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 tags of an existing object

Use PutObjectTaggingRequest to set or replace the tag set on an existing object.

String bucketName = "examplebucket";
String objectName = "exampledir/exampleobject.txt";

Map<String, String> tags = new HashMap<>();
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) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

Add tags when copying an object

Set x-oss-tagging and x-oss-tagging-directive: REPLACE on the CopyObjectRequest to apply new tags to the destination object, ignoring any tags from the source.

// Specify the source bucket name, source object path, destination bucket name, and destination object path.
// The full path of an object cannot contain the bucket name.
CopyObjectRequest copyObjectRequest = new CopyObjectRequest("examplebucket", "exampledir/exampleobject.txt",
        "destexamplebucket", "destexampledir/exampleobject.txt");

Map<String, String> tags = new HashMap<>();
tags.put("key1", "value1");
tags.put("key2", "value2");
String tagHeader = OSSUtils.paramToQueryString(tags, "UTF-8");

ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setHeader("x-oss-tagging", tagHeader);
// Ignore the source object's tags and use the tags specified in this request.
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 clientException,
                          ServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            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

Attach tags to a symbolic link by setting x-oss-tagging on a PutSymlinkRequest.

PutSymlinkRequest putSymlink = new PutSymlinkRequest();
putSymlink.setBucketName("examplebucket");
putSymlink.setObjectKey("yourSymLink");
putSymlink.setTargetObjectName("yourTargetObjectName");

Map<String, String> tags = new HashMap<>();
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

GetObjectTaggingRequest returns a map of tag key-value pairs. Iterate over result.getTags().entrySet() to read them.

String bucketName = "examplebucket";
String objectName = "exampledir/exampleobject.txt";

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> entry : result.getTags().entrySet()) {
            Log.d("tag", "key: " + entry.getKey() + ", value: " + entry.getValue());
        }
    }

    @Override
    public void onFailure(GetObjectTaggingRequest request, ClientException clientException,
                          ServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            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

DeleteObjectTaggingRequest removes all tags from an object.

String bucketName = "examplebucket";
String objectName = "exampledir/exampleobject.txt";

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) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

What's next

For the complete sample code, see ObjectTaggingTest.java on GitHub.
For the underlying API operations, see PutObjectTagging, GetObjectTagging, and DeleteObjectTagging.