快速上手ROA風格請求體和簽名機制 - Alibaba Cloud SDK

本文介紹了阿里雲 OpenAPI 的 ROA風格介面，包括ROA OpenAPI 請求的組成部分，如何通過這些組成部分構造一個 OpenAPI 請求，如何擷取返回結果以及簽名機制等。阿里雲 ROA OpenAPI 向開發人員提供HTTP介面，如果您想要自研阿里雲ROA調用風格的OpenAPI SDK，您可以參看本文，來構造 HTTP 要求調用對應的 OpenAPI 。

重要

不再推薦使用該訪問方式，請移步參考V3版本請求體&簽名機制。

HTTP 要求結構

一個完整的阿里雲 OpenAPI 請求，包含以下部分。

名稱	是否必選	描述	樣本值
協議	是	您可以查閱不同雲產品的 API 參考文檔進行配置。支援通過`HTTP`或`HTTPS`協議進行請求通訊。為了獲得更高的安全性，推薦您使用HTTPS協議發送請求。取值範圍為`https://`或者 `http://`。	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`	application/json
Authorization	String	非匿名請求必須	用於驗證請求合法性的認證資訊，格式為`AccessKeyId:Signature`。其中AccessKeyId 為使用者的存取金鑰ID。您可以在RAM 控制台查看您的 AccessKeyId。如需建立 AccessKey，請參見建立AccessKey。 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`。	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要求標頭的值，當要求標頭不存在時，使用Null 字元串代替。
ContentMD5	Content-MD5要求標頭的值，當要求標頭不存在時，使用Null 字元串代替。
ContentType	Content-Type要求標頭的值，當要求標頭不存在時，使用Null 字元串代替。
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

簽名樣本

本樣本以調用 Container ServiceKubernetes版（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"
}

Alibaba Cloud SDK：V2版本ROA風格請求體&簽名機制