公共参数

最近更新时间:2023-12-28 01:08:19

我的收藏

公共参数是用于标识用户和接口签名的参数,如非必要,在每个接口单独的文档中不再对这些参数进行说明,但每次请求均需要携带这些参数,才能正常发起请求。

公共参数的具体内容会因您使用的签名方法版本不同而有所差异。

使用签名方法 v3 的公共参数

签名方法 v3 (有时也称作 TC3-HMAC-SHA256)相比签名方法 v1 (有些文档可能会简称签名方法),更安全,支持更大的请求包,支持 POST JSON 格式,性能有一定提升,推荐使用该签名方法计算签名。完整介绍详见 签名方法 v3

注意:出于简化的目的,部分接口文档中的示例使用的是签名方法 v1 GET 请求,而不是更安全的签名方法 v3。

使用签名方法 v3 时,公共参数需要统一放到 HTTP Header 请求头部中,如下表所示:

参数名称 类型 必选 描述
Action String HTTP 请求头:X-TC-Action。操作的接口名称。取值参考接口文档输入参数章节关于公共参数 Action 的说明。例如云服务器的查询实例列表接口,取值为 DescribeInstances。
Region String - HTTP 请求头:X-TC-Region。地域参数,用来标识希望操作哪个地域的数据。取值参考接口文档中输入参数章节关于公共参数 Region 的说明。注意:某些接口不需要传递该参数,接口文档中会对此特别说明,此时即使传递该参数也不会生效。
Timestamp Integer HTTP 请求头:X-TC-Timestamp。当前 UNIX 时间戳,可记录发起 API 请求的时间。例如 1529223702。注意:如果与服务器时间相差超过5分钟,会引起签名过期错误。
Version String HTTP 请求头:X-TC-Version。操作的 API 的版本。取值参考接口文档中入参公共参数 Version 的说明。例如云服务器的版本 2017-03-12。
Authorization String HTTP 标准身份认证头部字段,例如:
TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
其中,
- TC3-HMAC-SHA256:签名方法,目前固定取该值;
- Credential:签名凭证,AKIDEXAMPLE 是 SecretId;Date 是 UTC 标准时间的日期,取值需要和公共参数 X-TC-Timestamp 换算的 UTC 标准时间日期一致;service 为具体产品名,通常为域名前缀。例如,域名 cvm.tencentcloudapi.com 意味着产品名是 cvm。本产品取值为 cat;tc3_request 为固定字符串;
- SignedHeaders:参与签名计算的头部信息,content-type 和 host 为必选头部;
- Signature:签名摘要,计算过程详见 文档
Token String HTTP 请求头:X-TC-Token。即 安全凭证服务 所颁发的临时安全凭证中的 Token,使用时需要将 SecretId 和 SecretKey 的值替换为临时安全凭证中的 TmpSecretId 和 TmpSecretKey。使用长期密钥时不能设置此 Token 字段。
Language String HTTP 请求头:X-TC-Language。指定接口返回的语言,仅部分接口支持此参数。取值:zh-CN,en-US。zh-CN 返回中文,en-US 返回英文。

假设用户想要查询广州地域的云服务器实例列表中的前十个,接口参数设置为偏移量 Offset=0,返回数量 Limit=10,则其请求结构按照请求 URL、请求头部、请求体示例如下:

HTTP GET 请求结构示例:

https://cvm.tencentcloudapi.com/?Limit=10&Offset=0

Authorization: TC3-HMAC-SHA256 Credential=AKID********EXAMPLE/2018-10-09/cvm/tc3_request, SignedHeaders=content-type;host, Signature=5da7a33f6993f0614b047e5df4582db9e9bf4672ba50567dba16c6ccf174c474
Content-Type: application/x-www-form-urlencoded
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1539084154
X-TC-Region: ap-guangzhou

HTTP POST (application/json) 请求结构示例:

https://cvm.tencentcloudapi.com/

Authorization: TC3-HMAC-SHA256 Credential=AKID********EXAMPLE/2018-05-30/cvm/tc3_request, SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b13162d9279b0855cfba6789a8edb4c
Content-Type: application/json
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou

{"Offset":0,"Limit":10}

HTTP POST (multipart/form-data)请求结构示例(仅特定的接口支持):

https://cvm.tencentcloudapi.com/

Authorization: TC3-HMAC-SHA256 Credential=AKID********EXAMPLE/2018-05-30/cvm/tc3_request, SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b13162d9279b0855cfba6789a8edb4c
Content-Type: multipart/form-data; boundary=58731222010402
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou

--58731222010402
Content-Disposition: form-data; name="Offset"

0
--58731222010402
Content-Disposition: form-data; name="Limit"

10
--58731222010402--

使用签名方法 v1 的公共参数

使用签名方法 v1 (有时会称作 HmacSHA256 和 HmacSHA1),公共参数需要统一放到请求串中,完整介绍详见文档

参数名称 类型 必选 描述
Action String 操作的接口名称。取值参考接口文档中输入参数章节关于公共参数 Action 的说明。例如云服务器的查询实例列表接口,取值为 DescribeInstances。
Region String - 地域参数,用来标识希望操作哪个地域的数据。接口接受的地域取值参考接口文档中输入参数公共参数 Region 的说明。注意:某些接口不需要传递该参数,接口文档中会对此特别说明,此时即使传递该参数也不会生效。
Timestamp Integer 当前 UNIX 时间戳,可记录发起 API 请求的时间。例如1529223702,如果与当前时间相差过大,会引起签名过期错误。
Nonce Integer 随机正整数,与 Timestamp 联合起来,用于防止重放攻击。
SecretId String 云API密钥 上申请的标识身份的 SecretId,一个 SecretId 对应唯一的 SecretKey ,而 SecretKey 会用来生成请求签名 Signature。
Signature String 请求签名,用来验证此次请求的合法性,需要用户根据实际的输入参数计算得出。具体计算方法参见 文档
Version String 操作的 API 的版本。取值参考接口文档中入参公共参数 Version 的说明。例如云服务器的版本 2017-03-12。
SignatureMethod String 签名方式,目前支持 HmacSHA256 和 HmacSHA1。只有指定此参数为 HmacSHA256 时,才使用 HmacSHA256 算法验证签名,其他情况均使用 HmacSHA1 验证签名。
Token String 安全凭证服务 所颁发的临时安全凭证中的 Token,使用时需要将 SecretId 和 SecretKey 的值替换为临时安全凭证中的 TmpSecretId 和 TmpSecretKey。使用长期密钥时不能设置此 Token 字段。
Language String 指定接口返回的语言,仅部分接口支持此参数。取值:zh-CN,en-US。zh-CN 返回中文,en-US 返回英文。

假设用户想要查询广州地域的云服务器实例列表,其请求结构按照请求 URL、请求头部、请求体示例如下:

HTTP GET 请求结构示例:

https://cvm.tencentcloudapi.com/?Action=DescribeInstances&Version=2017-03-12&SignatureMethod=HmacSHA256&Timestamp=1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d181d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKID********EXAMPLE

Host: cvm.tencentcloudapi.com

HTTP POST 请求结构示例:

https://cvm.tencentcloudapi.com/

Host: cvm.tencentcloudapi.com
Content-Type: application/x-www-form-urlencoded

Action=DescribeInstances&Version=2017-03-12&SignatureMethod=HmacSHA256&Timestamp=1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d181d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKID********EXAMPLE

地域列表

本产品所有接口 Region 字段的可选值如下表所示。如果接口不支持该表中的所有地域,则会在接口文档中单独说明。

地域 取值
华南地区(广州) ap-guangzhou