Object Storage Service (OSS) allows you to configure object tags to classify objects. You can configure lifecycle rules and control access to objects based on tags.

Background information

When you configure object tagging, take note of the following items:

  • You can add tags to an object when and after you upload the object. If the object already has tags, the existing tags are overwritten. For more information about how to configure object tags, see PutObjectTagging.
  • To add tags to an object, you must have the permissions to add tags.
  • The Last-Modified value of an object is not updated when its tags are changed.
  • You can add up to 10 tags to an object. The tags added to an object must have unique keys.
  • A tag key can be a maximum of 128 characters in length. A tag value can be a maximum of 256 characters in length.
  • Tag keys and tag values are case-sensitive.
  • The key and value of a tag can contain letters, digits, spaces, and the following special characters:

    + - = ._:/

    Note If you configure the tags in the HTTP header and the tags contain characters, you can encode the keys and values of the tags by using URL encoding.

Object tagging uses a key-value pair to identify objects. For more information about object tags, see Configure object tagging.

Add tags to an object when you upload the object

The following examples describe how to add tags to an object when you upload the object by using simple upload, multipart upload, and append upload.

  • Add tags to an object when you upload the object by using simple upload

    The following code provides an example on how to add tags to an object when you upload the object by using simple upload:

    <?php
    if (is_file(__DIR__ . '/../autoload.php')) {
        require_once __DIR__ . '/../autoload.php';
    }
    if (is_file(__DIR__ . '/../vendor/autoload.php')) {
        require_once __DIR__ . '/../vendor/autoload.php';
    }
    
    use OSS\OssClient;
    use OSS\Core\OssException;
    
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access Object Storage Service (OSS) because the account has permissions on all API operations. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    $accessKeyId = "yourAccessKeyId";
    $accessKeySecret = "yourAccessKeySecret";
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    $endpoint = "yourEndpoint";
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket = "examplebucket";
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    $object = "exampledir/exampleobject.txt";
    // Specify the string to upload. 
    $content = "hello world";
    
    $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);
    
    // Add tags to the object. 
    $options = array(
          OssClient::OSS_HEADERS => array(
                  'x-oss-tagging' => 'key1=value1&key2=value2&key3=value3',
    ));
      
    try {
          // Upload the object by using simple upload. 
          $ossClient->putObject($bucket, $object, $content, $options);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    
    print(__FUNCTION__ . ": OK" . "\n");  
  • Add tags to an object when you upload the object by using multipart upload

    The following code provides an example on how to add tags to an object when you upload the object by using multipart upload:

    <?php
    if (is_file(__DIR__ . '/../autoload.php')) {
        require_once __DIR__ . '/../autoload.php';
    }
    if (is_file(__DIR__ . '/../vendor/autoload.php')) {
        require_once __DIR__ . '/../vendor/autoload.php';
    }
    
    use OSS\OssClient;
    use OSS\Core\OssException;
    
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    $accessKeyId = "yourAccessKeyId";
    $accessKeySecret = "yourAccessKeySecret";
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    $endpoint = "yourEndpoint";
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket = "examplebucket";
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    $object = "exampledir/exampleobject.txt";
    // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. By default, if you do not specify the local path of the file and specify only the name of the file such as examplefile.txt, the local file is uploaded from the path of the project to which the sample program belongs. 
    $file = "D:\\localpath\\examplefile.txt";
    
    $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);
    
    // Add tags to the object. 
    $options = array(
        OssClient::OSS_CHECK_MD5 => true,
        OssClient::OSS_PART_SIZE => 1,
        OssClient::OSS_HEADERS => array(
              'x-oss-tagging' => 'key1=value1&key2=value2&key3=value3',
        ),
    );
    
    try {
        // Upload the object by using multipart upload. 
        $ossClient->multiuploadFile($bucket, $object, $file, $options);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    
    print(__FUNCTION__ . ": OK" . "\n");
  • Add tags to an object when you upload the object by using append upload

    The following code provides an example on how to add tags to an object when you upload the object by using append upload:

    <?php
    if (is_file(__DIR__ . '/../autoload.php')) {
        require_once __DIR__ . '/../autoload.php';
    }
    if (is_file(__DIR__ . '/../vendor/autoload.php')) {
        require_once __DIR__ . '/../vendor/autoload.php';
    }
    
    use OSS\OssClient;
    use OSS\Core\OssException;
    
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    $accessKeyId = "yourAccessKeyId";
    $accessKeySecret = "yourAccessKeySecret";
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    $endpoint = "yourEndpoint";
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket = "examplebucket";
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    $object = "exampledir/exampleobject.txt";
    // Specify the strings to upload in sequence. 
    $content_array = array('Hello OSS', 'Hi OSS');
    
    $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);
    
    // Add tags to the object. 
    $options = array(
          OssClient::OSS_HEADERS => array(
                  'x-oss-tagging' => 'key1=value1&key2=value2',
    ));
      
    try {
        // Upload the object by using append upload. 
        $position = $ossClient->appendObject($bucket, $object, $content_array[0], 0, $options);
        $position = $ossClient->appendObject($bucket, $object, $content_array[1], $position);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    
    print(__FUNCTION__ . ": OK" . "\n");

Add tags to an uploaded object or modify the tags of the object

If an existing object has no tags or the added tags of the object do not meet your requirements, you can add or modify the tags of the existing object.

The following code provides an example on how to add tags to or modify the tags of an existing object:

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;
use OSS\Model\TaggingConfig;
use OSS\Model\Tag;

// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
$accessKeyId = "yourAccessKeyId";
$accessKeySecret = "yourAccessKeySecret";
// Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
$endpoint = "yourEndpoint";
// Specify the name of the bucket. Example: examplebucket. 
$bucket = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
$object = "exampledir/exampleobject.txt";

$ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);

// Add tags to the object. 
$config = new TaggingConfig();
$config->addTag(new Tag("key1", "value1"));
$config->addTag(new Tag("key2", "value2"));

try {
    $ossClient->putObjectTagging($bucket, $object, $config);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");

Add tags to or modify the existing tags of a specified version of an object

If versioning is enabled for the bucket that contains the object, you can specify the version ID of the object to add tags to or modify the existing tags of the specified version of the object.

The following code provides an example on how to add tags to or modify the existing tags of a specified version of an object:

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;
use OSS\Model\TaggingConfig;
use OSS\Model\Tag;

// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
$accessKeyId = "yourAccessKeyId";
$accessKeySecret = "yourAccessKeySecret";
// Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
$endpoint = "yourEndpoint";
// Specify the name of the bucket. Example: examplebucket. 
$bucket = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
$object = "exampledir/exampleobject.txt";
// Specify the version ID of the object. 
$options = array(
    'versionId'=>'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'
);

$ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);

// Add tags to the object. 
$config = new TaggingConfig();
$config->addTag(new Tag("key1", "value1"));
$config->addTag(new Tag("key2", "value2"));

try {
    $ossClient->putObjectTagging($bucket, $object, $config,$options);
    printf("putObjectTagging Success" . "\n");
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}