使用 WSO2 API Manager 管理 Rest API

WSO2 API Manager 簡介

隨着軟件工程的增多，越來越多的軟件提供各種不同格式、不同定義的 Rest API 作為資源共享，而由於這些 API 資源的異構性，很難對其進行復用。WSO2 API Manager （下文簡稱為 AM）提供了一個完整的 API 發布的解決方案，從創建和管理 API，到監控 API，AM 提供了 API 整個生命周期所需要的各種控制，包含控制訪問權限，訪問流量，監控 API 的調用，版本控制等。 對於開發人員，使用 AM 將不需要再關心安全檢查，流量監控等輔助功能，只需關注 API 的業務邏輯，而架構師則將不再需要為不同的 API 編寫適配接口，而只需將 API 資源添加到 WSO2 API Manager 中，即可實現 API 資源復用等功能。同時 WSO2 API Manager 提供了可視化的管理界面，可以實時對 API 的訪問進行調控，從而使得 API 作為資源更為便捷的進行復用。

圖 1（引用自參考 1）展示了 AM 的架構，可以看到其主要由三部分組成，分別是 API Publisher、API Store 和 API Gateway。所有的 API 請求通過 API Gateway 進行攔截，實現請求 mapping，攔截，監控等各種功能。而 API publisher 用來生成、發布、管理、監控 API，由此創建的 API 將會注冊到 API Gateway 中以發布給用戶使用。API Store 則展示了用戶可見的所有 API，用戶通過這個頁面來查找、訂閱自己需要的 API。

圖 1.WSO2 API Manager 結構圖

API 生命周期

一個 API 從建立到銷毀將經歷以下周期，API Manager 提供對全生命周期的管理：

• Created：創建 API，在 created 周期中，API 只是被添加到了 API Store，但並不對用戶可見，也沒有部署到 API Gateway 中。
• Prototyped：API 作為以原型部署並發布在 API store 中。一個 API 原型通常是為了獲得其可用性的反饋，而模擬的實現，用戶可以嘗試使用但並不能將其添加到自己的 Application 中。
• Published：該階段是 API 正常使用階段，用戶可以在 API Store 中看到並且可以將其添加到自己的 Application 中調用。
• Deprecated：API 仍然部署在 API Gateway 中，但已經不能被調用。當一個新版本的 API 發布后，舊版本的 API 將自動變為 Deprecated。
• Retired：API 過期后將從 API Gateway 以及 API store 中移除。
• Blocked：API 訪問被限制，實時狀態下不能訪問該 API，並且不在 API store 中顯示。

Application

Application 主要用來使用戶為不同的目的添加不同的 API，例如，一個用戶需要兩組 API，一組專門用於零售業，另一組用於銀行業，這樣每一組都代表一個 Application，用戶可以將所有零售業的 API 放入 Retailer Application，銀行業的 API 放入 Bank Application。

Application 不但用於 API 的分組，還可以實現多個 API 接口使用同一個 access 密鑰，不用為每一個 API 都生成一組訪問密鑰。每一個用戶都有一個默認的 Application，同時可以為不同目的創建不同的 Application。

 

回頁首

WSO2 API Manager 安裝

WSO2 API Manager 需要 Oracle JDK 1.6.27 以上 或 1.7，並配置 JAVA_HOME 環境變量。下載相應的安裝包，解壓縮即可。不同操作系統的安裝有略微差異，具體可參考參考文檔 2（https://docs.wso2.com/display/AM190/Installing+the+Product）。

本文示例所用的 AM 安裝在 Linux 上，JDK 1.7。並且創建了 APITest role 和 APTTester user 作為本文使用的測試用戶組。

 

回頁首

通過 web console 新建 API

首先我們來說明一下 WSO2 AM published 的 API 的 URI pattern，如下圖 2：

圖 2.WSO2 API Manager published 的 API URI pattern

<context>和<version>是 WSO2 AM 自動添加到 API 的 URL 中，而<other patter>是可以根據需要自己設定。同時 WSO2 AM 不支持 URL 中包含參數，所有的參數需要通過 URL 路徑傳輸。

由於 AM published 的 URL 限制，我們需要添加的 API（后台的 API）的 URL 一般不會和 AM published 的 URL 一致，因此需要將后台的 API 的 URL mapping 到 AM published 的 URL 上。不同的后台 API URL 格式需要使用不同的 mapping 方法，以下以一個測試的 web 工程為例，說明如何添加后台 API 到 AM 中。

測試的 web 工程提供以下三組 Rest API，分別是：

1. http://localhost:8080/APITest/tasks/allTasks (不包含參數)
2. http://localhost:8080/APITest/tasks/getTasks/{taskId}（包含路徑參數）
3. http://localhost:8080/APITest/tasks/queryTasks?taskName={taskName}（包含查詢參數）

添加第一個 API

首先以添加第一個 API 為例，說明添加 API 的基本流程，然后將闡述如何添加其他兩種形式的 API。

圖 3 顯示了后台 API 到 AM published 的 API 的 URL 映射關系，我們將按如下關系來添加第一個 API：

圖 3. 后台 API 到 AM published 的 API 的映射

可以看到，從后台 API 到 AM API 需要經過一個 mapping，從端口號之后，URL 的格式就完全不同了，AM 提供了通過 xml 文件來描述 URL mapping 的機制，最簡單的就是直接將 AM API 端口號之后的 URL 用后台 API 的 URL 替換。該 XML 描述文件如下：

清單 1. 替換端口號之后的 URL 的 XML 文件

<sequence xmlns="http://ws.apache.org/ns/synapse" name="RemovePostfixSequence">
 <property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>
</sequence>

將清單 1 保存為 removePostfixSequence.xml 文件，並通過以下步驟將該文件上傳到 AM 的 API Gateway，由 API Gateway 來進行具體的 mapping。在 AM 中，這類 mapping XML 文件統稱為 sequence 文件。

上傳 Sequence 文件到 AM

1. 登陸 API carbon（https://localhost:9443/carbon/），用戶名密碼默認為 admin/admin。

2. 如圖 4，選擇 Resource > Browse > _system > governance >customsequences > in。

圖 4. 選擇 sequence 路徑

3. 上傳 removePostfixSequence.xml 文件，如圖 5 所示：

圖 5. 上傳 removePostfixSequence.xml 文件

點擊“Add Resource”后會出現圖 5 所示的上傳文件的具體信息，在 File 欄中選擇 Browse，選擇 removePostfixSequence.xml 文件的路徑，點擊 Add。

4. 上傳成功后，可以在 Entries 中看到已上傳的文件。

圖 6. 上傳成功

通過以上步驟，我們將 removePostfixSequence.xml 文件上傳到 AM 的文件系統中，在后續的添加 API 的過程中，可以直接使用該文件。

添加 API 到 AM

完成以上准備工作后，我們可以添加第一個 API 了。

1. 登陸 API Publisher（https://localhost:9443/publisher），用戶名密碼默認為 admin/admin。

2. 選擇添加 API，如圖 7 所示：

圖 7. 添加 API

選擇“Add”>“Design new API”>“Start Creating”。

3. 填寫 API 的具體信息，如圖 8 所示。

圖 8.API 具體信息

這里的“Context”必須是唯一的，如果在 Context 中不包含 {version}，只寫為 APITasks，則 version 信息將會被添加到 Context 之后，也就是 APITasks/v1。如果在 Context 中填寫 {version}/APITasks，則 version 信息將在 APITasks 之前，即 v1/APITasks。這里我們選擇將 version 信息寫在前面。

Visiblity 用來控制該 API 可以被哪些 role 可見。如果所有人可見，則該選項為“Public”。這里我們只需要屬於 APITest 的 user 可見，因此 Visible to Roles 填寫 APITest。

然后定義 API 的 URL Pattern，根據圖 3 的目標結果，這里填寫 allTasks，選擇 GET 方法，單擊 Add。添加完成后點擊 Next：Implement，進入 Implement 頁面。

1. 在 Implement 頁面中選擇 Managed API，配置具體的 API 信息，如圖 9 所示：

圖 9.Managed API

Production Endpoint 和 Sandbox Endpoint 輸入后台 API 的 URL，Endpoint Type 為 HTTP Endpoint。這里的 Endpoint URL 就是該 API 實際調用的后台鏈接。

設置完成后點擊 Next：Manage，進入 Manage 頁面。

2. 在 Manage 頁面中完成 API 的 Configuration 配置，如圖 10 所示：

圖 10.API Configuration 配置

在以上配置中，Tier Availability 用來設置對 requests 的限制，分別有以下幾種：

• Bronze: 每分鍾允許 1 個 request 請求
• Silver: 每分鍾允許 5 個 request 請求
• Gold: 每分鍾允許 20 個 request 請求
• Unlimited: 不限制

可以根據 API 的具體需求選擇。

Message Mediation Policies 用來指定如何 mapping AM 的 API URL 和后台 API URL，這里我們選擇之前上傳的 sequence 文件作為 mapping 的 police。

最后點擊頁面最下方的 Save & Published 來保存該 API。當保存 API 以后，會彈出圖 11 所示對話框，可以點擊 Go to Overview 來查看該 API 的信息。

圖 11.API 添加成功

可以在 API 的 Overview 中進行添加新 version、添加 API 的 document、查看 user 的使用情況，以及更改 API 的 Lifecycle 等操作，如圖 12 所示。

圖 12.API Overview

添加包含路徑參數的 API

以上我們添加了一個不包含任何參數的 API，下面要添加第二個 test API，該 API 包含一個路徑參數 taskId。后台 API 與 AM API 的映射關系如圖 13 所示。

圖 13. 第二個 API 的映射關系

該 API 的創建和第一個 API 的創建步驟一樣，只有兩個步驟的設置不同，一個是在第三步設置 API 具體信息時，需要填寫 request 參數，另一個是在第四步設置 Endpoint 時不同。以下分別說明，圖 14 顯示了第三步設置所需。

圖 14. 帶路徑參數的 API 的具體設置

點擊 Add 按鈕后，將會出現一個 GET 方法，單擊該方法將會出現具體的信息，如圖 15 所示。

圖 15. 帶參數的方法信息

在 AM 中，所有的參數都可以通過在 UR Pattern 中使用 {} 來設置，也可以在方法的具體信息中點擊 Add Parameter 來設置。AM URL 所使用的參數均為路徑參數，不可以包含查詢參數。也就是說，不可以在 URL Pattern 中使用“?taskId={taskId}”這樣的形式。

在第四步，Manage API 時，Endpoint 的設置需要改為包含參數的形式：

清單 2. 包含參數的 Endpoint

http://10.120.138.212:8080/APITest/tasks/getTasks/{uri.var.taskId}

這里 {uri.var.taskId} 用來表示傳入參數 taskId，如果有多個傳入參數，均需要寫成 {uri.var. 參數名} 這樣的形式。

除過以上步驟，其他步驟均與添加第一個 API 時一樣，在 Message Mediation Policies 中仍然選擇 RemovePostfixSequence 作為 In Flow。

添加包含查詢參數的 API

這里先給出包含查詢參數的 API 和 AM API 的映射關系，如圖 16 所示：

圖 16. 第三個 API 的映射關系

該 API 的建立同包含路徑參數的 API 一樣，需要在第三步 URL Pattern 中設置 {taskName} 作為參數。在第四步的 Endpoint 中，不能直接用包含“？”的路徑作為 Endpoint，我們只需要“？”之前的部分，在此例中為：http://localhost:8080/APITest/tasks/queryTasks。至於路徑中“？”之后的部分，我們需要一個新的 sequence 來進行 mapping。清單 3 給出了新的 sequence 文件內容。

清單 3. 查詢參數的 sequence 文件

<?xml version="1.0" encoding="UTF-8"?>
<sequence name="CDSSequence" trace="disable" xmlns="http://ws.apache.org/ns/synapse">
 <property description="QQY"
 expression="concat('?taskName=',syn:get-property('uri.var.taskName'
 name="QQY" scope="default" type="STRING"/>
 <property description="REST_URL_POSTFIX"
 expression="get-property('QQY')" name="REST_URL_POSTFIX"
 scope="axis2" type="STRING"/>
</sequence>

在清單 3 的 sequence 文件中，需要注意的是第一個 property 的 expression，該 expression 解析了后台 API URL“？”之后的部分，在 API 具體調用時，將后一部分添加到 Endpoint 之后，從而拼接出了完整的后台 API，再進行調用。每一個具體的包含查詢參數的 API 都需要根據具體的參數格式來修改這部分 expression，相同參數的 API 可以共用一個 sequence 文件，不同的則需要單獨的 sequence 文件。

在添加 API 之前，我們需要將這個 sequence 文件上傳到 AM 中，步驟和上傳 removePostfixSequence.xml 文件相同。

最后在 API configuration 配置時，Message Mediation Policies 中選擇新上傳的文件作為 In Flow。

 

回頁首

通過 WSO2 API Manager 調用 Rest API

至此，我們已經添加了三個 API 在 API Manager 中，作為 API 的使用者，需要用自己的賬號登陸 API Store，然后建立 Application，並 subscription 需要的 API。subscription API 的目的是使一組 API 可以共享同一個 access token，而不用為每一個 API 都生成一個 access token。

圖 17 展示了使用 APITester 用戶登陸后可以查看到的 API。

圖 17.API Store

如果登陸用戶不屬於 APITest role，則不會看到這三個 API。

之后需要建立自己的 Application 用來分類 API，這里我們新建一個 APITest Application 來包含以上三個 API。

圖 18. 創建 Application

在創建 API 之后，在 APIs tab 中單擊選擇需要包含在該 Application 中的 API，subscription 它。

圖 19.subscribe API

在 subscribe 成功后會彈出對話框，顯示 Sbuscription 成功，這時先不要進入 My Subscriptions 頁面，先將所有需要包含在該 Application 中的 API 都 subscribe 后，再進入 My Subscriptions 頁面。

當選擇完所有的 API 后，進入 My Subscription 頁面，生成 access token，就可以調用 API 了。如圖 20 所示，點擊 Generate keys 來生成 access token。

圖 20. 生成 Access token

首先需要選擇正確的 Application，可以在 Token Validity 中設定 token 過期的時間，默認是 3600 秒。點擊 Generate keys 生成 token，在該頁面的最下方會有所有已經 subscription 的 API，如圖 21 所示：

圖 21.subscribed APIs

可以通過單擊需要調用的 API，在網頁上直接調用，如圖 22 所示：

圖 22. 調用 APITest_GetTaskById

選擇 API Console，點擊 {taskId} 方法，輸入 taskId，點擊 Try it out！該頁面會顯示查詢結果，如圖 23 所示：

圖 23. 查詢結果

Curl 中顯示的命令，可以在命令行直接調用。

 

回頁首

總結

通過將 API 交付給 WSO2 API Manager 管理，開發人員將不用再關心 API 的訪問權限，訪問流量限制等問題，WSO2 API Manager 提供了安全的訪問機制以及監控機制，可以使開發者對自己的 API 進行全方位的管理和監控。本文通過實例描述了如何在 WSO2 API Manger 中創建一個 API，並且如何將 API 正確地 mapping 到后台實際的 API 上，並通過 WSO2 API Manager 提供的 console 界面管理各個 API。開發者可以通過本文提供的 sequence 描述文件作為范例，開發自己的 sequence 描述文件，適配不同的 API 資源，從而將不同規則、不同架構提供的 API 實現統一描述、統一管理，方便軟件的進一步功能性整合和復用。

參考資料

學習

• 參考 WSO2 API Manager Key Concepts，學習基本概念和架構。
• 參考 WSO2 API Manager Installation Guide，查看各操作系統的安裝。
• 參考 WSO2 API Manager User Guide，查看 API Manager 的使用說明。
• 參考 WSO2 Developer Studio，學習生成 sequence 文件。