阿里雲API網關（6）用戶指南（開放 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 網關（API Gateway），提供高性能、高可用的API托管服務，幫助您對外開放您部署在ECS、容器服務等阿里雲產品上的應用，為您提供完整的API發布、管理、維護生命周期管理。您只需簡單操作，即可快速、低成本、低風險的開放數據或服務。

在 API 網關您可以：

• 管理您的 API

  您可以對API的整個生命周期進行管理，包括API的創建、測試、發布、下線、版本切換等操作。

• 便捷轉換數據

  支持自定義映射規則，您可以配置映射將調用請求轉換成后端需要的格式。

• 預設請求校驗

  您可以預先設置參數類型、參數值（范圍、枚舉、正則、Json Schema）校驗，由網關幫助您過濾掉非法請求，減少您的后端對非法請求的處理成本。

• 靈活控制流量

  您可以對API、用戶、應用設置按分鍾、小時、天的調用量控制。您還可以設置特例用戶或者應用，對某個用戶或應用單獨配置流量控制。

• 輕松安全防護

  支持 Appkey 認證，HMAC（SHA-1,SHA-256）算法簽名。

  支持 SSL/TSL 加密，並借助阿里雲盾防病毒、防攻擊。

• 全面監控與報警

  為您提供可視化 API 實時監控，包括：調用量、調用方式、響應時間、錯誤率，並支持歷史情況查詢，以便統籌分析。您還可以配置預警方式（短信、Email）,訂閱預警信息，以便實時掌握 API 運行情況。

• 降低開放成本

  為您自動生成 API 文檔和 SDK（服務端、移動端），降低 API 開放成本。

二、創建api

API 創建

更新時間：2017-07-05 14:50:55   分享：   

創建 API 即在 API 網關錄入 API 的定義。您需要定義 API 的基本信息、服務信息、請求信息、返回信息。

• 網關支持您配置對入參的預校驗規則，讓網關成為您后端服務的第一道關卡。
• 網關支持您配置前端和后端的全映射，即參數混排。如您可以讓您的用戶在 Query 傳入參數，但是您后端從 Header 里接收，等等。以滿足您需要將服務包裝變形輸出。
• 網關支持您配置常量參數、系統參數，這些參數對您的用戶不可見，但是網關可以在中轉時將常量參數、系統參數加入請求中，傳遞至后端服務，滿足您后端的一些業務需求。比如您需要網關每次向您發送請求都帶有一個 keyword aligateway，您就可以把 aligateway 配置為常量參數，並指定接收的位置。

第一部分：定義請求的基本信息

API 基本信息包括 API 分組、 API 名稱、安全認證方式、 API 類型、描述。

• API 創建時需要選擇分組。分組是 API 的管理單元，創建 API 之前您需要先創建分組（ API 分組的詳細說明見 API 開放），選擇分組即選擇 Region。

• 安全認證方式：是 API 請求的認證方式，目前支持 阿里雲APP、OpenID Connect 和 無認證 三種認證方式。

  1. 阿里雲APP：認證方式即要求請求者調用該 API 時能夠通過對APP的身份認證。
  2. OpenID Connect：是一套基於 OAuth 2.0 協議的輕量級規范，提供通過RESTful APIs 進行身份交互的框架。可以使用OpenID Connect和您的自有賬號系統無縫對接，詳細介紹請參照 OpenID Connect。
  3. 無認證：認證方式即任何人知曉該 API 的請求定義后，均可發起請求，網關不對其做身份驗證，均會轉發至您后端服務。

• API 類型分為公開和私有兩種。

  1.私有 類型的 API ，當所在分組上架雲市場時，默認不包括該類型的 API 。如果有用戶想要調用您的 API ，您需要主動操作授權，否則用戶無渠道獲取 API 信息。
  2.公開 類型的 API ，所有用戶均有機會在 發現 API 頁面看到 API 的部分信息。公開 類型的 API 都會跟 API 分組上架到雲市場，供用戶購買和調用。

第二部分：定義 API 請求

這部分是定義用戶如何請求您的 API ，包括協議、Method、Path、入參的定義。

• 協議及method。 API 調用支持 HTTP/HTTPS 協議。Method 方法可選擇 PUT、GET、POST、DELETE、HEAD。
• Path。Path 指相對於服務 host， API 的請求路徑。請求 Path 可以與后端服務實際 Path 不同，您可以隨意撰寫合法的有明確語義的 Path 給用戶使用。您可以在請求 Path 中配置動態參數，即要求用戶在 Path 中傳入參數，同時您的后端又可以不在 Path 中接收，可以映射為在 Query、Header 等位置接收。在 開放 API 接入 API 網關 中，有詳細的舉例說明，更有清晰的截圖展示。
• 入參。定義您 API 的請求入參，即配置用戶需要在什么位置傳入什么參數。可選位置有Head、Query、Body、Path（Parameter Path），尤其當您在 Path 中配置了動態參數，那么在入參配置時需要對動態參數做配置說明。支持的參數類型有 String、Number、Boolean。
• 參數校驗規則。每個入參后可點擊 編輯更多 配置校驗規則。如 String 的長度，Number 的枚舉等等。網關會參照校驗規則對請求做初步校驗，如果入參不合法，則不會到達您的后端服務，大大的降低了后端服務的壓力。

第三部分：定義后端服務信息

這部分主要是定義一些參數的前后端映射，具體描述的是您后端真實服務的 API 配置。用戶請求到達網關后，網關會根據您的后端配置映射為對應實際后端服務的請求形式，去請求您的后端。包括后端服務地址、后端Path、后端超時時間、參數映射、常量參數、系統參數。

• 后端服務地址。后端服務的 host，可以是一個域名，也可以是 http(s)://host:port 的形式。
• 后端 Path。Path 是您的 API 服務在您后端服務器上的請求路徑，實際請求路徑。若您后端 Path 需要接收動態參數，那么需要聲明該參數是調用者從哪個位置哪個參數傳入的，即聲明映射關系。
• 后端超時時間。指 API 請求到達網關后，網關去調 API 后端服務的響應時間。由網關請求后端開始到網關收到后端返回結果。該值不能超過30秒。超過該值網關會放棄請求后端服務，並給用戶返回相應的錯誤信息。
• 參數映射。網關支持參數在前端、后端的全映射，包括名稱映射和位置映射。位置映射包括 Path、Header、Query、Body 的混排映射。也就是說，您可以將您的后端服務通過映射完成包裝成更規范、更專業的 API 形態。這部分就是在聲明前后端 API 映射關系的。在 開放 API 接入 API 網關 中，有詳細的舉例說明，更有清晰的截圖展示。注意前后端參數名稱不能重復。
• 常量參數。比如您需要網關每次請求您后端時都帶有標記 apigateway，那么您可以直接將標記配置為常量參數。常量參數對您的用戶不可見，請求達到網關后，網關會自動在指定位置加上該參數再去請求您的后端。

• 系統參數。指 API 網關的系統參數，這些參數默認不會傳遞給您，但是如果您需要獲取，您可以在 API 里配置接收位置和名稱。具體內容如下表：

  參數名稱	參數含義
  CaClientIp	發送請求的客戶端IP
  CaDomain	發送請求的域名
  CaRequestHandleTime	請求時間（格林威治時間）
  CaAppId	請求的APP的ID
  CaRequestId	RequestId
  CaApiName	API 名稱
  CaHttpSchema	用戶調用 API 使用的協議，http或者https
  CaProxy	代理（AliCloudApiGateway）

  注意：您所有錄入的參數，包括 Path 中的動態參數、Headers 參數、Query 參數、Body 參數（非二進制）、常量參數、系統參數，參數名稱保證全局唯一。即如果您同時在 Headers 和 Query 里各有一個名為 name 的參數，是不允許的。

完成以上定義后，您就完成了 API 的創建。下一步您可以發布、測試並開放 API 服務到市場，還可以為 API 綁定簽名密鑰和流量控制等安全配置。 

三、開放api

API 創建完成后，您就可以開放 API 服務了。要開放 API 服務您需要綁定一個在阿里雲系統備案成功的獨立域名，且該域名要完成 CNAME 解析。而獨立域名是綁定在 API 分組上面的，所以在這個部分為您詳細說明一下開放 API 服務需要了解的 API 分組和域名。

第一部分：API 分組

API 分組是 API 的管理單元。您創建 API 之前，需要先創建分組，然后在某個分組下創建 API。分組包含名稱、描述、區域（Region）、域名幾大屬性。

• 分組的區域（Region）在分組創建時選定不可更改。創建 API 時，如果選定分組那么 Region 也一同選定，不可更改。
• 每個賬號 API 分組個數上限為50個，每個分組 API 個數上限為200個。
• 域名。分組創建時，系統會為分組分配一個二級域名。如果需要開放 API 服務，您需要為分組綁定一個在阿里雲系統備案成功的獨立域名，且將獨立域名 CNAME 到相應的二級域名上。每個分組最多只能綁定5個獨立域名。具體請看下文——域名及證書。

第二部分：環境管理

關於環境需要理解兩個概念，環境和環境變量。

• 環境是 API 分組上的一個配置，每個分組有若干個環境。 API 錄入后，未經發布時，就只是 API 定義。發布到某個環境后才是能夠對外提供服務的 API 。

• 環境變量是在環境上用戶可創建可管理的一種變量，該配置是固定於環境上的。如在線上環境創建變量，變量名為 Path，變量值為 /stage/release.

在 API 定義中的 Path 位置，寫作 #Path#，即配置為變量標識，變量名為 Path。

那么將該 API 發布到線上環境時，該 API 在線上環境的運行定義，Path 處的 #Path#，會取值為 /stage/release。

而將該 API 發布到其他環境時，若環境上沒有環境變量 #Path#，則無法取值，那么 API 就無法調用。

使用環境變量可以解決后端服務需要區分環境的問題，通過不同的環境上配置不同的服務地址和Path，來調用不同的后端服務，同時 API 的定義配置又是一套。使用時需要注意以下幾點：

• 在 API 定義中配置了變量標識后，在 API 列表—管理—調試 頁面將無法調試。
• 變量名嚴格區分大小寫。
• 如果在 API 定義中設置了變量，那么一定要在要發布的環境上配置 變量名和變量值，否則變量無賦值， API 將無法正常調用。

第三部分：域名及證書

API 網關通過域名來定位到一個唯一的 API 分組，再通過 Path+HTTPMethod 確定唯一的 API 。如果要開放 API 服務，您需要了解 二級域名 和 獨立域名。

• 二級域名是分組創建時系統分配的，唯一且不可更改。在您還沒有獨立域名之前，您可以通過訪問二級域名來測試調用您的 API 。二級域名僅能用於測試，默認每天只能請求1000次。

• 獨立域名即自定義域名，是您開放 API 服務需要綁定的，用戶通過訪問您的獨立域名來調用您開放的 API 服務。您可以為一個分組綁定多個獨立域名，上限為5個。對於獨立域名的配置您需要注意以下幾點：

  • 獨立域名不必須是根域名，可以是二級、三級域名。

  • 獨立域名如果尚未備案，則可以在阿里雲做 首次備案。

  • 獨立域名若已在其他系統備案，則需要在阿里雲做 備案接入。

  • 獨立域名需要 CNAME 解析到分組的二級域名上。

  • 滿足上述的備案和解析兩個要求，域名才能成功綁定。

• 當您的 API 服務支持 HTTPS 協議時，需要為該域名上傳 SSL 證書，在 分組詳情 頁面進行添加即可。SSL 證書上傳不支持文件上傳，需要填寫 證書名稱、內容 和 私鑰。

第四部分：測試、線上、授權

通過上述操作您已經完成 API 的創建和域名綁定，接下來就可以將 API 發布到測試或者線上環境，進行調試和開放了。其中一個重要的環節是授權，授權即授予某個 APP 可以調用某個 API 的權限。

• 當您完成 API 創建之后，您就可以將 API 發布到測試或者線上，並給自己創建的 APP 授權，通過訪問二級域名來調用指定環境中的 API，進行測試。
• 成功綁定獨立域名之后，您的 API 就可以在市場上架，供客戶購買、調用。您還可以不經過購買將 API 授權給合作伙伴的 APP，供其調用。

至此，您完成 API 服務的開放。在 API 創建到開放的整個過程中，您還可以隨時操作 API 的創建、修改、刪除、查看、測試、發布、下線、授權、解除授權、發布歷史及版本切換等操作。

四、管理API

API 定義就是指您創建 API 時對 API 的請求結構的各方面定義。您可以在控制台完成 API 定義的查看、編輯、刪除、創建、復制。您需要注意以下幾點：

• 當您需要編輯某個 API 的定義時，如果該 API 已經發布，對定義的修改不會對線上產生影響，定義修改后需要再次發布才能把修改后的定義同步到線上環境。
• 當您想要刪除某個 API，如果該 API 已經發布，則不允許直接刪除 API 定義，需要先將 API 下線，然后刪除。
• API 網關為您提供了復制定義的功能。您可以從測試環境/線上環境復制線上的定義覆蓋當前的最新定義，然后重新點擊編輯進行修改。

API 發布管理

當您完成 API 的創建后，您可以將 API 發布到測試或者線上。也可以將測試或者線上的 API 下線。您需要注意以下幾點：

• API 創建完成后，發布到某環境，通過二級域名或者獨立域名訪問時，需要在請求的Header指定要請求的環境，參見 請求示例。
• 當您要發布某個 API 時，如果該 API 在測試或者線上已經有版本在運行，您的此次發布將使測試或者線上的該 API 被覆蓋，實時生效。但是歷史版本及定義會有記錄，您可以快速回滾。
• 您可以將測試或者線上的某個 API 下線，下線之后，與策略、密鑰、 APP 的綁定或者授權關系依然存在，再次上線時會自動生效。如果要解除關系，需要專門操作刪除。

API 授權管理

您的 API 如果上架到市場，那么購買者有權利操作給自己的某個 APP 授權。

如果不經過購買行為，您需要在線下跟合作伙伴建立使用關系，那么您需要通過授權來建立 API 和 APP 的權限關系。您將 API 發布到線上環境后，需要給客戶的 APP 授權，客戶才能用該 APP 進行調用。您有權對此類授權操作建立或者解除某個 API 與某個 APP 的授權關系， API 網關會對權限關系進行驗證。操作授權時，您需要注意以下幾點：

• 您可以將一個或者多個 API 授權給一個或者多個 APP 。批量操作時，建議不要同時操作多個分組下的 API 。
• 批量操作時，先選擇 API 后選擇環境。比如一個 API 在測試和線上均有發布，最后選擇了測試，就只會將測試下的該 API 授權。
• 您可以通過客戶提供給您的AppID或者阿里雲郵箱賬號來定位 APP 。
• 當您需要解除某個 API 下某個 APP 的授權時，您可以查看 API 的授權列表，在列表頁進行解除。

歷史與版本切換

您可以查看您每個 API 的發布歷史記錄，包括每次發布的版本號、說明、環境、時間和具體定義內容。

查看歷史時，您可以選定某個版本然后操作切換到此版本，該操作會使該版本直接在指定環境中替換之前的版本，實時生效。

五、簽名密鑰

什么是簽名密鑰

簽名密鑰是由您創建的一對 Key 和 Secret，相當於您給網關頒發了一個賬號密碼，網關向您后端服務請求時會將密鑰計算后一起傳過去，您后端獲取相應的字符串做對稱計算，就可以對網關做身份驗證。使用時您需要了解以下幾點：

• 創建密鑰時需要選擇 Region，Region 一旦選定不能更改，而且密鑰只能被綁定到同一個 Region 下的API上。
• 一個 API 僅能綁定一個密鑰，密鑰可以被替換和修改，可以與 API 綁定或者解綁。
• 您將密鑰綁定到 API 之后，由網關拋向您服務后端的該 API 的請求均會加上簽名信息。您需要在后端做對稱計算來解析簽名信息，從而驗證網關的身份。具體 HTTP 加簽說明請查看文檔——后端簽名密鑰說明文檔

密鑰泄露 修改替換

當您遇到如下情況：

• 您的某一個密鑰發生了泄露，您可能想要保留該密鑰與 API 的綁定關系，但是想要修改密鑰的 Key 和 Secret。

• 當您操作將密鑰應用於 API 時，可能該 API 已經綁定了某個密鑰，需要替換密鑰。

以上兩種情況都建議按照下面的流程來操作：

1. 先在后端同時支持兩個密鑰：原來的密鑰和即將修改或替換的密鑰，確保切換過程中的請求能夠通過簽名驗證，不受修改或替換的影響。
2. 后端配置完備后，完成修改，確定新 Key 和 Secret 生效后再將之前已泄露或廢棄的密鑰刪除。

六、流量控制策略

流量控制策略和 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 的綁定解綁，流量控制策略特殊對象的添加刪除等操作。

七、監控預警

• API網關為您提供可視化的實時監控和預警。您可以獲得您開放的API被調用數據，包括調用量、流量、響應時間、錯誤分布等多個維度、多種時間單位的數據統計結果。同時支持歷史數據查詢，以便您統籌分析。
• 后續我們會陸續支持報表輸出，給您提供最周到的數據支持。
• 您還可以配置預警，以便實時掌握API運行情況。

八、使用限制

九、專屬VDC環境

 

十、MOCK api

在項目開發過程中，往往是多個合作方一同開發，多個合作方相互依賴，而這種依賴在項目過程中會造成相互制約，理解誤差也會影響開發進度，甚至影響項目的工期。所以在開發過程中，一般都會使用 Mock 來模擬最初預定的返回結果，來降低理解偏差，從而提升開發效率。

API 網關也支持 Mock 模式的簡單配置。

配置 Mock

在 API 編輯頁面——后端基礎定義，來配置 Mock。

1. 選擇 Mock 模式

   可以選擇使用 Mock 或者不使用 Mock，選擇使用 Mock 時會進行二次確認

   

2. 填寫 Mock 返回結果

   Mock 返回結果，可以填寫您真實的返回結果。目前支持是 Json、XMl、文本等格式作為 Mock 返回結果。如

   1. {
   2. "result": {
   3. "title": " API 網關 Mock 測試",
   5. }
   6. }

   保存后 Mock 設置成功，請根據實際需要 發布 到測試或線上環境進行測試，也可以在 API 調試頁面進行調試。

3. 調試

   可以在調試 API 頁面發起 API 調用來測試設置結果：

   

   這表示 Mock 設置成功。

解除 Mock

若您需要解除 Mock，可以將第一幅圖中的 Mock，修改為 不使用 Mock 即可，而 Mock 返回結果中的值不會被清除，以便您進行下一次的 Mock 。修改完成后請 發布，只有發布后才會真正生效。 

十一、以函數計算作為api

函數計算（Function Compute）是一個事件驅動的服務，通過函數計算，用戶無需管理服務器等運行情況，只需編寫代碼並上傳，函數計算准備計算資源，並以彈性伸縮的方式運行用戶代碼。而用戶只需根據實際代碼運行所消耗的資源付費。詳細了解請查看函數計算幫助文檔。

API網關與函數計算對接，可以讓您以API形式開放您的函數，並且解決認證、流量控制、數據轉換等問題(查看API網關功能） ，讓您的函數服務可以安全、簡單的以API形式對外開放。

1 實現原理

API網關調用函數服務時，會將API的相關數據包裝為一個Map形式傳給函數計算服務，函數計算服務處理后，需要按照圖中Output Format的格式返回statusCode，headers，body等相關數據，API gateway再將函數計算返回的內容映射到statusCode，header,body等位置返回給客戶端。

2 快速配置API

配置方法：

2.1 創建函數計算的Function

1）到函數計算控制台創建Service。去往 函數計算控制台。如果您已經創建過Function，可以忽略此步。

2）在剛創建的Service下創建Function，點擊“新建函數”。並輸入您的代碼,詳細操作請參照創建函數。

3）觸發器頁面點擊“跳過” 即可，最后點擊完成。

2.2 配置跨服務授權Role和policy

在此步，您需要將此函數的調用權限授權給API網關。

1）到RAM控制台創建角色，去往RAM控制台。在“角色管理”頁面，點擊“創建角色”。

2) 綁定角色授權策略

該授權策略能訪問賬號下所有的Function。如果想限制授權范圍，可以按照下面步驟新創建自定義策略，然后綁定。

3）創建自定義策略。在“策略管理”頁面，點擊“新建授權策略”。

圖中策略內容為：

1. {
2. "Version": "1",
3. "Statement": [
4. {
5. "Effect": "Allow",
6. "Action": [
7. "fc:InvokeFunction"
8. ],
9. "Resource": [
10. "acs:fc:*:1227466664334133:services/apitest/functions/*"
11. ]
12. }
13. ]
14. }

其中的Resource代表要授權的資源，需要更改為自己賬號下的資源。

• 當限定到某個具體的Function時，格式為 "acs:fc:*:[AccountId]:services/[ServiceName]/functions/[FunctionName]".

• 當要授權某個賬號下的所有Function時，可以為"acs:fc:*:[AccountId]:services/*"

注意:當授權策略為單個Function時，后續更改Function，還需要重新修改該策略或者新增策略。

2.3 配置函數計算作為API后端服務

在API編輯中，在選擇API后端服務時，選擇“FunctionCompute”.

• 區域：函數計算對應的區域，當API和函數計算區域相同時，API通過內網調用函數計算，當區域不一樣時，則走公網。
• RoleArn：因為最終是由API網關去調用函數計算，為跨服務調用，因此需要用戶授權后，API網關才能成功調用。RoleArn為授權角色上的Arn. 可到RAM控制台角色詳情中查看。

3 API網關和函數計算對接的格式要求

3.1 API網關給函數計算的輸入格式

當以函數計算作為API網關的后端服務時，API網關會把請求參數通過一個固定的Map結構傳給函數計算的入參event，函數計算通過如下結構去獲取需要的參數，然后進行處理，該結構如下：

1. {
2. "path":"api request path",
3. "httpMethod":"request method name",
4. "headers":{all headers,including system headers},
5. "queryParameters":{query parameters},
6. "pathParameters":{path parameters},
7. "body":"string of request payload",
8. "isBase64Encoded":"true|false, indicate if the body is Base64-encode"
9. }

需要特別說明的是：當isBase64Encoded=true時，表明API網關傳給函數計算的body內容是經過Base64編碼的，函數計算需要先對body內容進行Base64解碼后再處理。反之，isBase64Encoded=false時，表明API網關沒有對body內容進行Base64編碼。

3.2 函數計算給API網關的輸出格式

同時，函數計算需要將輸出內容通過如下JSON格式返回給API網關，方便API網關解析。

1. {
2. "isBase64Encoded":true|false,
3. "statusCode":httpStatusCode,
4. "headers":{response headers},
5. "body":"..."
6. }

說明：

1) 當body內容為二進制時，需在函數計算中對body內容進行Base64編碼，同時設置isBase64Encoded=true。如果body無需Base64編碼，isBase64Encoded可以設置為false。API網關會對isBase64Encoded=true的body內容進行Base64解碼后再透出給客戶端。

2) 在nodejs版本的函數計算中，callback需要根據不同的情況進行設置。 當返回一個成功的請求， callback{null,{“statusCode”:200,”body”:”…”}}。需要拋一個異常時，callback{new Error(‘internal server error’),null}。當返回一個客戶端錯誤 callback{null,{“statusCode”:400,”body”:”param error”}}。

3) 如果函數計算返回不符合上面的格式要求，API網關將返回503 Service Unavailable給客戶端。

3.3 示例

如在函數計算中配置一個demo程序：

這是一個撞牆式返回程序的代碼示例，會原裝返回您所有的請求內容。

1. module.exports.handler = function(event, context, callback) {
2. var responseCode = 200;
3. console.log("request: " + JSON.stringify(event.toString()));
4. //將event轉化為JSON對象
5. event=JSON.parse(event.toString());
6. var isBase64Encoded=false;
7. //根據用戶輸入的statusCode返回，可用於測試不同statusCode的情況
8. if (event.queryParameters !== null && event.queryParameters !== undefined) {
9. if (event.queryParameters.httpStatus !== undefined && event.queryParameters.httpStatus !== null && event.queryParameters.httpStatus !== "") {
10. console.log("Received http status: " + event.queryParameters.httpStatus);
11. responseCode = event.queryParameters.httpStatus;
12. }
13. }
14. //如果body是Base64編碼的，FC中需要對body內容進行解碼
15. if(event.body!==null&&event.body!==undefined){
16. if(event.isBase64Encoded!==null&&event.isBase64Encoded!==undefined&&event.isBase64Encoded){
17. event.body=new Buffer(event.body,'base64').toString();
18. }
19. }
20. //input是API網關給FC的輸入內容
21. var responseBody = {
22. message: "Hello World!",
23. input: event
24. };
26. //對body內容進行Base64編碼，可根據需要處理
27. var base64EncodeStr=new Buffer(JSON.stringify(responseBody)).toString('base64');
29. //FC給API網關返回的格式，須如下所示。isBase64Encoded根據body是否Base64編碼情況設置
30. var response = {
31. isBase64Encoded:true,
32. statusCode: responseCode,
33. headers: {
34. "x-custom-header" : "header value"
35. },
36. body: base64EncodeStr
37. };
38. console.log("response: " + JSON.stringify(response));
39. callback(null, response);
40. };

以POST form形式請求如下一個API的url, path為：

1. /fc/test/invoke/[type]。

1. POST http://test.alicloudapi.com/fc/test/invoke/test?param1=aaa&param2=bbb
3. "X-Ca-Signature-Headers":"X-Ca-Timestamp,X-Ca-Version,X-Ca-Key,X-Ca-Stage",
4. "X-Ca-Signature":"TnoBldxxRHrFferGlzzkGcQsaezK+ZzySloKqCOsv2U=",
5. "X-Ca-Stage":"RELEASE",
6. "X-Ca-Timestamp":"1496652763510",
7. "Content-Type":"application/x-www-form-urlencoded; charset=utf-8",
8. "X-Ca-Version":"1",
9. "User-Agent":"Apache-HttpClient\/4.1.2 (java 1.6)",
10. "Host":"test.alicloudapi.com",
11. "X-Ca-Key":"testKey",
12. "Date":"Mon, 05 Jun 2017 08:52:43 GMT","Accept":"application/json",
13. "headerParam":"testHeader"
15. {"bodyParam":"testBody"}

API網關返回內容：

1. 200
2. Date: Mon, 05 Jun 2017 08:52:43 GMT
3. Content-Type: application/json; charset=UTF-8
4. Content-Length: 429
5. Access-Control-Allow-Origin: *
6. Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS , PATCH
7. Access-Control-Allow-Headers: X-Requested-With, X-Sequence,X-Ca-Key,X-Ca-Secret,X-Ca-Version,X-Ca-Timestamp,X-Ca-Nonce,X-Ca-API-Key,X-Ca-Stage,X-Ca-Client-DeviceId,X-Ca-Client-AppId,X-Ca-Signature,X-Ca-Signature-Headers,X-Forwarded-For,X-Ca-Date,X-Ca-Request-Mode,Authorization,Content-Type,Accept,Accept-Ranges,Cache-Control,Range,Content-MD5
8. Access-Control-Max-Age: 172800
9. X-Ca-Request-Id: 16E9D4B5-3A1C-445A-BEF1-4AD8E31434EC
10. x-custom-header: header value
12. {"message":"Hello World!","input":{"body":"{\"bodyParam\":\"testBody\"}","headers":{"X-Ca-Api-Gateway":"16E9D4B5-3A1C-445A-BEF1-4AD8E31434EC","headerParam":"testHeader","X-Forwarded-For":"100.81.146.152","Content-Type":"application/x-www-form-urlencoded; charset=UTF-8"},"httpMethod":"POST","isBase64Encoded":false,"path":"/fc/test/invoke/test","pathParameters":{"type":"test"},"queryParameters":{"param1":"aaa","param2":"bbb"}}}

4. 多環境

可以通過API網關的環境管理功能來實現測試環境的管理。目前每個API分組可以有三個環境：測試、預發和線上（后續會開放多個，實現自助管理）。

API網關，為避免用戶測試、線上不停變化后端地址，增加環境級變量參數的來實現請求的自動路由。

環境級變量參數，即在每個環境中可以自定義公共常量參數。當用戶發API調用時，可以在放置請求任意位置，傳遞給后端服務，以實現網關對請求的路由。

API網關將適配您請求中的環境參數信息來區分請求環境。

4.1 配置方法

4.1.1 定義環境變量

1)您可以在【開放API】-【API分組】菜單找到環境配置按鈕：

2)在測試、預發、線上環境，分別新增一個變量。

• Name：是變量的名稱，可以自行定義，但要保持三個環境中都有相同的變量名稱。

  小提示：您如果有多個API，建議Name標識有實際意義，以便后續查詢。

• Value：對應你在函數服務中的Service或者Function名稱。

  注意：請按您實際的名稱填寫，否則可能造成無法調用。

下面以Service為例介紹：

比如：我有個函數服務，測試、預發、線上的名稱分別為：TestServiceD、PreServiceD、ServiceD。

那么我需要測試、預發、線上分別定義一個Service的變量，並填寫相應Value

函數名稱，也可以同理錄入，您可以錄入一個叫Function的環境變量。

4.1.2 定義API

在定義API是可以在Service、Function的位置用“#”隔開，輸入您環境變量的Name，如圖：

注意：使用多環境后，將暫時無法使用“調試”功能

4.2 調用多環境API

發布您的API后，您即可發起API調用。

4.1 正式環境

直接發起您的API調用，即調用測試環境。

4.2 預發環境

您只需要在調用API時，在Header中增加入參X-Ca-Stage: RELEASE 即可訪問預發環境的API。

4.2 測試環境

您只需要在調用API時，在Header中增加入參X-Ca-Stage: TEST 即可訪問測試環境的API。

5. FAQ

1. 為什么我無法錄入我已有的Function？

   函數計算服務由很嚴格的權限控制機制，所以您必須授權API網關可以使用，因此請在確認您的Function存在，並且可用的情況下，檢查一下授權關系是否存在。

2. 我是否可以將多個Function作為API的后端服務？

   不可以，目前API和Function是一對一的關系存在。

十二、支持HTTPS

HTTPS在HTTP的基礎上加入了SSL協議，對信息、數據加密，用來保證數據傳輸的安全。現如今被廣泛使用。

API網關也支持使用HTTPS對您的API請求進行加密。可以控制到API級別，即您可以強制您的API只支持HTTP、HTTPS或者兩者均支持。

如果您的API需要支持HTTPS，以下為操作流程：

步驟1:准備

您需要准備如下材料：

• 一個自有可控域名。

• 為這個域名申請一個SSL證書

  SSL證書會包含兩部分內容:XXXXX.key、XXXXX.pem，可以使用文本編輯器打開

  示例：

  KEY

  1. -----BEGIN RSA PRIVATE KEY-----
  2. MIIEpAIBAAKCAQEA8GjIleJ7rlo86mtbwcDnUfqzTQAm4b3zZEo1aKsfAuwcvCud
  3. ....
  4. -----END RSA PRIVATE KEY-----

  PEM

  1. -----BEGIN CERTIFICATE-----
  2. MIIFtDCCBJygAwIBAgIQRgWF1j00cozRl1pZ+ultKTANBgkqhkiG9w0BAQsFADBP
  3. ...
  4. -----END CERTIFICATE-----

步驟2:綁定SSL證書

准備好以上材料，需要進行如下操作進行，登陸API網關管理控制台【開放API】-【分組管理】，單擊您需要綁定SSL證書的分組，查看分組詳情

在綁定SSL證書，您首先需要您在API分組上綁定【獨立域名】

【獨立域名】-添加SSL證書

• 證書名稱：用戶自定義名稱，以供后續識別
• 證書內容：證書的完整內容，需要復制XXXXX.pem 中的全部內容

• 私鑰：證書的私鑰，需要復制XXXXX.key中的內容。點擊【確定】后，完成SSL證書的綁定。

  步驟3：API配置調整

 

 

• 綁定SSL證書后，您可以按API控制不同的訪問方式，支持HTTP、HTTPS、HTTP和HTTPS三種，出於安全考慮，建議全部配置成HTTPS。

  可以在【開放API】-【API列表】找到相應API，【API定義】-編輯-【請求基礎定義】中進行修改。

  API支持的協議包括：

  • HTTP：只允許HTTP訪問，不允許HTTPS
  • HTTPS：只允許HTTPS訪問，不允許HTTP
  • HTTP和HTTPS：兩者均可調整后，API支持HTTPS協議配置完成。您的API將支持HTTPS訪問。