前言

一個Open APIs的生態建設，在對外API服務及治理的角度，關鍵是引入一個優質的APIM。現有的雲廠商相關服務，AWS算一個比較好的選擇。但是如果自己搭建，要麼選擇基於開源的框架，要麼基於API Gateway的自建方式。但是一定要滿足APIM（API Manager）的必要功能和服務體系。下面基於我之前使用的WSO2 APIM，進行介紹。注：之前使用的完全開源版本。

APIM的組件

一個組件是由一個或多個OSGibundle組成，一個bundle是OSGi中的一個模塊化單元，就像java的jar文件。基於組件的架構為開發者提供了基於最小依賴的移除或添加特性的靈活性。

APIManager提供以下高級組件：

API Publisher

提供友好的API提供商使用的Web終端用戶界面，用於發佈API、共享文件、提供API密鑰，及收集API的性能、質量、使用情況的反饋信息。

API Store

提供友好的API消費者使用的Web終端用戶界面，用於API消費者自主註冊、發現API功能、訂閱API，評價API，及與API提供商交互。

API Gateway

使用esb開發的後端運行組件（API代理）。包括API Gateway安全、保護、管理，以及度量API的調用。它攔截API請求，並應用策略（如流量控制、安全使用處理、管理API統計）處理。通過策略驗證後，該Gateway才傳輸Web服務請求消息到實際的後端服務。如果這服務調用請求是一個令牌請求，Gateway直接傳輸請求到Key Manager組件。在API Manager運行時，你可以使用URL https://localhost:9443/carbon訪問該Gateway。監控和統計組件已經集成到API Manager上了，不需要任何額外的配置工作。集成在Business Activity Monitor產品上的監控組件，可以分開部署來分析事件。

提示：雖然APIGateway包含ESB的功能，建議不要使用ESB特有的計劃任務，僅使用它與API調用相關的網關功能。例如，如果你想調用外部服務，如SAP,使用一個單獨的ESB集群來實現。

Key Manager

處理所有與安全和密鑰相關的操作。當API被調用時，Gateway連接Key Manager來檢查OAuth tokens的有效性。Key Manager還提供了一個可以通過Gateway訪問的token API，用於生成OAuth tokens。所有用於驗證的tokens都是基於OAuth 2.0.0協議的。Key Manager基於OAuth 2.0標準對API的進行安全授權。API Gateway支持OAuth 2.0 API認證，使得IT組織可以執行速率限制以及流量控制策略。當Gateway接收到API調用請求時，它同樣聯繫Key Manager服務進行驗證。如果在Gateway 層沒有啟用緩存，這種驗證請求在Gateway每次收到API調用請求時都會發生。Gateway傳輸access token、API、API version到Key Manager來進行這種驗證。API Gateway與Key Manager之間的通信以如下兩種方式進行：

• Through a Web service call
• Through a Thrift call (Thrift is the default communication protocol and is much faster than SOAP over HTTP)

如果你使用ELB做負載均衡，建立了有多個Key Manager節點的集群，修改<apim>/repository/conf/api-manager.xml的<keyvalidatorclienttype>節點，將Key Manager的協議從Thrift修改為WSClient。因為Thrift使用TCP做負載均衡，ELB目前還不支持。/<keyvalidatorclienttype>/<apim>

Handlers

當一個API創建完成，一個synapse配置文件就被添加到API Gateway。可以在<apim>/repository/deployment/server/synapse-configs/default/api文件夾下找到。配置文件中包含一組的handlers，在API上執行的每個handler的順序與在這配置文件中排列的順序一致。在任何API的Synapse配置文件中都可以找到的默認的handlers配置如下：/<apim>

<handlers>

<handlerclass>

<handlerclass>

<propertyname>

<propertyname>

<handlerclass>

<handler>

<handlerclass>

說明：

APIAuthenticationHandler：驗證OAuth2 持票人的token時調用的API。這也決定了該token是Production或Sandbox，以及適當的設置MessageContext變量。

APIThrottleHandler：流量控制基於流量控制策略中policyKey屬性的設置。流量控制可應用於applicationlevel、subscription level。

APIMgtUsageHandler：發佈事件到BAM，用於收集和分析統計數據。這個handler只有在啟用APIusage tracking的情況下才會執行。

APIMgtGoogleAnalyticsTrackingHandler：發佈事件到Google分析。這個handler只有在啟用Google analytics tracking的情況下才會執行。

APIManagerExtensionHandler：擴展處理經API Gateway傳輸的消息的中介。

Statistics

由monitoring組件提供statistics，集成自BAM。

用戶及角色

API Manager提供4種不同的適用於大多數企業的角色：

Admin

管理主機、API Gateway的API Manager提供商。負責在此係統中的創建、分配用戶角色，管理數據庫、安全等。這個Admin角色默認的賬戶密碼是admin/admin。

Creator

Creator是具有API相關知識（接口、描述文檔、版本等）的角色，通過APIPublisher組件來註冊APIs到APIStore中。Creator通過APIStore來查看API使用者的評價和反饋信息。Creator可以添加APIs到Store中，但不能管理它們的生命週期。

Publisher

Publisher管理一組企事業單位間的API，並控制API的生命週期、訂閱使用費用。Publisher也可以以使用者模式訪問所有感興趣的API，以及API統計信息。

Subscriber

Subscriber通過API Store組件來發現APIs，閱讀文檔、討論、API的評價信息，訂閱APIs，獲取access tokens以及調用APIs。

API生命週期

API是一個發佈的接口，而實現這接口的服務運行在後端。APIs有它們自己的生命週期，與它們依賴的後端服務無關。生命週期在APIPublisher Web界面展示，由APIpublisher角色管理。默認有如下幾種可用的API生命週期狀態：

• CREATED：添加了API元數據到APIStore，但還沒有部署到APIgateway，因此，訂閱者在APIStore中是看不見的。
• PROTOTYPED：API原型已經部署且發佈到了APIStore。原型API通常是一個為了得到關於其可用性的反饋信息的模擬實現。用戶不訂閱就可以調用此API。
• PUBLISHED：API在APIStore中可見，也可以被訂閱。
• DEPRECATED：當一個API是deprecated狀態時，不能創建新的訂閱。但API仍然部署在Gateway，在運行時對現有的訂閱者仍然可用。現有的訂閱者可以像以前一樣繼續使用直到此APIretired。
• RETIRED：API已經從APIGateway取消發佈，從store中刪除了。
• BLOCKED：訪問該API暫時被阻塞。運行時調用被阻塞，APIStore也不顯示該API。

應用 / Application

Application邏輯上是一個API集合。Application主要用於將用戶從APIs上區分開。有如下功能：

• 生成並使用一個密鑰訪問多個API。
• 使用不同的SLA levels多次訂閱一個API。

通過一個application訂閱APIs。Applications在不同的SLAlevels都是可用的，具有application-levelthrottlingtiers功能。throttlingtier決定了在一段指定的時間內可以調用API的最大次數。API Manager預先定義的、默認的application，默認允許無限訪問API。可以創建自己的applications。

訪問令牌 / Access tokens

accesstoken是一個通過HTTP請求頭部信息傳輸的簡單的字符串。例如："Authorization: BearerNtBQkXoKElu0H1a1fQ0DWfo6IX4a"。Access tokens用於驗證API的用戶和應用程序，並確保更好的安全性（例如，防止DOS攻擊）。如果一個請求附帶的token是無效的，這個請求在第一階段處理時就被丟棄。無論是SOAP調用，還是REST調用，Accesstokens都工作的一樣好。有兩種類型的accesstokens：

• User access tokens
• Applicationaccesstokens

Useraccess tokens

Tokens用於驗證API的終端用戶。Useraccess tokens允許你從第三方應用程序調用一個API，例如mobileapp，通過RESTclient調用LoginAPI,生成或更新一個useraccess token。

Application access tokens

Tokens用於驗證一個邏輯上是一個API集合的應用程序。允許使用一個accesstoken來訪問與一個應用程序相關的所有API,也可以使用不同的SLA等級多次訂閱同一個API。Applicationaccess tokens利用OAuth2的優勢提供簡單的密鑰管理。

流控 / Throttling Tiers

流量控制允許限制API在一段時間內的點擊數，典型的應用場景如下所示：

• 保護API免遭常見的安全攻擊，如拒絕服務攻擊（DOS）
• 根據基礎設備的情況限制流量
• 將API、應用程序或資源，以不同等級的服務提供給消費者，通常是以盈利為目的

流控的層級

流量控制分以下幾種級別：

• API-level throttling
• Application-level throttling
• Resource-level throttling
• IP-level throttling

（1）API-level throttling

API-levelthrottling tiers是在使用API Publisher portal管理APIs時被定義的。界面如下：

在設置好API-level throttling tiers併發布API服務後，在訂閱的時候，該API的消費者可以登錄進API Store,並選擇適合自己的tier。界面如下：

根據訂閱者選擇的tier，准許訂閱者在指定時間內發送該tier中配置的最大請求數量的請求給該API。默認的tier如下:

• Bronze: 每分鐘1個請求
• Silver: 每分鐘5個請求
• Gold: 每分鐘20個請求
• Unlimited: 允許無限訪問（可以通過修改<apim>/repository/conf/api-manager.xml文件中的<tiermanagement>節點禁用此等級）/<tiermanagement>/<apim>

設置tier權限：用戶可以通過基於角色的權限控制，管理設置API-level access throttling tiers的權限。這是通過使用在API Publisher界面的Tier Permissions菜單來設置的，如下圖所示。在每一個tier,可以使用逗號分隔多個角色，設置為允許或拒絕設置的角色訪問此tier。

Subscriber登錄到API Store可以使用一個指定的，所在角色被允許訪問的tier消費APIs。在API Store中，subscriber能看到一個基於subscriber所在角色過濾後的tiers列表，只有允許角色訪問的tiers才會出現在這裡。默認設置是允許所有人訪問所有tiers。

（2）Application-level throttling

Application-level throttling tiers是在application創建到API Store時被定義的。界面如下：

一個應用程序在邏輯上是一個或多個API的集合，發佈需要被訂閱的API。允許使用一個access token來調用一組API，及使用不同的SLA等級多次訂閱一個API。應用程序可以給消費者提供不同等級的服務。例如：如果你的應用程序受限於基礎設施，在單位時間內不能接收超過一定數量的請求。可以通過throttling tiers設置應用程序在指定時間段能夠接收的最大請求數。默認的throttling levels如下所示：

• Bronze: 每分鐘1個請求
• Silver: 每分鐘5個請求
• Gold: 每分鐘20個請求
• Unlimited: 無訪問限制。應用程序的默認設置。你可以將它設置為受限的。

（3）Resource-level throttling

一個API是由一個或多個資源組成。每個資源處理特定類型的請求，類似於一個方法（函數）在一個較大的API中。Resource-level throttling tiers是在使用API Publisher portal管理API時，設置在API的資源的HTTP verbs上的。如圖所示：

默認的throttling levels是Gold、bronze、silver及unlimited，與在上一節講到的一樣。

當subscriber使用API Store查看API時,他能夠通過Throttle Info 標籤看到resource-level throttling tiers。如下圖所示：

Subscribers是沒有權限修改這些throttling tiers。只是通知給Subscribers，知道這些限制。

（4）IP-level throttling

基於IP的流量控制，可以通過客戶端IP來限制客戶端的請求數量（例如：一個客戶端請求10次）。

• 登錄到管理控制檯，單擊Resources -> Browse菜單。
• 在/_system/governance/apimgt/applicationdata目錄下找到tiers.xml文件。

• 添加你的策略。例如：以下策略只允IP為10.1.1.1的客戶端每分鐘調用1次API，允許其他IP地址的客戶端每分鐘調用2次API。策略配置如下：

<policyxmlns>

xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">

<mediatorthrottleassertion> /<mediatorthrottleassertion>

<policy> /<policy>

<idthrottle>10.1.1.1 /<idthrottle>

<policy> /<policy>

<control> /<control>

<policy> /<policy>

<maximumcount>1/<maximumcount>

<unittime>60000/<unittime>

<policy> /<policy>

<idthrottle>other /<idthrottle>

<policy> /<policy>

<control> /<control>

<policy> /<policy>

<maximumcount>2/<maximumcount>

<unittime>60000/<unittime>

流控層工作原理

通過在3個層面定義的流量控制，最終才准許API調用請求經過統一的throttlingtiers輸出到後端服務。

例如：兩個用戶使用Gold級別（每分鐘20個請求）的流量控制訂閱了一個API。他們都使用應用程序App1來進行訂閱，App1也有一個流量控制，tier也設置成了每分鐘20個請求。所有資源級別的流量控制是unlimited。在這個場景下，儘管用戶可以每分鐘調用20次API，但理論上又限制為每分鐘發送10次請求。這是由於應用程序級別的每分鐘20次請求的限制造成的。

API可見性 / API visibility

API可見性設置用於防止某些用戶角色查看、修改由另一個用戶角色創建的APIs。

• Public:所有用戶（包括註冊用戶及匿名用戶）都可以訪問這種API，能夠在多個Stores（central and non-WSO2 stores）展示。
• Visible to my domain:在此API租戶域註冊的用戶可以訪問這種API。
• Restricted by Roles:在此API租戶域註冊的，指定角色的用戶可以訪問這種API。

以下是visibility levels為處於不同角色中的用戶工作的過程：

• API creator和publisher角色可以看到在他們租戶域的Store中的所有API，就算限制了訪問的也能看見。這是因為這些角色在APIPublisher中有查看和編輯所有API的權限，因此，在Store中沒有被限制。
• 匿名用戶只能看見可見性設置為Public的APIs.
• 註冊用戶可以看見：

1. 所有租戶域下的public APIs。
2. 在用戶註冊的租戶域下的所有沒有基於角色限制的、及分配了角色權限訪問的所有APIs。

API文檔可見性 / API documentationvisibility

所有與API相關的文檔默認都是與API具有一樣的visibilitylevel。換句話說，如果API是public，它的文檔也就是所有用戶（包括註冊用戶及匿名用戶）都可以訪問。如果要給文檔啟用另外的visibilitylevels，到/repository/conf/api-manager.xml文件中，取消註釋掉的如下內容，設置為true。如下所示：

<apipublisher>

....

<enableapidocvisibilitylevels>true/<enableapidocvisibilitylevels>

然後登陸進API Publisher,進入Doc標籤，單擊Add new Document就可以看見一個新的下拉列表被添加進了表單：

可以通過以下方式設置visibility：

• Same as API visibility：可以看見API的用戶角色就可以訪問。例如，如果API的visibility是public，它的文檔就是所有用戶都可以訪問。
• Visible to my domain：所有在API所在租戶域註冊的用戶可以訪問。
• Private：只有能夠登錄到API Publisher Web界面，能夠創建或發佈APIs到API Store中的用戶可以訪問。

API資源 / API resources

一個API是由一個或多個資源組成。每個資源處理特定類型的請求，類似於一個方法（函數）在一個較大的API中。

APIresources具有以下屬性：

OAuth Scopes

對API資源在一定範圍內使用基於用戶角色的細粒度的訪問控制。可以自定義API資源範圍。當用戶調用API時，他的OAuth 2 token不能授予任何規定的API資源範圍外的權限。可以在API創建或修改時指定API資源的範圍。在API Publisher中，單擊API -> Add菜單（添加新的API）或Edit鏈接編輯已存在的API。然後，導航到Manage選項卡，向下滾動到Add Scopes按鈕。一個如下的頁面就出現了：

• Scope Key：scope的唯一標識。通常使用API名稱的一部分做前綴來滿足唯一性，但不要求可讀性。
• ScopeName：人可讀的scope名稱。通常能反應出這個scope是做什麼的。
• Roles：允許獲取訪問此scope的token的用戶角色。例如：manager,employee。

為了解釋scopes的功能，假設你有如下圖所示的scopes附加到一個資源API上：

假設賦予了用戶Tom角色employee，賦予了用戶John角色employee和manager。Tom通過Token API使用grant_type=password&username=nuwan&password=xxxx&scope=news_readnews_write請求一個token。然而，由於Tom不是manager角色，只會授予他一個news_read scope的token。從Token API返回的響應信息類似於如下內容：

"scope":"news_read","token_type":"bearer","expires_in":3299,

"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",

"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8"

另一種情況，John使用消息grant_type=password&username=john&password=john123&scope=news_readnews_write請求一個token。由於兩個角色都賦予了John，那麼生成的token會具有請求的scopes的所有權限。響應消息類似於如下內容：

"scope":"news_readnews_write", "token_type":"bearer","expires_in":3299,"refresh_token":"4ca244fb321bd555bd3d555df39315",

"access_token":"42a377a0101877d1d9e29c5f30857e"

也就意味著，Tom只能使用這個API的GET operation，而由於授予了John employee和manager兩個角色，John可以訪問所有的operation。如果Tom試圖訪問POST operation，將會返回HTTP 403禁止訪問的錯誤，如下：

<faultxmlns>

<code>900910/<code>

<message>The access token doesnot allow you to access the requested resource/<message>

<description>Access failure forAPI: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8/<description>

提示：調用通過scopes保護的API，需要通過Token API獲取access token。而不是從API Store的My Subscriptions頁面生成的token。

URL Pattern

URL pattern可以是以下類型中的任意一種：

l url映射（url-mapping）。例如：/state/town/*

l uri模板（uri-template）。例如：/{state}/{town}

url-mapping和uri-template表達式來源於synapse configuration language。當一個API發佈到API Publisher中時，在API Gateway中就創建了一個對應的XML定義文件。這個XML文件有一個專用的部分用於定義資源。例如：

<resourcemethods>

<resource>

url-mapping根據請求的URL進行一對一的映射，而uri-template則進行模式匹配。

參數化的URL允許API Manager基於消息內容及請求的URI，映射輸入請求到定義的資源模板上。一旦一個uri-template匹配上，模板中的參數就被填充上。根據上面的例子，一個請求到http://gatewa_host:gateway_port/api/v1/texas/houston，則設置state的值為texas,town的值為houston。可以通過uri.var.province和uri.var.district變量來使用這些參數，以在synapse中用於不同目的的配置和採集訪問信息。

HTTP Verb

指定需要對資源執行的HTTP方法。這些方法可以是GET、POST、PUT、DELETE或OPTIONS。可以選擇多個方法。

Auth Type

對資源的各種HTTP方法的驗證類型，可以指定為下列中的一種：

None：沒有使用認證，API Gateway跳過認證處理。

Application：通過應用程序的用戶進行認證，資源接收user access tokens。

Application and Application User：同時使用了應用程序和應用程序用戶兩種級別的認證。

注意：具有HTTP verbs(GET、POST等)的資源需要認證（即，認證類型不能設置為NONE），只有在HTTP verbs為OPTINS時，可以設置為NONE。這是為了支持在API Store和Gateway間的CORS(跨域資源共享)（如上一個截圖所示）。

為了更好的性能，認證類型緩存在API Manager中。如果通過UI修改了認證類型，需要大約15分鐘來刷新緩存。在這期間，服務從緩存返回舊的認證類型。如果你想改為立即返回，請在更改認證類型後重啟服務。

小結

資源的參數緩存在APIGateway的資源緩存中。一旦一個請求被資源接收，它將通過in-sequense中介處理。任何來自後端服務的響應消息被out-sequence處理。Fault sequences用於中介處理在sequences中可能發生的錯誤。默認的in-sequence、out-sequence和fault sequences在API發佈時生成。

API模板 / API templates

API template是使用XML來描述的，保存在<apim>/repository/resources/api_templates/velocity_template.xml文件中。這個文件是API Manager的默認文件。可以修改這個默認的模板來改變所有已創建的API的synapse配置。如果使用分佈式方式部署的API Manager（即：Publisher、Store、Gateway、Key Manager組件運行在不同的JVM上），編輯Publisher節點的template。/<apim>

其他

Endpoints

Endpoint是一個標識消息目的地的信息，如：address、WSDL、a failover group, a load-balance group等。API Manager支持一系列不同類型的endpoint，允許API Gateway與後端服務進行高效的連接。支持HTTP endpoints, URL endpoints（也被稱為address endpoint），WSDL endpoints, Failover endpoints,Load-balanced endpoints

注意以下幾點：

• 通過API，支持以REST、SOAP方式將服務暴露給消費者。
• 不能調用在APIPublisher創建的使用OAuth保護的後端服務。在這種情況下，只能使用賬戶名、密碼才能調用受保護的服務。
• 系統從<java>/Repository/conf/api-manager.xml文件讀取gateway endpoints信息。在定義了多個gateway的環境中，從production 環境獲取gateway endpoint信息。可以像下面這樣定義HTTP及HTTPS gateway endpoints：<gatewayendpoint>http://${carbon.local.ip}:${http.nio.port},https://${carbon.local.ip}:${https.nio.port}/<gatewayendpoint>/<java>
• 如果兩種類型的endpoints都定義了，會選擇HTTPSendpoint作為這個服務器的endpoint。提示：如果定義了安全的（HTTPS）endpoints，請在<apim>/repository/conf/axis2/axis2.xml文件的HTTPS transport sender的配置處設置<parameter>元素的值為AllowAll：<parameter>AllowAll/<parameter>/<parameter>/<apim>

如果不設置，服務器會拋出異常。

• 當通過PublisherUI(在Implement選項下)創建或更新Failoverendpoints時，需要進入每個endpoint的AdvancedOptions選項，為endpoint設置一套失敗發生時的錯誤代碼，設置InitialDuration的值為-1來去掉InitialDuration。

Sequences

在每個API調用時，會執行API Manager默認的mediation flow。有3個默認的sequences：in、out、fault。

Caching

關於響應消息的緩存，及在Gateway和Key Manager server調用API的緩存的配置信息，請查看緩存配置。

閱讀更多 AirlineDataPlus 的文章

關鍵字: 一個 前言 Java