公共參數(shù)
本文主要介紹了管控API的公共參數(shù)。
公共參數(shù)包括兩個部分:公共請求參數(shù)與公共返回參數(shù)。
公共請求參數(shù):每個接口都需要使用的請求參數(shù)。
公共返回參數(shù):任何的接口調(diào)用,無論成功與否,系統(tǒng)都會返回的參數(shù)。
公共請求參數(shù)
TSDB OpenAPI所有的公共請求參數(shù)如下表所示:
名稱 | 類型 | 是否必須 | 描述 |
---|---|---|---|
Format | String | 否 | 返回值的類型,支持 JSON與XML。 |
Action | String | 是 | 調(diào)用接口名稱。 |
Version | String | 是 | API版本號,為日期形式:YYYY-MM-DD。當(dāng)前版本為2017-06-01。 |
AccessKeyId | String | 是 | 阿里云頒發(fā)給用戶的訪問服務(wù)所用的密鑰ID。 |
SignatureMethod | string | 是 | 簽名方式,目前支持HMAC-SHA1。 |
Timestamp | String | 是 | 請求的時間戳。日期格式按照ISO8601標(biāo)準(zhǔn)表示,并需要使用UTC 時間。格式為:YYYY-MM-DDThh:mm:ssZ。例如,2013-08-15T12:00:00Z(為北京時間2013年1月10日20點(diǎn)0分0秒)。 |
SignatureVersion | String | 是 | 簽名算法版本,目前版本是1.0。 |
SignatureNonce | String | 是 | 唯一隨機(jī)數(shù),用于防止網(wǎng)絡(luò)重放攻擊。用戶在不同請求間要使用不同的隨機(jī)數(shù)值。 |
RegionId | String | 是 | TSDB實(shí)例所在的地域。 |
Signature | String | 是 | 簽名結(jié)果串。關(guān)于簽名的計算方法,請參見簽名機(jī)制。 |
公共返回參數(shù)
TSDB OpenAPI 的公共返回參數(shù):唯一識別碼RequestId
。
RequestId
標(biāo)識了用戶的每一次API調(diào)用請求,用于API方面的問題排查。
RequestId的示例(XML 格式)
<?xml version="1.0" encoding="utf-8"?>
<!—結(jié)果的根結(jié)點(diǎn)-->
<接口名稱+Response>
<!—返回請求標(biāo)簽-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—返回結(jié)果數(shù)據(jù)-->
...
</接口名稱+Response>
返回結(jié)果
調(diào)用API服務(wù)后返回數(shù)據(jù)采用統(tǒng)一格式:
返回的 HTTP 狀態(tài)碼為2xx,代表調(diào)用成功;
返回的 HTTP 狀態(tài)碼為4xx或 5xx,代表調(diào)用失敗。
調(diào)用成功返回的數(shù)據(jù)格式主要有XML和JSON 兩種,外部系統(tǒng)可以在請求時傳入?yún)?shù)來制定返回的數(shù)據(jù)格式,推薦使用JSON格式。
為了便于查看,本文中的返回示例做了格式化處理。實(shí)際返回結(jié)果是沒有進(jìn)行換行、縮進(jìn)等處理的。
成功的返回結(jié)果
結(jié)果包括請求是否成功信息和具體的業(yè)務(wù)數(shù)據(jù)。
XML
<?xml version="1.0" encoding="utf-8"?>
<!—結(jié)果的根結(jié)點(diǎn)-->
<接口名稱+Response>
<!—返回請求標(biāo)簽-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—返回結(jié)果數(shù)據(jù)-->
...
</接口名稱+Response>
JSON
{
/* 返回的請求 ID */
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
/* 返回結(jié)果數(shù)據(jù) */
...
}
錯誤的返回結(jié)果
調(diào)用接口出錯后,將不會返回結(jié)果數(shù)據(jù)。調(diào)用方可根據(jù)錯誤代碼表來定位錯誤原因。
當(dāng)調(diào)用出錯時,HTTP 請求會返回4個信息:
一個4xx或5xx的HTTP狀態(tài)碼;
具體的錯誤代碼及錯誤信息;
一個全局唯一的請求ID;
一個您該次請求訪問的站點(diǎn)ID:HostId。
如果根據(jù)API的返回信息找不到錯誤原因,可以聯(lián)系阿里云客服,并提供該HostId和RequestId,以方便TSDB工作人員盡快解決問題。
XML
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<RequestId>8906582E-6722-409AA6C4-0E7863B733A5</RequestId>
<HostId>hitsdb.aliyuncs.com</HostId>
<Code>UnsupportedOperation</Code>
<Message>The specified action is not supported.</Message>
</Error>
JSON
{
"RequestId": "7463B73D-35CC-4D19-A010-6B8D65D242EF",
"HostId": "hitsdb.aliyuncs.com",
"Code": "UnsupportedOperation",
"Message": "The specified action is not supported."
}