tencent cloud

Feedback

Access Control

Last updated: 2022-01-23 14:27:55

    Overview

    This document provides an overview of APIs and SDK code samples related to the access control lists (ACLs) for buckets and objects.

    Bucket ACL

    API Operation Description
    PUT Bucket acl Setting a bucket ACL Sets an ACL for a bucket
    GET Bucket acl Querying a bucket ACL Gets the ACL of a specified bucket

    Object ACL

    API Operation Description
    PUT Object acl Setting an object ACL Sets an ACL for an object (file) in a bucket
    GET Object acl Querying an object ACL Queries the ACL of an object (file)

    Bucket ACL

    Setting a bucket ACL

    Description

    This API is used to set an access control list (ACL) for a specified bucket.

    Method prototype

    cos_status_t *cos_put_bucket_acl(const cos_request_options_t *options, 
                                   const cos_string_t *bucket, 
                                   cos_acl_e cos_acl,
                                   const cos_string_t *grant_read,
                                   const cos_string_t *grant_write,
                                   const cos_string_t *grant_full_ctrl,
                                   cos_table_t **resp_headers);
    

    Parameter description

    Parameter Description Type
    options COS request options Struct
    bucket Bucket name in the format of BucketName-APPID String
    cos_acl Allow users to customize permissions.
    Valid values: COS_ACL_PRIVATE(0) (default), COS_ACL_PUBLIC_READ(1), COS_ACL_PUBLIC_READ_WRITE(2)
    Enum
    grant_read Authorized user to which read permission is granted String
    grant_write Authorized user to which write permission is granted String
    grant_full_ctrl Authorized user to which full permission is granted String
    resp_headers Returns the HTTP response headers Struct

    Response description

    Response Parameter Description Type
    code Error code Int
    error_code Error code content String
    error_msg Error code description String
    req_id Request message ID String

    Sample

    #include "cos_http_io.h"
    #include "cos_api.h"
    #include "cos_log.h"
    // `endpoint` is the COS access domain name. For more information, see https://www.tencentcloud.com/document/product/436/6224.
    static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
    // A developer-owned secret ID/key used for the project. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char *TEST_ACCESS_KEY_ID;                // Your SecretId
    static char *TEST_ACCESS_KEY_SECRET;            // Your SecretKey
    // A unique user-level resource identifier for COS access. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char TEST_APPID[] = "<APPID>";    // Your APPID
    // COS bucket name, in the format of [bucket]-[appid], for example `mybucket-1253666666`. It can be obtained at https://console.tencentcloud.com/cos5/bucket.
    static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
    void log_status(cos_status_t *s)
    {
      cos_warn_log("status->code: %d", s->code);
      if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
      if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
      if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
    }
    void init_test_config(cos_config_t *config, int is_cname)
    {
      cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
      cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
      cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
      cos_str_set(&config->appid, TEST_APPID);
      config->is_cname = is_cname;
    }
    void init_test_request_options(cos_request_options_t *options, int is_cname)
    {
      options->config = cos_config_create(options->pool);
      init_test_config(options->config, is_cname);
      options->ctl = cos_http_controller_create(options->pool, 0);
    }
    void test_put_bucket_acl()
    {
      cos_pool_t *p = NULL;
      int is_cname = 0;
      cos_status_t *s = NULL;
      cos_request_options_t *options = NULL;
      cos_string_t bucket;
      cos_acl_e cos_acl = COS_ACL_PRIVATE; // Use your own configuration
      cos_table_t *resp_headers = NULL;
       // Create a memory pool
      cos_pool_create(&p, NULL);
       // Initialize the request options
      options = cos_request_options_create(p);
      init_test_request_options(options, is_cname);
      cos_str_set(&bucket, TEST_BUCKET_NAME);
       // Set a bucket ACL
      cos_string_t read;
      cos_str_set(&read, "id=\"qcs::cam::uin/100000000001:uin/100000000001\", id=\"qcs::cam::uin/100000000011:uin/100000000011\"");
      s = cos_put_bucket_acl(options, &bucket, cos_acl, &read, NULL, NULL, &resp_headers);
      if (cos_status_is_ok(s)) {
              printf("put bucket acl succeeded\n");
      } else {
              printf("put bucket acl failed\n");
      }
       // Destroy the memory pool
      cos_pool_destroy(p); 
    }
    int main(int argc, char *argv[])
    {
      // Get SecretId and SecretKey from environment variables
      TEST_ACCESS_KEY_ID     = getenv("COS_SECRETID");
      TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
        if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
         exit(1);
      }
       // Set the log level. Default value: `COS_LOG_WARN`
      cos_log_set_level(COS_LOG_WARN);
       // Set log output. Default value: `stderr`
      cos_log_set_output(NULL);
       test_put_bucket_acl();
       cos_http_io_deinitialize();
       return 0;
    }
    

    Querying a bucket ACL

    Description

    This API is used to query the access control list (ACL) of a specified bucket.

    Method prototype

    cos_status_t *cos_get_bucket_acl(const cos_request_options_t *options, 
                                   const cos_string_t *bucket, 
                                   cos_acl_params_t *acl_param, 
                                   cos_table_t **resp_headers)
    

    Parameter description

    Parameter Description Type
    options COS request options Struct
    bucket Bucket name in the format: BucketName-APPID String
    acl_param Parameters for the request Struct
    owner_id ID of the bucket owner String
    owner_id Name of the bucket owner String
    object_list Information on the authorized user and granted permission Struct
    type Authorized user account type String
    id ID of the authorized user String
    name Name of the authorized user String
    permission Permission granted to the authorized user String
    resp_headers Returns the HTTP response headers Struct

    Response description

    Response Parameter Description Type
    code Error code Int
    error_code Error code content String
    error_msg Error code description String
    req_id Request message ID String

    Sample

    #include "cos_http_io.h"
    #include "cos_api.h"
    #include "cos_log.h"
    // `endpoint` is the COS access domain name. For more information, see https://www.tencentcloud.com/document/product/436/6224.
    static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
    // A developer-owned secret ID/key used for the project. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char *TEST_ACCESS_KEY_ID;                // Your SecretId
    static char *TEST_ACCESS_KEY_SECRET;            // Your SecretKey
    // A unique user-level resource identifier for COS access. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char TEST_APPID[] = "<APPID>";    // Your APPID
    // COS bucket name, in the format of [bucket]-[appid], for example `mybucket-1253666666`. It can be obtained at https://console.tencentcloud.com/cos5/bucket.
    static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
    void log_status(cos_status_t *s)
    {
      cos_warn_log("status->code: %d", s->code);
      if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
      if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
      if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
    }
    void init_test_config(cos_config_t *config, int is_cname)
    {
      cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
      cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
      cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
      cos_str_set(&config->appid, TEST_APPID);
      config->is_cname = is_cname;
    }
    void init_test_request_options(cos_request_options_t *options, int is_cname)
    {
      options->config = cos_config_create(options->pool);
      init_test_config(options->config, is_cname);
      options->ctl = cos_http_controller_create(options->pool, 0);
    }
    void test_get_bucket_acl()
    {
      cos_pool_t *p = NULL;
      int is_cname = 0;
      cos_status_t *s = NULL;
      cos_request_options_t *options = NULL;
      cos_string_t bucket;
      cos_table_t *resp_headers = NULL;
       // Create a memory pool
      cos_pool_create(&p, NULL);
       // Initialize the request options
      options = cos_request_options_create(p);
      init_test_request_options(options, is_cname);
      cos_str_set(&bucket, TEST_BUCKET_NAME);
       // Get a bucket ACL
      cos_acl_params_t *acl_params = NULL;
      acl_params = cos_create_acl_params(p);
      s = cos_get_bucket_acl(options, &bucket, acl_params, &resp_headers);
      if (cos_status_is_ok(s)) {
          printf("get bucket acl succeeded\n");
          printf("acl owner id:%s, name:%s\n", acl_params->owner_id.data, acl_params->owner_name.data);
          cos_acl_grantee_content_t *acl_content = NULL;
          cos_list_for_each_entry(cos_acl_grantee_content_t, acl_content, &acl_params->grantee_list, node) {
              printf("acl grantee type:%s, id:%s, name:%s, permission:%s\n", acl_content->type.data, acl_content->id.data, acl_content->name.data, acl_content->permission.data);
          }
      } else {
          printf("get bucket acl failed\n");
      }
       // Destroy the memory pool
      cos_pool_destroy(p); 
    }
    int main(int argc, char *argv[])
    {
      // Get SecretId and SecretKey from environment variables
      TEST_ACCESS_KEY_ID     = getenv("COS_SECRETID");
      TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
        if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
         exit(1);
      }
       // Set the log level. Default value: `COS_LOG_WARN`
      cos_log_set_level(COS_LOG_WARN);
       // Set log output. Default value: `stderr`
      cos_log_set_output(NULL);
       test_get_bucket_acl();
       cos_http_io_deinitialize();
       return 0;
    }
    

    Object ACL

    Setting an object ACL

    Description

    This API is used to set the ACL of an object.

    Method prototype

    cos_status_t *cos_put_object_acl(const cos_request_options_t *options, 
                                   const cos_string_t *bucket,
                                   const cos_string_t *object,  
                                   cos_acl_e cos_acl,
                                   const cos_string_t *grant_read,
                                   const cos_string_t *grant_write,
                                   const cos_string_t *grant_full_ctrl,
                                   cos_table_t **resp_headers);
    

    Parameter description

    Parameter Description Type
    options COS request options Struct
    bucket Bucket name in the format of BucketName-APPID String
    object Object name String
    cos_acl Allow users to customize permissions. Valid values: COS_ACL_PRIVATE(0) (default), COS_ACL_PUBLIC_READ(1), COS_ACL_PUBLIC_READ_WRITE(2) Enum
    grant_read Grants a user permission to read an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". String
    grant_write Grants a user permission to write to an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". String
    grant_full_ctrl Grants a user full permission to operate on an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". String
    resp_headers Returns the HTTP response headers Struct
    Note:

    For more information, please see PUT Object acl and ACL Overview.

    Response description

    Response Parameter Description Type
    code Error code Int
    error_code Error code content String
    error_msg Error code description String
    req_id Request message ID String

    Sample

    #include "cos_http_io.h"
    #include "cos_api.h"
    #include "cos_log.h"
    // `endpoint` is the COS access domain name. For more information, see https://www.tencentcloud.com/document/product/436/6224.
    static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
    // A developer-owned secret ID/key used for the project. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char *TEST_ACCESS_KEY_ID;                // Your SecretId
    static char *TEST_ACCESS_KEY_SECRET;            // Your SecretKey
    // A unique user-level resource identifier for COS access. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char TEST_APPID[] = "<APPID>";    // Your APPID
    // COS bucket name, in the format of [bucket]-[appid], for example `mybucket-1253666666`. It can be obtained at https://console.tencentcloud.com/cos5/bucket.
    static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
    // A unique identifier of an object stored in COS. For more information about objects and object keys, please see https://www.tencentcloud.com/document/product/436/13324.
    static char TEST_OBJECT_NAME1[] = "1.txt";
    void log_status(cos_status_t *s)
    {
      cos_warn_log("status->code: %d", s->code);
      if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
      if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
      if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
    }
    void init_test_config(cos_config_t *config, int is_cname)
    {
      cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
      cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
      cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
      cos_str_set(&config->appid, TEST_APPID);
      config->is_cname = is_cname;
    }
    void init_test_request_options(cos_request_options_t *options, int is_cname)
    {
      options->config = cos_config_create(options->pool);
      init_test_config(options->config, is_cname);
      options->ctl = cos_http_controller_create(options->pool, 0);
    }
    void test_put_object_acl()
    {
      cos_pool_t *p = NULL;
      int is_cname = 0;
      cos_status_t *s = NULL;
      cos_request_options_t *options = NULL;
      cos_string_t bucket;
      cos_string_t object;
      cos_acl_e cos_acl = COS_ACL_PRIVATE; // Use your own configuration
      cos_table_t *resp_headers = NULL;
       // Create a memory pool
      cos_pool_create(&p, NULL);
       // Initialize the request options
      options = cos_request_options_create(p);
      init_test_request_options(options, is_cname);
      cos_str_set(&bucket, TEST_BUCKET_NAME);
       // Set the object ACL (use your own ACL configuration)
      cos_str_set(&object, TEST_OBJECT_NAME1);
      cos_string_t read;
      cos_str_set(&read, "id=\"qcs::cam::uin/12345:uin/12345\", id=\"qcs::cam::uin/45678:uin/45678\"");
      s = cos_put_object_acl(options, &bucket, &object, cos_acl, &read, NULL, NULL, &resp_headers);
      if (cos_status_is_ok(s)) {
          printf("put object acl succeeded\n");
      } else {
          printf("put object acl failed\n");
      }
       // Destroy the memory pool
      cos_pool_destroy(p); 
    }
    int main(int argc, char *argv[])
    {
      // Get SecretId and SecretKey from environment variables
      TEST_ACCESS_KEY_ID     = getenv("COS_SECRETID");
      TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
        if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
         exit(1);
      }
       // Set the log level. Default value: `COS_LOG_WARN`
      cos_log_set_level(COS_LOG_WARN);
       // Set log output. Default value: `stderr`
      cos_log_set_output(NULL);
       test_put_object_acl();
       cos_http_io_deinitialize();
       return 0;
    }
    

    Querying an object ACL

    Description

    The API is used to query the ACL of an object.

    Method prototype

    cos_status_t *cos_get_object_acl(const cos_request_options_t *options, 
                                   const cos_string_t *bucket,
                                   const cos_string_t *object,
                                   cos_acl_params_t *acl_param, 
                                   cos_table_t **resp_headers)
    

    Parameter description

    Parameter Description Type
    options COS request options Struct
    bucket Bucket name in the format: BucketName-APPID String
    object Object name String
    acl_param Parameters for the request Struct
    owner_id ID of the bucket owner String
    owner_id Name of the bucket owner String
    object_list Information on the authorized user and granted permission Struct
    type Authorized user account type String
    id ID of the authorized user String
    name Name of the authorized user String
    permission Permission granted to the authorized user String
    resp_headers Returns the HTTP response headers Struct

    Response description

    Response Parameter Description Type
    code Error code Int
    error_code Error code content String
    error_msg Error code description String
    req_id Request message ID String

    Sample

    #include "cos_http_io.h"
    #include "cos_api.h"
    #include "cos_log.h"
    // `endpoint` is the COS access domain name. For more information, see https://www.tencentcloud.com/document/product/436/6224.
    static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
    // A developer-owned secret ID/key used for the project. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char *TEST_ACCESS_KEY_ID;                // Your SecretId
    static char *TEST_ACCESS_KEY_SECRET;            // Your SecretKey
    // A unique user-level resource identifier for COS access. It can be obtained at https://console.tencentcloud.com/cam/capi.
    static char TEST_APPID[] = "<APPID>";    // Your APPID
    // COS bucket name, in the format of [bucket]-[appid], for example `mybucket-1253666666`. It can be obtained at https://console.tencentcloud.com/cos5/bucket.
    static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
    // A unique identifier of an object stored in COS. For more information about objects and object keys, please see https://www.tencentcloud.com/document/product/436/13324.
    static char TEST_OBJECT_NAME1[] = "1.txt";
    void log_status(cos_status_t *s)
    {
      cos_warn_log("status->code: %d", s->code);
      if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
      if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
      if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
    }
    void init_test_config(cos_config_t *config, int is_cname)
    {
      cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
      cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
      cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
      cos_str_set(&config->appid, TEST_APPID);
      config->is_cname = is_cname;
    }
    void init_test_request_options(cos_request_options_t *options, int is_cname)
    {
      options->config = cos_config_create(options->pool);
      init_test_config(options->config, is_cname);
      options->ctl = cos_http_controller_create(options->pool, 0);
    }
    void test_get_object_acl()
    {
      cos_pool_t *p = NULL;
      int is_cname = 0;
      cos_status_t *s = NULL;
      cos_request_options_t *options = NULL;
      cos_string_t bucket;
      cos_string_t object;
      cos_acl_grantee_content_t *acl_content = NULL;
      cos_table_t *resp_headers = NULL;
       // Create a memory pool
      cos_pool_create(&p, NULL);
       // Initialize the request options
      options = cos_request_options_create(p);
      init_test_request_options(options, is_cname);
      cos_str_set(&bucket, TEST_BUCKET_NAME);
      cos_str_set(&object, TEST_OBJECT_NAME1);
       // Get the object ACL
      cos_acl_params_t *acl_params2 = NULL;
      acl_params2 = cos_create_acl_params(p);
      s = cos_get_object_acl(options, &bucket, &object, acl_params2, &resp_headers);
      if (cos_status_is_ok(s)) {
          printf("get object acl succeeded\n");
          printf("acl owner id:%s, name:%s\n", acl_params2->owner_id.data, acl_params2->owner_name.data);
          acl_content = NULL;
          cos_list_for_each_entry(cos_acl_grantee_content_t, acl_content, &acl_params2->grantee_list, node) {
              printf("acl grantee id:%s, name:%s, permission:%s\n", acl_content->id.data, acl_content->name.data, acl_content->permission.data);
          }
      } else {
          printf("get object acl failed\n");
      }
       // Destroy the memory pool
      cos_pool_destroy(p); 
    }
    int main(int argc, char *argv[])
    {
      // Get SecretId and SecretKey from environment variables
      TEST_ACCESS_KEY_ID     = getenv("COS_SECRETID");
      TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
        if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
         exit(1);
      }
       // Set the log level. Default value: `COS_LOG_WARN`
      cos_log_set_level(COS_LOG_WARN);
       // Set log output. Default value: `stderr`
      cos_log_set_output(NULL);
       test_get_object_acl();
       cos_http_io_deinitialize();
       return 0;
    }
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support