Bucket Operations

Last updated: 2020-05-20 14:54:50

    Overview

    This document provides an overview of APIs and SDK sample codes related to the basic bucket operations and access control lists (ACL).

    Basic operations

    API Operation Description
    GET Service Querying a bucket list Queries the list of all buckets under a specified account
    PUT Bucket Creating a bucket Creates a bucket under a specified account
    HEAD Bucket Retrieving information on a bucket and its permission Checks whether a bucket exists and if you have the permission to access it
    DELETE Bucket Deleting a bucket Deletes an empty bucket under a specified account

    ACL

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

    Basic operations

    Querying a bucket list

    Feature description

    This API is used to query the list of all buckets under a specified account.

    Method prototype

    GetServiceResult GetService(GetServiceRequest request);
    
    void GetService(GetServiceRequest 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
    {
      GetServiceRequest request = new GetServiceRequest();
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      GetServiceResult result = cosXml.GetService(request);
      // Get a list of all buckets
      List<ListAllMyBuckets.Bucket> allBuckets = result.listAllMyBuckets.buckets;
    }
    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
    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 Indicates whether the signature verifies the header List<string>
    queryParameterKeys SetSign Indicates whether the signature verifies the query parameters in the request URL List<string>

    Response description

    The result of the request is returned through GetServiceResult.

    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.
    listAllMyBuckets ListAllMyBuckets Returns the list of buckets under the specified account

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

    Creating a bucket

    Feature description

    This API is used to create a bucket under a specified account.

    Method prototype

    PutBucketResult PutBucket(PutBucketRequest request);
    
    void PutBucket(PutBucketRequest 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
      PutBucketRequest request = new PutBucketRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      PutBucketResult result = cosXml.PutBucket(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
    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 in measured seconds, e.g., if a signature is valid for 1 minute, this value would be 60 long
    headerKeys SetSign Indicates whether the signature verifies the header List<string>
    queryParameterKeys SetSign Indicates whether the signature verifies the query parameters in the request URL List<string>

    Response description

    The result of the request is returned through PutBucketResult.

    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.

    Retrieving information on a bucket and its permission

    Feature description

    This API is used to verify whether a bucket exists and if you have the permission to access it.

    Method prototype

    HeadBucketResult HeadBucket(HeadBucketRequest request);
    
    void HeadBucket(HeadBucketRequest 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
      HeadBucketRequest request = new HeadBucketRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      HeadBucketResult result = cosXml.HeadBucket(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());
    }

    Deleting a bucket

    Feature description

    This API is used to delete an empty bucket under a specified account.

    Method prototype

    DeleteBucketResult DeleteBucket(DeleteBucketRequest request);
    
    void DeleteBucket(DeleteBucketRequest 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
      DeleteBucketRequest request = new DeleteBucketRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      DeleteBucketResult result = cosXml.DeleteBucket(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
    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 Indicates whether the signature verifies the header List<string>
    queryParameterKeys SetSign Indicates whether the signature verifies the query parameters in the request URL List<string>

    Response description

    The result of the request is returned through DeleteBucketResult.

    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.

    ACL

    Setting bucket ACL

    Feature description

    This API is used to set the access control list (ACL) of a specified object in a 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 the read permission to the 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 int he format: BucketName-APPID string
    cosAcl SetCosAcl Sets the ACL permissions for the bucket 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 Indicates whether the signature verifies the header List<string>
    queryParameterKeys SetSign Indicates whether the signature verifies the query parameters in the request URL 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 bucket ACL

    Feature description

    This API is used to query the access control list (ACL) of a 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 Indicates whether the signature verifies the header List<string>
    queryParameterKeys SetSign Indicates whether the signature verifies the query parameters in the request URL 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 information on the bucket ACL

    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