阿里雲API網關（4）快速入門（開放 API）

網關指南： https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl

網關控制台： https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list

使用二級域名訪問我開放的api

http://66bc382db8344b3b93056c696fab49a8-cn-hangzhou.alicloudapi.com/LsqGrp1/LsqApi1?access_token=2689594c-ca7e-4b54-a20a-43b538f2b3c7

一、創建api分組

API 分組是 API 的管理單元，先創建 API 分組，然后在分組下創建 API。

• 分組有 Region 屬性，API 選定分組就選定了 Region，不可更改。

• 分組創建時，會綁定一個唯一的二級域名，您可以訪問該二級域名調用該分組下測試中的 API。

• 若要開放 API 服務，您需要為分組綁定獨立域名，獨立域名需要在阿里雲系統備案並且 CNAME 到該分組的二級域名上，用戶訪問獨立域名時會調用該分組下線上的 API。

• 如果您的 API 支持 HTTPS 協議，您還需要為該獨立域名上傳 SSL 證書。

二、綁定域名和證書

域名是綁定在 API 分組上面的，API 網關通過域名來定位到一個唯一的 API 分組，再通過Path+HTTPMethod 確定唯一的 API。

如果您需要開放 API 則需要為分組綁定獨立域名。獨立域名需要滿足以下幾點：

• 獨立域名需要在 阿里雲備案 或者在 阿里雲備案接入。
• 獨立域名要 CNAME 解析到該分組的二級域名上，然后操作綁定。先解析，后綁定，否則綁定操作會報錯。
• 若您需要將其他分組的獨立域名變更到當前分組，需要先變更解析，才能成功綁定。

若該分組下的 API 支持 HTTPS 協議，您還需要為該獨立域名上 SSL 證書。不支持文件上傳，需要填寫證書名稱、內容和私鑰。

三、創建api

API 分組創建完成您就可以創建 API 了，創建 API 是定義 API 請求的過程。您需要在創建中依次定義以下內容：

1. API 的基本信息：分組、API 名稱、API 類型、API 認證方式、描述。
2. API 請求：協議、Method、Path、入參。
3. API 服務：后端服務協議、后端服務 Method、后端服務地址、后端服務 Path、服務超時時間、參數映射、系統參數、常量參數。
4. API 返回結果：返回類型及示例，目前網關對於返回結果不做處理，直接透傳給請求者。后續會支持用戶定制化、格式化的定義返回信息。

至此完成 API 的創建，並且具備開放的條件。操作詳細說明請看 使用手冊（開放API）。

四、發布api

完成 API 創建后，需要進行調試、測試和正式上線 API。

操作步驟：

1.調試

您要把 API 發布到測試環境，然后在 API 網關控制台的調試頁面上調試 API。

調試時，會跳過 APP 鑒權 和 簽名校驗 環節，只是調試 API 的請求鏈路是否正確。

如果您勾選了 Mock，就是把返回結果定義為一個常量，然后調試時不會真的去請求后端服務，而會直接返回常量結果。這種 Mock 調試模式，不要求后端服務完備。

如果未勾選 Mock，則網關會真實地請求后端服務。返回信息里可能有網關的 X-Ca 開頭的返回信息，也會有底層服務真實返回的信息。

2.測試

為了模擬真實的用戶請求，您可以自己創建一個 APP，操作您的 API 給這個 APP 授權。

然后按照真實的請求場景，寫代碼或者基於網關提供的 SDK 樣例 請求 API。

您可以將 API 發布到測試或者線上環境，在綁定獨立域名之前，可以直接訪問二級域名來進行測試調用。請求時注意指定環境，若不指定則默認為訪問線上。參見 API 調用示例。

調用API的方法，請您查看 使用手冊（調用 API）。

3.發布

完成測試后，您就可以把 API 開放出去了。

要上架到 API 市場則必須將 API 發布到線上，且 API 的類型應為公開。

對外開放的 API，應在所屬分組上綁定獨立域名，直接訪問二級域名有流控限制為1000次/天。

API 網關支持對測試/線上的 API 做版本管理，您可以發布 API、下線 API 還可以切換版本，切換版本是實時生效。

五、授權給應用

應用（APP）代表請求者的身份。當您的客戶或者您自己測試調用 API 時，都需要創建 APP 作為請求者的身份，然后由您操作給 APP 授權。

• 如果您的 API 已經上架雲市場，購買者能夠給自己的 APP 授權，不需要您再配置。

• 無購買行為時的授權操作需要以下幾個步驟：

  1. 獲知待授權的 APP 的 AppID 或者 APP 所有者的阿里雲郵箱賬號。
  2. 在授權操作頁面，選擇一個或者多個准備開放調用權限的 API，選定 測試/線上。
  3. 選定 API 后，用 AppID 或者阿里雲郵箱賬號搜索到 APP。
  4. 確認授權。

注意：授權是區分環境的，同一個API、同一個APP，在兩個環境需要分別授權，避免因為授權的環境和請求的環境不一致，導致報錯。

六、安全服務

接下來您可以配置安全防護設置。目前 API 網關為您提供后端服務簽名密鑰和流量控制策略兩種安全措施。

• 后端服務簽名密鑰主要是用於您后端驗證網關的身份，在網關請求您后端時，保障您后端的安全。

  簽名密鑰的 Key 和 Secret 都是您自定義的，您將創建的密鑰綁定到 API 上后，相當於網關請求這個 API 時需要出示這一對 Key 和 Secret，您后端通過驗證簽名字符串來驗證網關的身份。具體后端簽名密鑰的說明請參見 后端簽名密鑰說明文檔。

• 流量控制策略用於您管控 API 服務的流量，詳見 流量控制策略。

• 您還可以在控制台進行更多 API 生命周期的管理操作，如 API 下線、API 版本切換、API調 用情況監控和預警等。更多詳情請您查看 使用手冊（開放API）。

七、附錄

1、后端簽名秘鑰說明文檔

概述

• API 網關提供后端 HTTP 服務簽名驗證功能，創建簽名密鑰並將簽名密鑰綁定到 API 即可開啟后端簽名（請妥善保管此密鑰，API 網關會對密鑰進行加密存儲來保障密鑰的安全性）。
• 開啟后端簽名后 API 網關到后端HTTP服務的請求將會添加簽名信息，后端 HTTP 服務讀取 API 網關的簽名字符串，然后對收到的請求進行本地簽名計算，比對網關與本地簽名結果是否一致。
• 所有您定義的參數都會參與簽名，包括您錄入的業務參數、您定義的常量系統參數和 API 網關系統參數（如 CaClientIp 等）。
• 后端對 API 網關的簽名字符串校驗后，如果校驗失敗，建議返回 errorcode = 403；errormessage = “InvalidSignature”。
• 若您的后端服務為VPC環境，且通過內網對接（專屬網絡VPC環境開放API），您無需使用后端簽名，通道自身是安全的。

讀取 API 網關簽名方法

網關計算的簽名保存在 Request 的 Header 中，Header 名稱：X-Ca-Proxy-Signature

后端 HTTP 服務加簽方法

簽名計算的詳細 demo（JAVA）請參照鏈接：https://github.com/aliyun/api-gateway-demo-sign-backend-java。

簽名計算方法步驟如下：

組織參與加簽的數據

1. String stringToSign=
2. HTTPMethod + "\n" + //Method全大寫
3. Content-MD5 + "\n" + //Content-MD5 需要判斷是否為空，如果為空則跳過，但是為空也需要添加換行符 "\n"
4. Headers + //Headers 如果為空不需要添加"\n"，不為空的Headers中包含了"\n"，詳見下面組織Headers的描述
5. Url

計算簽名

1. Mac hmacSha256 = Mac.getInstance("HmacSHA256");
2. byte[] keyBytes = secret.getBytes("UTF-8");
3. hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
4. String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

secret 為綁定到 API 上的簽名密鑰

補充說明

• Content-MD5

  Content-MD5 是指 Body 的 MD5 值，只有 HttpMethod 為 PUT 或者 POST 且 Body 為非 Form 表單時才計算 MD5，計算方式為：

  String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes(“UTF-8”)));

• Headers

  Headers 指所有參與簽名計算的 Header的Key、Value。參與簽名計算的 Header 的 Key 從 Request Header 中讀取，Key為：”X-Ca-Proxy-Signature-Headers”，多個 Key 用英文逗號分割。

• Headers 組織方法：

  先對所有參與簽名計算的 Header 的 Key 按照字典排序，然后將 Header 的 Key 轉換成小寫后按照如下方式拼接：

  String headers = HeaderKey1.toLowerCase() + “:” + HeaderValue1 + “\n”+ HeaderKey2.toLowerCase() + “:” + HeaderValue2 + “\n”+ … HeaderKeyN.toLowerCase() + “:” + HeaderValueN + “\n”

• Url

  Url指 Path+Query+Body 中 Form 參數，組織方法：如果有 Query 或 Form 參數則加 ?，然后對 Query+Form 參數按照字典對 Key 進行排序后按照如下方法拼接，如果沒有 Query 或 Form 參數，則 Url = Path

1. String url =
2. Path +
3. "?" +
4. Key1 + "=" + Value1 +
5. "&" + Key2 + "=" + Value2 +
6. ...
7. "&" + KeyN + "=" + ValueN
8. 注意:這里 Query 或 Form 參數的 Value 可能有多個，多個的時候只取第一個 Value 參與簽名計算

• 調試模式

  為了方便后端簽名接入與調試，可以開啟 Debug 模式進行調試，具體方法如下：

  1. 請求API網關的 Header 中添加 X-Ca-Request-Mode = debug

  2. 后端服務在 Header 中讀取 X-Ca-Proxy-Signature-String-To-Sign 即可，因為 HTTP Header 中值不允許有換行符，因此換行符被替換成了 “|”。

     注意：X-Ca-Proxy-Signature-String-To-Sign 不參與后端簽名計算。

• 時間戳校驗

  如果后端需要對請求進行時間戳校驗，可以在 API 定義中選擇系統參數 “CaRequestHandleTime” ，值為網關收到請求的格林威治時間。

2、流量控制策略

流量控制策略和 API 分別是獨立管理的，操作兩者綁定后，流控策略才會對已綁定的 API 起作用。

在已有的流量控制策略上，可以額外配置特殊用戶和特殊應用（APP），這些特例也是針對當前策略已綁定的API生效。

流量控制策略可以配置對 API、用戶、應用三個對象的流控值，流控的單位可以是分鍾、小時、天。使用流量控制策略您需要了解以下幾點：

• 流量控制策略可以涵蓋下表中的維度：

  API 流量限制	該策略綁定的API在單位時間內被調用的次數不能超過設定值，單位時間可選分鍾、小時、天，如5000次/分鍾。
  APP 流量限制	每個APP對該策略綁定的任何一個API在單位時間內的調用次數不能超過設定值。如50000次/小時。
  用戶流量限制	每個阿里雲賬號對該策略綁定的任何一個 API 在單位時間內的調用次數不能超過設定值。一個阿里雲賬號可能有多個 APP，所以對阿里雲賬號的流量限制就是對該賬號下所有 APP 的流量總和的限制。如 50 萬次/天。

  此外，您可以在流控策略下添加特殊應用（APP）和特殊用戶。對於特例，流控策略基礎的 API 流量限制 依然有效，您需要額外設定一個閾值作為該 APP 或者該用戶的流量限制值，該值不能超過策略的 API流量限制 值，同時流控策略基礎的 APP流量限制 和 用戶流量限制 對該 APP 或用戶失效。

• 與簽名密鑰相似，當您創建流量控制策略時，需要選擇 Region，Region 一旦選定不可更改，且僅能被應用於同一個 Region 下的 API。

• 由於 API 網關限制，當您設置 API 流量限制 值時，考慮每個 API 分組的默認流控上限是500QPS（該值可以通過提交工單申請提高）。

• 綁定 API。您可以將策略綁定於多個 API，流控策略的限制值和特例將對該策略綁定的每一個 API 單獨生效。當您綁定 API 時，如果該 API 已經與某個策略綁定，您的此次操作將替換之前的策略，實時生效。

• 特殊對象。如果您想要添加特殊應用或者特殊用戶，您需要獲得應用 ID 即 AppID 或者用戶的阿里雲郵箱賬號。

• 在 API 網關控制台，您可以完成對流量控制策略的創建、修改、刪除、查看等基本操作。還有流控策略與 API 的綁定解綁，流量控制策略特殊對象的添加刪除等操作。