Access Control

Last updated: 2020-05-25 11:42:54

    Overview

    This document provides an overview of APIs and SDK code samples related to bucket and object access control lists (ACL).

    Bucket ACL

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

    Object ACL

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

    Bucket ACL

    Setting a bucket ACL

    Feature description

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

    Method prototype

    PutBucketACLResult PutBucketACL(PutBucketACLRequest request);
    
    void PutBucketACL(PutBucketACLRequest request, COSXML.Callback.OnSuccessCallback<CosResult> successCallback, COSXML.Callback.OnFailedCallback failCallback);

    Sample request

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Sets the connection timeout period in milliseconds; this value is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Sets the read/write timeout period in milliseconds; this value is 45,000 ms by default
      .IsHttps(true)  // Sets HTTPS as the default request method
      .SetAppid("1250000000") // Sets the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Sets the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // The SecretId of your TencentCloud API key
    String secretKey = "COS_SECRETKEY"; // The SecretKey of your TencentCloud API key
    long durationSecond = 600;          // Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
      PutBucketACLRequest request = new PutBucketACLRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Set private read and write permissions
      request.SetCosACL(CosACL.PRIVATE);
      // Grant read permission to account 1131975903
      COSXML.Model.Tag.GrantAccount readAccount = new COSXML.Model.Tag.GrantAccount();
      readAccount.AddGrantAccount("1131975903", "1131975903");
      request.SetXCosGrantRead(readAccount);
      // Execute the request
      PutBucketACLResult result = cosXml.PutBucketACL(request);
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Bucket name in the format: BucketName-APPID string
    cosAcl SetCosAcl Sets bucket ACL permission string
    grantAccount SetXCosGrantRead, SetXCosGrantWrite, or SetXCosReadWrite Grants users read and write permissions GrantAccount
    signStartTimeSecond SetSign Start time of the signature's validity period in the format of a Unix timestamp, e.g., 1557902800 long
    durationSecond SetSign Signature validity period measured in seconds, e.g., if a signature is valid for 1 minute, this value would be 60 long
    headerKeys SetSign Signature request header List<string>
    queryParameterKeys SetSign Signature request parameter List<string>

    Response description

    The result of the request is returned through PutBucketACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code within the range of [200, 300) indicates a successful operation. Other values indicate a failure.

    If the operation fails, the system will throw a CosClientException or CosServiceException exception.

    Querying a bucket ACL

    Feature description

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

    Method prototype

    GetBucketACLResult GetBucketACL(GetBucketACLRequest request);
    
    void GetBucketACL(GetBucketACLRequest request, COSXML.Callback.OnSuccessCallback<CosResult> successCallback, COSXML.Callback.OnFailedCallback failCallback);

    Sample request

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Sets the connection timeout period in milliseconds; this value is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Sets the read/write timeout period in milliseconds; this value is 45,000 ms by default
      .IsHttps(true)  // Sets HTTPS as the default request method
      .SetAppid("1250000000") // Sets the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Sets the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // The SecretId of your TencentCloud API key
    String secretKey = "COS_SECRETKEY"; // The SecretKey of your TencentCloud API key
    long durationSecond = 600;          // Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
      GetBucketACLRequest request = new GetBucketACLRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      GetBucketACLResult result = cosXml.GetBucketACL(request);
      // Bucket ACL information
      AccessControlPolicy acl = result.accessControlPolicy;
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Bucket name in the format: BucketName-APPID string
    signStartTimeSecond SetSign Start time of the signature's validity period in the format of a Unix timestamp, e.g., 1557902800 long
    durationSecond SetSign Signature validity period measured in seconds, e.g., if a signature is valid for 1 minute, this value would be 60 long
    headerKeys SetSign Signature request header List<string>
    queryParameterKeys SetSign Signature request parameter List<string>

    Response description

    The result of the request is returned through GetBucketACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code within the range of [200, 300) indicates a successful operation. Other values indicate a failure.
    accessControlPolicy AccessControlPolicy Returns the bucket ACL information

    If the operation fails, the system will throw a CosClientException or CosServiceException exception.

    Object ACL

    Setting object ACL

    Feature description

    This API is used to set the ACL for a specified object.

    Method prototype

    PutObjectACLResult PutObjectACL(PutObjectACLRequest request);
    
    void PutObjectACL(PutObjectACLRequest request, COSXML.Callback.OnSuccessCallback<CosResult> successCallback, COSXML.Callback.OnFailedCallback failCallback);

    Sample request

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Sets the connection timeout period in milliseconds; this value is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Sets the read/write timeout period in milliseconds; this value is 45,000 ms by default
      .IsHttps(true)  // Sets HTTPS as the default request method
      .SetAppid("1250000000") // Sets the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Sets the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // The SecretId of your TencentCloud API key
    String secretKey = "COS_SECRETKEY"; // The SecretKey of your TencentCloud API key
    long durationSecond = 600;          // Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    // To avoid hitting the ACL limit of 1000
    // We do not recommend setting an ACL for an individual object unless absolutely necessary. Objects are subject to their bucket’s ACL by default.
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
      PutObjectACLRequest request = new PutObjectACLRequest(bucket, key);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Set private read and write permissions 
      request.SetCosACL(CosACL.PRIVATE);
      // Grant read permission to account 1131975903 
      COSXML.Model.Tag.GrantAccount readAccount = new COSXML.Model.Tag.GrantAccount();
      readAccount.AddGrantAccount("1131975903", "1131975903");
      request.SetXCosGrantRead(readAccount);
      // Execute the request
      PutObjectACLResult result = cosXml.PutObjectACL(request);
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Bucket name in the format: BucketName-APPID string
    key Constructor or SetCosPath Object key of the object stored in COS string
    cosAcl SetCosAcl Sets bucket ACL permission string
    grantAccount SetXCosGrantRead, SetXCosGrantWrite, or SetXCosReadWrite Grants users read and write permissions GrantAccount
    signStartTimeSecond SetSign Start time of the signature's validity period in the format of a Unix timestamp, e.g., 1557902800 long
    durationSecond SetSign Signature validity period measured in seconds, e.g., if a signature is valid for 1 minute, this value would be 60 long
    headerKeys SetSign Signature request header List<string>
    queryParameterKeys SetSign Signature request parameter List<string>

    Response description

    The result of the request is returned through PutObjectACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code within the range of [200, 300) indicates a successful operation. Other values indicate a failure.

    If the operation fails, the system will throw a CosClientException or CosServiceException exception.

    Querying an object ACL

    Feature description

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

    Method prototype

    GetObjectACLResult GetObjectACL(GetObjectACLRequest request);
    
    void GetObjectACL(GetObjectACLRequest request, COSXML.Callback.OnSuccessCallback<CosResult> successCallback, COSXML.Callback.OnFailedCallback failCallback);

    Sample request

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Sets the connection timeout period in milliseconds; this value is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Sets the read/write timeout period in milliseconds; this value is 45,000 ms by default
      .IsHttps(true)  // Sets HTTPS as the default request method
      .SetAppid("1250000000") // Sets the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Sets the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // The SecretId of your TencentCloud API key
    String secretKey = "COS_SECRETKEY"; // The SecretKey of your TencentCloud API key
    long durationSecond = 600;          // Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
      GetObjectACLRequest request = new GetObjectACLRequest(bucket, key);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      GetObjectACLResult result = cosXml.GetObjectACL(request);
      // Object’s ACL information
      AccessControlPolicy acl = result.accessControlPolicy;
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Bucket name in the format: BucketName-APPID string
    key Constructor or SetCosPath Object key of the object stored in COS string
    signStartTimeSecond SetSign Start time of the signature's validity period in the format of a Unix timestamp, e.g., 1557902800 long
    durationSecond SetSign Signature validity period measured in seconds, e.g., if a signature is valid for 1 minute, this value would be 60 long
    headerKeys SetSign Signature request header List<string>
    queryParameterKeys SetSign Signature request parameter List<string>

    Response description

    The result of the request is returned through GetObjectACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code within the range of [200, 300) indicates a successful operation. Other values indicate a failure.
    accessControlPolicy AccessControlPolicy Returns object ACL information

    If the operation fails, the system will throw a CosClientException or CosServiceException exception.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help