TencentCloud API has been upgraded to v3.0. This version is optimized for performance and deployed in all regions. It supports nearby access and access by region for significantly reduced access latency. In addition, it features more detailed API descriptions and error codes and API-level comments for SDKs, enabling you to use Tencent Cloud services more conveniently and quickly. This document describes how to call APIs for Python.
This version currently supports various Tencent Cloud services such as CVM, CBS, VPC, and TencentDB and will support more services in the future.
Request Structure
1. Service address (endpoint)
TencentCloud API supports access from either a nearby region (such as cvm.tencentcloudapi.com for CVM) or a specified region (such as cvm.ap-guangzhou.tencentcloudapi.com for CVM in the Guangzhou region). For values of the region parameter, please see the region list in the "Common Parameters" section below. To check whether a region is supported by a specific Tencent Cloud service, please see its "Request Structure" document.
Note:
For latency-sensitive businesses, we recommend you specify a domain name with a region.
2. Communications protocol
All TencentCloud APIs communicate over HTTPS, providing highly secure communications tunnels.
3. Request method
Supported HTTP request methods:
POST (recommended)
GET
Content-Type types supported by POST request:
application/json (recommended). The signature algorithm v3 (TC3-HMAC-SHA256) must be used.
application/x-www-form-urlencoded. The signature algorithm v1 (HmacSHA1 or HmacSHA256) must be used.
multipart/form-data (only supported by certain APIs). The signature algorithm v3 (TC3-HMAC-SHA256) must be used.
The size of a GET request packet cannot exceed 32 KB. The size of a POST request cannot exceed 1 MB for the signature algorithm v1 (HmacSHA1 or HmacSHA256) or 10 MB for the signature algorithm v3 (TC3-HMAC-SHA256).
4. Character encoding
UTF-8 encoding is always used.
Common Parameters
Note:
The common parameters are used to identity the user and API signature. They should be carried by each request to initiate properly.
Signature algorithm v3
The signature algorithm v3 (sometimes referred to as "TC3-HMAC-SHA256") is more secure than the signature algorithm v1 (referred to as signature algorithm in certain documents), supports larger request packets and POST JSON format, and has a higher performance. We recommend you use it to calculate signatures. For more information on how to use it, please see below.
Parameter Name
Type
Required
Description
X-TC-Action
String
Yes
Name of the API for the desired operation. For the specific value, please see the description of common parameter Action in the input parameters in the related API document. For example, the API for querying CVM instance list is DescribeInstances.
X-TC-Region
String
-
Region parameter, which is used to identify the region where the data you want to manipulate resides. For values supported for an API, please see the description of common parameter Region in the input parameters in related API documentation. Note: this parameter is not required for some APIs (which will be indicated in related API documentation) and will not take effect even if it is passed.
X-TC-Timestamp
Integer
Yes
The current UNIX timestamp that records the time when the API request was initiated, such as 1529223702. Note: if the difference between the UNIX timestamp and the server time is greater than 5 minutes, a signature expiration error may occur.
X-TC-Version
String
Yes
Version of the API for the desired operation, such as 2017-03-12 for CVM. For the specific value, please see the description of common parameter Version in the input parameters in related API documentation.
Authorization
String
Yes
HTTP authentication request header, such as TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168
Here,
TC3-HMAC-SHA256: signature algorithm, currently fixed as this value.
Credential: signature credential. AKIDEXAMPLE indicates the SecretId.
Date indicates a UTC date which must match the value of X-TC-Timestamp (a common parameter) in UTC format.
service indicates the name of the service and is generally a domain name prefix; for example, the domain name cvm.tencentcloudapi.com means the CVM service, and the value for this service is cvm.
SignedHeaders: the headers that contain the authentication information. content-type and host are required.
Signature: signature digest. For the calculation process, please see below.
X-TC-Token
String
No
Token used for temporary credentials. It must be used with a temporary key. You can get the temporary key and token by calling a CAM API. No token is required for a long-term key.
Signature algorithm v1
When the signature algorithm v1 (sometimes referred to as "HmacSHA256" or "HmacSHA1") is used, the common parameters should be uniformly placed in the request string.
Parameter Name
Type
Required
Description
Action
String
Yes
Name of the API for the desired operation. For the specific value, please see the description of common parameter Action in the input parameters in the related API document. For example, the API for querying CVM instance list is DescribeInstances.
Region
String
-
Region parameter, which is used to identify the region where the data you want to manipulate resides. For values supported for an API, please see the description of common parameter Region in the input parameters in related API documentation. Note: this parameter is not required for some APIs (which will be indicated in related API documentation) and will not take effect even if it is passed.
Timestamp
Integer
Yes
The current UNIX timestamp that records the time when the API request was initiated, such as 1529223702. If the difference between the UNIX timestamp and the current time is too large, a signature expiration error may occur.
Nonce
Integer
Yes
A random positive integer used in conjunction with Timestamp to prevent replay attacks.
SecretId
String
Yes
The identifying SecretId obtained on the TencentCloud API Key page. A SecretId corresponds to a unique SecretKey which is used to generate the request signature (Signature).
Signature
String
Yes
Request signature, which is used to verify the validity of the request. It is generated based on input parameters. For more information on how to calculate the signature, please see below.
Version
String
Yes
Version of the API for the desired operation, such as 2017-03-12 for CVM. For the specific value, please see the description of common parameter Version in the input parameters in related API documentation.
SignatureMethod
String
No
Signature algorithm. Currently, only HmacSHA256 and HmacSHA1 are supported. The HmacSHA256 algorithm is used to verify the signature only when this parameter is specified as HmacSHA256. In other cases, the signature is verified with HmacSHA1.
Token
String
No
Token used for temporary credentials. It must be used with a temporary key. You can get the temporary key and token by calling a CAM API. No token is required for a long-term key.
Region list
As the supported regions vary by service, please refer to the region list in each service's product documentation for specific details.
For example, you can see the region list of CVM.
API Call Method for Python
TencentCloud API authenticates every request, that is, the request must be signed with the security credentials in the designated steps. Each request must contain the signature information in the common request parameters and be sent in the specified way and format.
Suppose your SecretId and SecretKey are AKIDz8krbsJ5**********mLPx3EXAMPLE and Gu5t9xGAR***********EXAMPLE, respectively. If you want to view the status of an unnamed instance in the Guangzhou region and have only one data entry returned, the request may be:
In this document, the security credential used is a key pair, which consists of a SecretId and a SecretKey. Each user can have up to two key pairs.
SecretId: identifies the user that calls an API, which is similar to a username.
SecretKey: authenticates the user that calls the API, which is similar to a password.
Note:
You must keep your security credentials private and avoid disclosure; otherwise, your assets may be compromised. If they are disclosed, please disable them as soon as possible.
The signature algorithm v3 (TC3-HMAC-SHA256) is compatible with the previous signature algorithm v1 and more secure, supports larger request packets and POST JSON format, and has a higher performance. We recommend you use it to calculate signatures as shown below:
Note:
If you are using the signature algorithm for the first time, we recommend you use the "signature string generation" feature in API Explorer and select "API 3.0 signature v3" as the signature version, which can generate a signature for demonstration and verification. Plus, it can also generate SDK code directly. Seven common open-source programming language SDKs are available for TencentCloud API, including Python, Java, PHP, Go, Node.js, .NET, and C++.
TencentCloud API supports both GET and POST requests. For the GET method, only the Content-Type: application/x-www-form-urlencoded protocol format is supported. For the POST method, Content-Type: application/json and Content-Type: multipart/form-data are supported. The JSON format is supported by all business APIs, while the multipart format is supported only by specific APIs (in this case, an API cannot be called in JSON format). For more information, please see the specific business API document. We recommend you use the POST method because the two methods generate the same results, but the GET method only supports request packets below 32 KB in size.
The following describes how to calculate a signature by calling the DescribeInstances API. This API is chosen because:
1. The CVM API is enabled by default, and this API is often used.
2. It is read-only and does not change the status of existing resources.
3. It covers many types of parameters so that it is easy to show how to use an array that contains data structures.
1. Concatenate the canonical request string
CanonicalRequest =
HTTPRequestMethod + '\\n' +
CanonicalURI + '\\n' +
CanonicalQueryString + '\\n' +
CanonicalHeaders + '\\n' +
SignedHeaders + '\\n' +
HashedRequestPayload
Field
Description
HTTPRequestMethod
HTTP request method (GET or POST). This example uses POST.
CanonicalURI
URI parameter. Slash ("/") is used for API 3.0.
CanonicalQueryString
Query string in the URL of the originating HTTP request. This is always an empty string "" for POST requests and is the string after the question mark (?) for GET requests such as Limit=10&Offset=0. Note: CanonicalQueryString must be URL-encoded as instructed in RFC 3986 with the UTF-8 character set. The applicable standard programming language library is recommended. All special characters must be encoded and capitalized.
CanonicalHeaders
Header information for signature calculation, including at least host and content-type. Custom headers can also be added to the signature process to improve the uniqueness and security of the request. Concatenation rules: both the key and value of a header should be converted to lowercase with the leading and trailing spaces removed so that they are concatenated in the key:value\\n format. If there are multiple headers, they should be sorted in ASCII ascending order by header key (lowercase). The calculation result in this example is content-type:application/json; charset=utf-8\\nhost:cvm.tencentcloudapi.com\\n. Note: content-type must match the content that is actually sent. In some programming languages, a charset value is automatically added even if it is not specified. In this case, the request sent will be different from the one signed, and the sever will return a signature verification failure.
SignedHeaders
Header information for signature calculation, indicating the request headers that are involved in the signature process. The request headers must correspond to the headers in CanonicalHeaders. Content-type and host are required headers. Concatenation rules: both the key and value of a header should be converted to lowercase. If there are multiple headers, they should be sorted in ASCII ascending order by header key (lowercase) and separated by semicolons (;). The value in this example is content-type;host.
HashedRequestPayload
Hash value of Requestpayload (i.e., the request body, such as {"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]} in this example). The pseudo-code for calculation is Lowercase(HexEncode(Hash.SHA256(RequestPayload))), which means that SHA256 hashing is performed on the payload of the HTTP request, then hexadecimal encoding is performed, and finally the encoded string is converted to lowercase letters. For GET requests, RequestPayload is always an empty string. The calculation result in this example is 35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064.
According to the rules above, the canonical request string obtained in the example is as follows:
Concatenate the string to sign in the following format:
StringToSign =
Algorithm + \\n +
RequestTimestamp + \\n +
CredentialScope + \\n +
HashedCanonicalRequest
Field
Description
Algorithm
Signature algorithm, which is always TC3-HMAC-SHA256 currently.
RequestTimestamp
Request timestamp, i.e., the value of the common parameter X-TC-Timestamp in the request header. It is the UNIX timestamp of the current time in seconds, such as 1551113065 in this example.
CredentialScope
Scope of the credential in the format of Date/service/tc3_request, including the date, requested service, and termination string (tc3_request). Date indicates a UTC date, which should match the UTC date converted by the common parameter X-TC-Timestamp.service is the service name, which should match the domain name of the service called. The calculation result in this example is 2019-02-25/cvm/tc3_request.
HashedCanonicalRequest
Hash value of the canonical request string concatenated in the steps above. The pseudo-code for calculation is Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculation result in this example is 5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031.
Note:
Date must be calculated from the timestamp X-TC-Timestamp and the time zone is UTC+0. If you add the local time zone information (such as UTC+8) in the system, calls can succeed both day and night but will definitely fail at 00:00. For example, if the timestamp is 1551113065 and the time in UTC+8 is 2019-02-26 00:44:25, the UTC+0 date in the calculated Date value should be 2019-02-25 instead of 2019-02-26.
Timestamp must be the same as your current system time, and your system time must be in sync with the UTC time. If the difference between the timestamp and your current system time is greater than five minutes, the request will fail. If your system time is out of sync with the UTC time for a prolonged period, the request will fail, and a signature expiration error will be returned.
According to the rules above, the string to sign obtained in the example is as follows:
The signature algorithm v1 (HmacSHA1 or HmacSHA256) is simple and easy to use, but its functionality and security are not as good as the signature algorithm v3 which is therefore recommended.
If you are using the signature algorithm for the first time, we recommend you use the "signature string generation" feature in API Explorer and select "API 3.0 signature v1" as the signature version, which can generate a signature for demonstration and verification and provides signing examples for certain programming languages. Plus, it can also generate SDK code directly. Seven common open-source programming language SDKs are available for TencentCloud API, including Python, Java, PHP, Go, Node.js, .NET, and C++.
For example, if you call the DescribeInstances API to query CVM instances, the request parameters may be as follows:
Parameter Name
Description
Value
Action
Method
DescribeInstances
SecretId
Key ID
AKIDz8krbsJ5**********mLPx3EXAMPLE
Timestamp
Current timestamp
1465185768
Nonce
Random positive integer
11886
Region
Instance region
ap-guangzhou
InstanceIds.0
ID of the instance to be queried
ins-09dx96dg
Offset
Offset
0
Limit
Allowed maximum number of output entries
20
Version
API version number
2017-03-12
1. Sort parameters
Sort all the request parameters in an ascending lexicographical order (ASCII code) by their names.
Note:
1. The parameters are sorted only by name but not by value.
2. The parameters are sorted based on ASCII code but not in an alphabetical order or by value. For example, InstanceIds.2 should be arranged behind InstanceIds.12. You can complete sorting by using a sorting function in a programming language, such as the ksort function in PHP.
The parameters in the example are sorted as follows:
{
'Action':'DescribeInstances',
'InstanceIds.0':'ins-09dx96dg',
'Limit':20,
'Nonce':11886,
'Offset':0,
'Region':'ap-guangzhou',
'SecretId':'AKIDz8krbsJ5**********mLPx3EXAMPLE',
'Timestamp':1465185768,
'Version':'2017-03-12',
}
Any other programming languages can be used to sort these parameters as long as the same result is produced.
2. Concatenate the canonical request string
This step generates a request string. Format the request parameters sorted in the previous step into the form of parameter=value. For example, for the Action parameter, its parameter is Action and its value is DescribeInstances; therefore, the parameter will be formatted into Action=DescribeInstances.
Note:
The value is the original value instead of the URL-encoded value.
Then, concatenate the formatted parameters with &. The generated request string will be as follows:
This step generates the original signature string. The original signature string consists of the following parameters:
1. Request method: POST and GET methods are supported. GET is used here for the request. Please note that the method name should be in all capital letters.
2. Request server: the domain name of the request for querying instances (DescribeInstances) is cvm.tencentcloudapi.com. The actual request domain name varies by the module to which the API belongs. For more information, please see the specific API document.
3. Request path: the request path in the current version of TencentCloud API is fixed to /.
4. Request string: the request string generated in the previous step.
The rule for concatenating the original string of the signature is request method + request server + request path + ? + request string.
The concatenation result in the example is as follows:
This step generates a signature string. Use the HMAC-SHA1 algorithm to sign the original signature string obtained in the previous step, and then Base64-encode the generated signature to get the final signature.
secret_key ="Gu5t9xGAR********QYCN3EXAMPLE"
s ="GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yK**********mLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12"
API parameter of the sample API 3.0 signature v1. Note: you should add the calculated signature in the format of key-value pair to data.
Note:
The key in the example is not real, and the timestamp is not the current system time. If you open this URL in the browser or call it by using commands such as curl, an authentication error The signature expired will be returned. To obtain a URL that works, you need to replace the SecretId and SecretKey in this example with your own credentials and use the current system time as the Timestamp.
To further explain the signing process, Python is used as examples below to implement the process as described above. The request domain name, API, and parameter values in the above example are used here. The code below is for demonstration only. Please use the SDK for actual development.
6. Encode a signature string
The generated signature string cannot be directly used as a request parameter and needs to be URL-encoded.
For example, if the signature string generated in the previous step is Eli*****************cGeI=, the final value of the Signature request parameter will be EliP***********************eI%3D, which will be used to generate the final request URL.
Note:
If you use the GET request method or use the POST request method with Content-Type of application/x-www-form-urlencoded, all the request parameter values must be URL-encoded (except the parameter key and the equal symbol (=)) before the request is sent. Non-ASCII characters must be encoded with UTF-8 before URL-encoding.
The network libraries of some programming languages automatically URL-encode all parameters. In this case, the signature string does not need to be URL-encoded again; otherwise, two rounds of URL-encoding will cause the signature to fail.
Other parameter values also need to be encoded with RFC 3986. Use %XY in percent-encoding for special characters such as Chinese characters, where "X" and "Y" are hexadecimal characters (0–9 and uppercase A–F). Using lowercase characters will cause an error.
7. Sample API 3.0 signature v1
Note:
In the Python 2 environment, the following requests dependency package must be installed first by running pip install requests.
# -*- coding: utf8 -*-
import base64
import hashlib
import hmac
import time
import requests
secret_id ="AKIDz8k*********LPx3EXAMPLE"
secret_key ="Gu5t9xGA*********YCN3EXAMPLE"
defget_string_to_sign(method, endpoint, params):
s = method + endpoint +"/?"
query_str ="&".join("%s=%s"%(k, params[k])for k insorted(params))
This signature version has been disused. We recommend you use API 3.0 signature with better performance. If you still need to use it, please go to API Explorer > Signature Generation and select API 2.0 Signature as the signature version.
Signature Failure
The following error codes may be returned for signature failure. Please resolve the errors accordingly.
Error Code
Error Description
AuthFailure.SignatureExpire
The signature expired. The difference between the Timestamp and the server time cannot be greater than five minutes.
AuthFailure.SecretIdNotFound
The key does not exist. Log in to the console and check whether it is disabled or you copied fewer or more characters.
AuthFailure.SignatureFailure
Signature error. It is possible that the signature is calculated incorrectly, the signature does not match the content that is actually sent, or the SecretKey is incorrect.
AuthFailure.TokenFailure
Temporary credential token error.
AuthFailure.InvalidSecretId
Invalid key (not TencentCloud API key type).
Returned Result
Successful response
For example, when calling the CVM API DescribeInstancesStatus (version: 2017-03-12) to view the status of instances, if the request succeeds, you may see the following response:
The API will return Response, which contains RequestId, as long as it processes the request, no matter whether the request is successful or not.
RequestId is the unique ID of an API request. It is required to troubleshoot issues.
Any fields other than the common fields are API-specific. For more information on such fields, please see the relevant API documentation. In this example, both TotalCount and InstanceStatusSet are specific to the DescribeInstancesStatus API. Since the user who initiated the request does not have a CVM instance yet, 0 is returned for TotalCount and InstanceStatusSet is empty.
Error response
If the call fails, you may see the following response:
{
"Response":{
"Error":{
"Code":"AuthFailure.SignatureFailure",
"Message":"The provided credentials could not be validated. Please check your signature is correct."
Error indicates that the request failed. A response for a failed request will always include the Error, Code, and Message fields.
Code indicates the specific error code, which is returned when an API request failed. You can use this code to locate the cause and solution of the error in the common or API-specific error code list.
Message explains the cause of the error. Note that the returned messages are subject to service updates. The information the messages provide may not be up-to-date and should not be the only source of reference.
RequestId is the unique ID of an API request. It is required to troubleshoot issues.
Common error codes
The Error field in a response indicates that the API call failed. The Code field in Error indicates the error code. The following table lists the common error codes that any services may return.
Error Code
Error Description
AuthFailure.InvalidSecretId
Invalid key (not TencentCloud API key type).
AuthFailure.MFAFailure
MFA failure.
AuthFailure.SecretIdNotFound
The key does not exist.
AuthFailure.SignatureExpire
The signature expired.
AuthFailure.SignatureFailure
Signature error.
AuthFailure.TokenFailure
Token error.
AuthFailure.UnauthorizedOperation
No CAM authorization.
DryRunOperation
DryRun Operation. It means that the request would have succeeded, but the DryRun parameter was used.
FailedOperation
The operation failed.
InternalError
Internal error.
InvalidAction
The API does not exist.
InvalidParameter
Incorrect parameter.
InvalidParameterValue
Invalid parameter value.
LimitExceeded
The quota limit is exceeded.
MissingParameter
A parameter is missing.
NoSuchVersion
The API version does not exist.
RequestLimitExceeded
The request rate limit is exceeded.
ResourceInUse
The resource is in use.
ResourceInsufficient
Insufficient resource.
ResourceNotFound
The resource does not exist.
ResourceUnavailable
The resource is unavailable.
UnauthorizedOperation
Unauthorized operation.
UnknownParameter
Unknown parameter error.
UnsupportedOperation
Unsupported operation.
UnsupportedProtocol
Unsupported HTTPS request method. Only GET and POST requests are supported.
Yes
No
Was this page helpful?