Updated on 2026-08-03 GMT+08:00

Adding Tags to an Object (SDK for C)

If you have any questions during development, post them on the Issues page of GitHub.

Function

This API sets or updates tags for an object. Each tag is a key-value pair.

Restrictions

  • To add tags to an object, you must be the object owner or have the required permission (obs:object:PutObjectTagging granted using IAM or PutObjectTagging granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
  • The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
  • A bucket can have a maximum of 10 tags.
  • Tags cannot be set for files in parallel file systems.
  • A tag key and its value can contain a maximum of 128 and 255 characters, respectively.
  • Tag keys and values cannot contain commas (,), asterisks (*), vertical bars (|), slashes (/), less-than signs (<), greater-than signs (>), equal signs (=), backslashes (\), or ASCII codes (0x00 to 0x1F).

Method

void set_object_tagging(const obs_options *options, const char *key, 
                         obs_name_value *tagging_list, unsigned int number,
                         obs_response_handler *handler, void *callback_data);

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

options

const obs_options*

Yes

Explanation:

Context of the requested bucket. You can set the AK, SK, endpoint, bucket, timeout interval, and temporary credentials through obs_options.

Restrictions:

None

Value range:

None

Default value:

None

key

char *

Yes

Explanation:

Object name. An object name is a complete path of the object that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Restrictions:

The name of each object in a bucket must be unique.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

tagging_list

obs_name_value*

Yes

Explanation:

Tag list.

Restrictions:

None

Value range:

None

Default value:

None

number

unsigned int

Yes

Explanation:

Number of tags.

Restrictions:

None

Value range:

[0, 10]

Default value:

None

handler

obs_response_handler *

Yes

Explanation:

A callback structure where all members are pointers to callback functions, used to set the callback functions that handle response data. You can set a callback function to copy the response data from the server to callback_data (custom callback data).

Restrictions:

None

Value range:

None

Default value:

None

callback_data

void *

No

Explanation:

Custom callback data.

Restrictions:

None

Value range:

None

Default value:

None

Table 2 obs_name_value

Parameter

Type

Mandatory (Yes/No)

Description

name

char *

Yes if used as a request parameter

Explanation:

Tag key.

Restrictions:

  • The tag key in the same bucket must be unique.
  • You can define tags or select the ones predefined on TMS.
  • A tag key must contain 1 to 128 characters.
  • Tag keys cannot start or end with a space and cannot contain commas (,), asterisks (*), vertical bars (|), slashes (/), less-than signs (<), greater-than signs (>), equal signs (=), backslashes (\), or ASCII control characters (0x00 to 0x1F). Tag keys and values must be URL encoded before being sent to a server.
  • A tag key is case-sensitive.

Default value:

None

Value range:

None

Default value:

None

value

char *

Yes if used as a request parameter

Explanation:

Tag value.

Restrictions:

Tag values can be duplicated or left blank.

  • A tag value must contain 0 to 255 characters.
  • Tag values cannot start or end with a space and cannot contain commas (,), asterisks (*), vertical bars (|), slashes (/), less-than signs (<), greater-than signs (>), equal signs (=), backslashes (\), or ASCII control characters (0x00 to 0x1F). Tag keys and values must be URL encoded before being sent to a server.
  • A tag value is case-sensitive.

Default value:

None

Value range:

None

Default value:

None

Sample Code

This example adds tags to an object.
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
#include "eSDKOBS.h"
#include <stdio.h>
// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
// The callback function for the completed response. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
#define TAG_LIST_LENGTH 10
int main()
{
    // The following example shows how to use set_object_tagging to add tags to an object:
    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    // Create and initialize options, including the access domain name (host_name), access keys (access_key_id and access_key_secret), bucket name (bucket_name), and bucket storage class (storage_class).
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Specify the bucket name, for example, example-bucket-name.
    char * bucketName = "example-bucket-name";
    options.bucket_options.bucket_name = bucketName;
    obs_response_handler response_handler = { &response_properties_callback, &response_complete_callback };
    obs_status ret_status = OBS_STATUS_BUTT;
    // Define object tags.
    char tagKey[][OBS_COMMON_LEN_256] = { {"k1"},{"k2"},{"k3"},{"k4"},{"k5"},{"k6"},{"k7"},{"k8"},{"k9"},{"k10"} };
    char tagValue[][OBS_COMMON_LEN_256] = { {"v1"},{"v2"},{"v3"},{"v4"},{"v5"},{"v6"},{"v7"},{"v8"},{"v9"},{"v10"} };
    obs_name_value tagginglist[TAG_LIST_LENGTH] = { 0 };
    int i = 0;
    for (; i < TAG_LIST_LENGTH; i++)
    {
        tagginglist[i].name = tagKey[i];
        tagginglist[i].value = tagValue[i];
    }
    // Add tags to the object.
    set_object_tagging(&options, "objectname", tagginglist, TAG_LIST_LENGTH, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set object tagging successfully. \n");
    }
    else
    {
        printf("set object tagging failed(%s).\n", obs_get_status_name(ret_status));
    }
    // Release the allocated global resources.
    obs_deinitialize();
}
// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    if (properties == NULL)
    {
        printf("error! obs_response_properties is null!");
        return OBS_STATUS_OK;
    }
    // Print the response.
#define print_nonnull(name, field)                                 \
    do {                                                           \
        if (properties-> field) {                                  \
            printf("%s: %s\n", name, properties->field);          \
        }                                                          \
    } while (0)
    print_nonnull("request_id", request_id);
    print_nonnull("request_id2", request_id2);
    print_nonnull("content_type", content_type);
    if (properties->content_length) {
        printf("content_length: %llu\n", properties->content_length);
    }
    print_nonnull("server", server);
    print_nonnull("ETag", etag);
    print_nonnull("version_id", version_id);
    return OBS_STATUS_OK;
}
// The callback function for the completed response. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) {
        obs_status *ret_status = (obs_status *)callback_data;
        *ret_status = status;
    }
    else {
        printf("Callback_data is NULL");
    }
    if (error && error->message) {
        printf("Error Message: \n   %s\n", error->message);
    }
    if (error && error->resource) {
        printf("Error Resource: \n  %s\n", error->resource);
    }
    if (error && error->further_details) {
        printf("Error further_details: \n   %s\n", error->further_details);
    }
    if (error && error->extra_details_count) {
        int i;
        for (i = 0; i < error->extra_details_count; i++) {
            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
                error->extra_details[i].value);
        }
    }
    if (error && error->error_headers_count) {
        int i;
        for (i = 0; i < error->error_headers_count; i++) {
            const char *errorHeader = error->error_headers[i];
            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
        }
    }
}