公共參數包括兩個部分：公共請求參數與公共返回參數。

  • 公共請求參數：每個接口都需要使用的請求參數。
  • 公共返回參數：任何的接口調用，無論成功與否，系統都會返回的參數。

公共請求參數如下表所示：

名稱 類型 是否必須 描述
Format String 否 返回值的類型，支持JSON與XML。
Action String 是 調用接口名稱。
Version String 是 API版本號，為日期形式：YYYY-MM-DD，當前版本對應為2017-10-16。
AccessKeyId String 是 阿里云頒發給用戶的訪問服務所用的密鑰ID。
SignatureMethod string 是 簽名方式，目前支持HMAC-SHA1。
Timestamp String 是 請求的時間戳。日期格式按照ISO8601標準表示，并需要使用UTC時間。格式為：YYYY-MM-DDThh:mm:ssZ。 例如，2013-08-15T12:00:00Z（為北京時間2013年8月15日20點0分0秒）。
SignatureVersion String 是 簽名算法版本，目前版本是1.0。
SignatureNonce String 是 唯一隨機數，用于防止網絡重放攻擊。用戶在不同請求間要使用不同的隨機數值。
RegionId String 是 PolarDB-X 1.0所在的地域。
Signature String 是 簽名結果串。

公共返回參數

PolarDB-X 1.0 OpenAPI的公共返回參數：唯一識別碼RequestId。RequestId標識了用戶的每一次API調用請求，用于API方面的問題排查。

RequestId的示例（XML格式）

<?xml version="1.0" encoding="utf-8"?> 
<!—結果的根結點-->
<接口名稱+Response>

    <!—返回請求標簽-->
    <RequestId>
        4C467B38-3910-447D-87BC-AC049166F216
    </RequestId>

    <!—返回結果數據-->
    ...
</接口名稱+Response>

返回結果

調用API服務后返回數據采用統一格式：

  • 返回的HTTP狀態碼為2xx，代表調用成功；
  • 返回4xx或5xx的HTTP狀態碼代表調用失敗。

調用成功返回的數據格式主要有XML和JSON兩種，外部系統可以在請求時傳入參數來制定返回的數據格式，推薦使用JSON格式。

為了便于查看，本文中的返回示例做了格式化處理。實際返回結果是沒有進行換行、縮進等處理的。

成功的返回結果

結果包括請求是否成功信息和具體的業務數據。

XML

<?xml version="1.0" encoding="utf-8"?> 
<!—結果的根結點-->
<接口名稱+Response>

    <!—返回請求標簽-->
    <RequestId>
        4C467B38-3910-447D-87BC-AC049166F216
    </RequestId>

    <!—返回結果數據-->
    ...
</接口名稱+Response>

JSON

{

    <!—返回的請求 ID-->
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",

    /* 返回結果數據 */
    ...

}

錯誤的返回結果

調用接口出錯后，將不會返回結果數據。調用方可根據錯誤代碼表來定位錯誤原因。

當調用出錯時，HTTP請求會返回4個信息：

  • 一個4xx或5xx的HTTP狀態碼；

  • 具體的錯誤代碼及錯誤信息；

  • 一個全局唯一的請求ID；

  • 一個您該次請求訪問的站點ID：HostId。

如果根據API的返回信息找不到錯誤原因，可以聯系阿里云客服，并提供該HostId和RequestId，以方便PolarDB-X 1.0工作人員盡快解決問題。

XML

<?xml version="1.0" encoding="UTF-8"?>
<Error>
       <RequestId>8906582E-6722-409AA6C4-0E7863B733A5</RequestId>
       <HostId>drds.aliyuncs.com</HostId>
       <Code>UnsupportedOperation</Code>
       <Message>The specified action is not supported.</Message>
</Error>

JSON

{
    "RequestId": "7463B73D-35CC-4D19-A010-6B8D65D242EF",
    "HostId": "rds.aliyuncs.com",
    "Code": "UnsupportedOperation",
    "Message": "The specified action is not supported."
}