V2版本ROA風格請求體&簽名機制
本文介紹了阿里云 OpenAPI 的 ROA風格接口，包括ROA OpenAPI 請求的組成部分，如何通過這些組成部分構造一個 OpenAPI 請求，如何獲取返回結果以及簽名機制等。阿里云 ROA OpenAPI 向開發者提供HTTP接口，如果您想要自研阿里云ROA調用風格的OpenAPI SDK，您可以參看本文，來構造 HTTP 請求調用對應的 OpenAPI 。
不再推薦使用該訪問方式，請移步參考V3版本請求體&簽名機制。
HTTP 請求結構
一個完整的阿里云 OpenAPI 請求，包含以下部分。
名稱 | 是否必選 | 描述 | 示例值 |
協議 | 是 | 您可以查閱不同云產品的 API 參考文檔進行配置。支持通過 | https:// |
服務地址 | 是 | 即 Endpoint。您可以查閱不同云產品的服務接入地址文檔，查閱不同服務區域下的服務地址。 | cs.aliyuncs.com |
resource_URI_parameters | 是 | 接口URL，包括接口路徑和位置在 path、 query的接口請求參數。 | /clusters/{cluster_id}/triggers |
RequestHeader | 是 | 請求頭信息，通常包含API的版本、Host、Authorization等信息。后文將詳細說明，請參見RequestHeader（請求頭） | x-acs-action |
RequestBody | 是 | 定義在 body 中的業務請求參數，建議您在阿里云 OpenAPI 開發者門戶進行試用。 | cluster_id |
HTTPMethod | 是 | 請求使用的方法，ROA接口請求方法包括PUT、POST、GET、DELETE。 | POST |
RequestHeader（請求頭）
一個完整的阿里云 OpenAPI 請求，包含以下部分。
名稱 | 類型 | 是否必選 | 描述 | 示例值 |
x-acs-action | String | 是 | API的名稱。您可以訪問阿里云 OpenAPI 開發者門戶，搜索您想調用的 OpenAPI | CreateTrigger |
x-acs-version | String | 是 | API 版本。您可以訪問阿里云 OpenAPI 開發者門戶，查看您調用 OpenAPI 對應的 API 版本 | 2015-12-15 |
Accept | String | 否 | 指定接口返回數據的格式。ROA 只支持固定值 | application/json |
Authorization | String | 非匿名請求必須 | 用于驗證請求合法性的認證信息，格式為 Signature為請求簽名，取值參見簽名機制。 | acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY= |
x-acs-signature-nonce | String | 否 | 簽名唯一隨機數。用于防止網絡重放攻擊，建議您每一次請求都使用不同的隨機數。 | 15215528852396 |
Date | String | 是 | 當前時間戳，有效期為15分鐘，即生成時間戳后需要在15分鐘內發起請求。HTTP 1.1協議中規定的 GMT 時間，例如：Tue 9 Apr 2019 07:35:29 GMT。 | Tue 9 Apr 2022 07:35:29 GMT |
x-acs-signature-method | String | 非匿名請求必須 | 簽名方式。目前為固定值 | HMAC-SHA1 |
Content-MD5 | String | 否 | HTTP請求正文的128-bit MD5散列值轉換成BASE64編碼的結果。 | Gtl/0jNYHf8t9Lq8Xlpaqw== |
Host | String | 是 | 即服務地址，參見HTTP 請求結構。 | cs.aliyuncs.com |
接口請求構造
一個完整的接口請求構造如下：
HTTPMethod /resource_URI_parameters
RequestHeader
RequestBody請求參數由公共請求頭和API自定義參數組成。公共請求頭中包含API版本號、身份驗證等信息。
HTTPMethod ：請求使用的方法，包括PUT、POST、GET、DELETE。詳情請參看HTTP 請求結構。
resource_URI_parameters：請求要調用的資源標識符，如
/cluster。詳情請參看HTTP 請求結構。RequestHeader：請求頭信息，通常包含API的版本、Host、Authorization等信息。詳情請參看HTTP 請求結構。
RequestBody：在 body 中的業務請求參數。詳情請參看HTTP 請求結構。
示例：
POST /clusters/test_cluster_id/triggers HTTP/1.1
{
"x-acs-action":"CreateTrigger",
"x-acs-version":"2015-12-15",
"Accept":"application/json",
"Authorization": "acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=",
"x-acs-signature-nonce":"15215528852396",
"Date":"Tue 9 Apr 2022 07:35:29 GMT",
"x-acs-signature-method":"HMAC-SHA1",
"Content-MD5":"Gtl/0jNYHf8t9Lq8Xlpaqw=="
"Host":"cs.aliyuncs.com"
}
{
"cluster_id":"test_cluster_id",
"project_id":"default/nginx-test",
"action":"redeploy",
"type":"deployment"
}請求編碼
請求及返回結果都使用UTF-8字符集進行編碼。
接口返回結果
每次接口調用請求，無論成功與否，系統都會返回一個唯一識別碼RequestId。調用API服務后返回數據采用統一格式。接口調用成功后，會返回接口的返回參數請求 ID，HTTP 狀態碼為 2xx（不顯示在響應正文中）。響應正文示例如下：
{
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216"/* 返回結果數據 */
}接口調用出錯后，會返回請求ID、服務節點、錯誤碼和錯誤信息，HTTP 狀態碼為 4xx 或者 5xx。示例如下：
{
"code": "400", /* 錯誤碼 */
"message": "Cluster permission denied", /* 錯誤信息 */
"requestId": "A026BC61-0523-5A6D-A5F3-314A3D92FD50", /* 請求 ID */
"status": 400 /* 業務字段 */
}接口調用出錯后，您可以根據返回的RequestId，在阿里云OpenAPI開發者門戶-診斷中排查。此外，您還可以查閱公共錯誤碼以及API 錯誤中心。當您無法排查錯誤時，可以提交工單，并在工單中注明Host（服務地址，參見HTTP 請求結構）和RequestId。
簽名機制
為保證API的安全調用，在調用API時阿里云會對每個API請求通過簽名（Signature）進行身份驗證。無論使用HTTP還是HTTPS協議提交請求，都需要在請求中包含簽名信息。本文指導您如何進行簽名處理。
對于每一次HTTP或者HTTPS協議請求，阿里云會根據訪問中的簽名信息驗證訪問請求者身份。您在訪問時簽名信息時，請按照以下方法對請求進行簽名處理：
步驟一：構造規范化請求頭
阿里云規范化請求頭（CanonicalizedHeaders）是非標準HTTP頭部信息。是指請求中出現的以x-acs-為前綴的參數信息，構造方法如下：
將所有以
x-acs-為前綴的HTTP請求頭的名稱轉換成小寫字母。如X-acs-Meta-Name: TaoBao轉換成x-acs-meta-name: TaoBao。阿里云規范請求頭的名稱大小寫不敏感，建議全小寫。如果一個公共請求頭的值過長，則需要處理其中的
\t、\n、\r、\f分隔符，將其替換成英文半角的空格。將上一步得到的所有HTTP阿里云規范頭按照字典順序進行升序排列。
刪除請求頭的名稱和值之間的分隔符兩端出現的任何空格。例如
x-acs-oss-meta-name :TaoBao,Alipay轉換成x-acs-oss-meta-name:TaoBao,Alipay。在每一個請求頭后添加一個
\n分隔符（包括最后一個請求頭），然后將所有請求頭拼接在一起即獲得CanonicalizedHeaders。
步驟二：構造規范化資源
規范化資源（CanonicalizedResource） 表示您想要訪問資源的規范描述，具體構造方式如下：
將請求的查詢字符串（queryString）中的參數按照參數名稱的字典序重新排序，并以
&分隔符連接生成已排序查詢字符串。將請求資源路徑（指URL中host與查詢字符串之間的部分，包含host之后的
/但不包含查詢字符串前的?）與已排序查詢字符串以?拼接，得到規范化資源。當查詢字符串不存在時，直接用請求資源路徑作為規范化資源。
示例
原始請求URL：
http://demo-product.aliyuncs.com/instances?status=ONLINE&group=test_group規范化資源：
/instances?group=test_group&status=ONLINE步驟三：構造待簽名字符串
按照以下偽代碼構造待簽名字符串（stringToSign）：
String stringToSign =
HTTPMethod + "\n" +
Accept + "\n" +
ContentMD5 + "\n" +
ContentType + "\n" +
Date + "\n" +
CanonicalizedHeaders +
CanonicalizedResource參數 | 描述 |
HTTPMethod | 大寫的HTTP方法名，例如POST、GET。 |
Accept | Accept請求頭的值，當請求頭不存在時，使用空字符串代替。 |
ContentMD5 | Content-MD5請求頭的值，當請求頭不存在時，使用空字符串代替。 |
ContentType | Content-Type請求頭的值，當請求頭不存在時，使用空字符串代替。 |
Date | Date請求頭的值。 |
CanonicalizedHeaders | 步驟一：構造規范化請求頭中獲得的規范化請求頭。 |
CanonicalizedResource | 步驟二：構造規范化資源中獲得的規范化資源。 |
步驟四：計算簽名
根據RFC2104的定義，按照HMAC-SHA1算法對上一步生成的待簽名字符串進行簽名計算，并以Base64編碼規則將計算結果編碼成字符串，即得到最終的簽名值（signature）。
String signature = Base64(HMAC_SHA1(SigningKey, stringToSign))計算簽名時使用的SigningKey值就是您的AccessKey Secret。更多信息，請參見創建AccessKey。
步驟五：將簽名添加到請求中
計算出簽名結果 signature后，按照以下規則拼接字符串，并將結果作為 Authorization 請求頭的值。
String Authorization = "acs " + AccessKeyId + ":" + signature簽名示例
本示例以調用 容器服務Kubernetes版（CS） CreateTrigger為應用創建觸發器為例。假設您獲得了AccessKeyID 為 testid， AccessKeySecret 為 testsecret，x-acs-signature-nonce 為 15215528852396，Date 為 Tue 9 Apr 2022 07:35:29 GMT。簽名流程如下：
構造規范化請求頭。
x-acs-signature-method:HMAC-SHA1
x-acs-signature-nonce:15215528852396
x-acs-signature-version:1.0
x-acs-version:2015-12-15構造規范化資源。
/clusters/test_cluster_id/triggers構造待簽名字符串。
POST
application/json
Gtl/0jNYHf8t9Lq8Xlpaqw==
application/json
Tue 9 Apr 2022 07:35:29 GMT
x-acs-signature-method:HMAC-SHA1
x-acs-signature-nonce:15215528852396
x-acs-signature-version:1.0
x-acs-version:2015-12-15
/clusters/test_cluster_id/triggers計算簽名。
acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=將簽名添加到請求中。
POST /clusters/test_cluster_id/triggers HTTP/1.1
/* headers */
{
"accept": "application/json",
"date": "Tue 9 Apr 2022 07:35:29 GMT",
"host": "cs.cn-hangzhou.aliyuncs.com",
"x-acs-signature-nonce": "15215528852396",
"x-acs-signature-method": "HMAC-SHA1",
"x-acs-signature-version": "1.0",
"x-acs-version": "2015-12-15",
"content-type": "application/json",
"content-md5": "Gtl/0jNYHf8t9Lq8Xlpaqw==",
"authorization": "acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY="
}
/* body */
{
"project_id": "default/nginx-test",
"cluster_id": "test_cluster_id",
"action": "redeploy",
"type": "deployment"
}