wso2 API Manager主要概念介绍

原文地址：https://docs.wso2.com/display/AM180/Key+Concepts

翻译了wso2 AM产品中的主要概率，以便于理解使用wso2 AM。

1       API Manager components

一个组件是由一个或多个OSGibundle组成，一个bundle是OSGi中的一个模块化单元，就像java的jar文件。基于组件的架构为开发者提供了基于最小依赖的移除或添加特性的灵活性。

组件描述图

APIManager提供以下高级组件：

1.1 API Publisher

提供友好的API提供商使用的Web终端用户界面，用于发布API、共享文件、提供API密钥，及收集API的性能、质量、使用情况的反馈信息。

1.2 API Store

提供友好的API消费者使用的Web终端用户界面，用于API消费者自主注册、发现API功能、订阅API，评价API，及与API提供商交互。

1.3 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集群来实现。

1.4 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_HOME>/repository/conf/api-manager.xml的<KeyValidatorClientType>节点，将Key Manager的协议从Thrift修改为WSClient。因为Thrift使用TCP做负载均衡，ELB目前还不支持。

1.5 Handlers

当一个API创建完成，一个synapse配置文件就被添加到API Gateway。可以在<APIM_HOME>/repository/deployment/server/synapse-configs/default/api文件夹下找到。配置文件中包含一组的handlers，在API上执行的每个handler的顺序与在这配置文件中排列的顺序一致。在任何API的Synapse配置文件中都可以找到的默认的handlers配置如下：

<handlers>

   <handlerclass="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>

   <handlerclass="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">

        <propertyname="id" value="A"/>

        <propertyname="policyKey"value="gov:/apimgt/applicationdata/tiers.xml"/>

   </handler>

   <handlerclass="org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageHandler"/>

   <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler"/>

   <handlerclass="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>

</handlers>

说明：

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传输的消息的中介。

1.6 Statistics

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

 

2       Users and roles

API Manager提供4种不同的适用于大多数企业的角色：

2.1Admin

管理主机、API Gateway的API Manager提供商。负责在此系统中的创建、分配用户角色，管理数据库、安全等。这个Admin角色默认的账户密码是admin/admin。

2.2 Creator

Creator是具有API相关知识（接口、描述文档、版本等）的角色，通过APIPublisher组件来注册APIs到APIStore中。Creator通过APIStore来查看API使用者的评价和反馈信息。Creator可以添加APIs到Store中，但不能管理它们的生命周期。

2.3 Publisher

Publisher管理一组企事业单位间的API，并控制API的生命周期、订阅使用费用。Publisher也可以以使用者模式访问所有感兴趣的API，以及API统计信息。

2.4 Subscriber

Subscriber通过API Store组件来发现APIs，阅读文档、讨论、API的评价信息，订阅APIs，获取access tokens以及调用APIs。

3       API lifecycle

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。

4       Application

Application逻辑上是一个API集合。Application主要用于将用户从APIs上区分开。有如下功能：

l  生成并使用一个密钥访问多个API。

l  使用不同的SLA levels多次订阅一个API。

通过一个application订阅APIs。Applications在不同的SLAlevels都是可用的，具有application-levelthrottlingtiers功能。throttlingtier决定了在一段指定的时间内可以调用API的最大次数。

API Manager预先定义的、默认的application，默认允许无限访问API。可以创建自己的applications。

5       Access tokens

accesstoken是一个通过HTTP请求头部信息传输的简单的字符串。例如："Authorization: BearerNtBQkXoKElu0H1a1fQ0DWfo6IX4a"。Access tokens用于验证API的用户和应用程序，并确保更好的安全性（例如，防止DOS攻击）。如果一个请求附带的token是无效的，这个请求在第一阶段处理时就被丢弃。无论是SOAP调用，还是REST调用，Accesstokens都工作的一样好。

有两种类型的accesstokens：

l  User access tokens

l  Applicationaccesstokens

5.1Useraccess tokens

Tokens用于验证API的终端用户。Useraccess tokens允许你从第三方应用程序调用一个API，例如mobileapp，通过RESTclient调用LoginAPI,生成或更新一个useraccess token。

5.2 Application access tokens

Tokens用于验证一个逻辑上是一个API集合的应用程序。允许使用一个accesstoken来访问与一个应用程序相关的所有API,也可以使用不同的SLA等级多次订阅同一个API。Applicationaccess tokens利用OAuth2的优势提供简单的密钥管理。

6       Throttling tiers

流量控制允许限制API在一段时间内的点击数，典型的应用场景如下所示：

l  保护API免遭常见的安全攻击，如拒绝服务攻击（DOS）

l  根据基础设备的情况限制流量

l  将API、应用程序或资源，以不同等级的服务提供给消费者，通常是以盈利为目的

下面讲流量控制：

6.1Differentlevels of throttling

流量控制分以下几种级别：

l  API-level throttling

l  Application-level throttling

l  Resource-level throttling

l  IP-level throttling

6.1.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_HOME>/repository/conf/api-manager.xml文件中的<TierManagement>节点禁用此等级）

设置tier权限：用户可以通过基于角色的权限控制，管理设置API-level access throttling tiers的权限。这是通过使用在API Publisher界面的Tier Permissions菜单来设置的，如下图所示。在每一个tier,可以使用逗号分隔多个角色，设置为允许或拒绝设置的角色访问此tier。

Subscriber登录到API Store可以使用一个指定的，所在角色被允许访问的tier消费APIs。在API Store中，subscriber能看到一个基于subscriber所在角色过滤后的tiers列表，只有允许角色访问的tiers才会出现在这里。默认设置是允许所有人访问所有tiers。

6.1.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: 无访问限制。应用程序的默认设置。你可以将它设置为受限的。

6.1.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，知道这些限制。

6.1.4 IP-level throttling

基于IP的流量控制，可以通过客户端IP来限制客户端的请求数量（例如：一个客户端请求10次）。

1、 登录到管理控制台，单击Resources -> Browse菜单。

2、 在/_system/governance/apimgt/applicationdata目录下找到tiers.xml文件。

3、 添加你的策略。例如：以下策略只允IP为10.1.1.1的客户端每分钟调用1次API，允许其他IP地址的客户端每分钟调用2次API。策略配置如下：

<wsp:Policyxmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"

 

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

<throttle:MediatorThrottleAssertion>   

<wsp:Policy>           

<throttle:IDthrottle:type="IP">10.1.1.1</throttle:ID>           

<wsp:Policy>               

<throttle:Control>                   

<wsp:Policy>                       

<throttle:MaximumCount>1</throttle:MaximumCount>                       

<throttle:UnitTime>60000</throttle:UnitTime>                   

</wsp:Policy>               

</throttle:Control>          

</wsp:Policy>       

</wsp:Policy>

     

<wsp:Policy>           

<throttle:IDthrottle:type="IP">other</throttle:ID>           

<wsp:Policy>               

<throttle:Control>                   

<wsp:Policy>                       

<throttle:MaximumCount>2</throttle:MaximumCount>                       

<throttle:UnitTime>60000</throttle:UnitTime>                  

 </wsp:Policy>               

</throttle:Control>           

</wsp:Policy>       

</wsp:Policy>   

</throttle:MediatorThrottleAssertion></wsp:Policy>

6.2throttlingtiers工作原理

通过在3个层面定义的流量控制，最终才准许API调用请求经过统一的throttlingtiers输出到后端服务。

例如：两个用户使用Gold级别（每分钟20个请求）的流量控制订阅了一个API。他们都使用应用程序App1来进行订阅，App1也有一个流量控制，tier也设置成了每分钟20个请求。所有资源级别的流量控制是unlimited。在这个场景下，尽管用户可以每分钟调用20次API，但理论上又限制为每分钟发送10次请求。这是由于应用程序级别的每分钟20次请求的限制造成的。

7       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为处于不同角色中的用户工作的过程：

l  API creator和publisher角色可以看到在他们租户域的Store中的所有API，就算限制了访问的也能看见。这是因为这些角色在APIPublisher中有查看和编辑所有API的权限，因此，在Store中没有被限制。

l  匿名用户只能看见可见性设置为Public的APIs.

l  注册用户可以看见：

n  所有租户域下的public APIs。

n  在用户注册的租户域下的所有没有基于角色限制的、及分配了角色权限访问的所有APIs。

8       API documentationvisibility

所有与API相关的文档默认都是与API具有一样的visibilitylevel。换句话说，如果API是public，它的文档也就是所有用户（包括注册用户及匿名用户）都可以访问。如果要给文档启用另外的visibilitylevels，到<AM_HOME>/repository/conf/api-manager.xml文件中，取消注释掉的如下内容，设置为true。如下所示：

<APIPublisher>

  ....

  <EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels>

</APIPublisher>

然后登陆进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中的用户可以访问。

9       API resources

一个API是由一个或多个资源组成。每个资源处理特定类型的请求，类似于一个方法（函数）在一个较大的API中。

APIresources具有以下属性：

9.1 OAuth Scopes

参见OAuth Scopes章节。

9.2 URL Pattern

参见OAuth Scopes章节。

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="POST GET" url-mapping="/state/town/*">

<resource methods="POSTGET" uri-template="/{state}/{town}">

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中用于不同目的的配置和采集访问信息。

9.3 HTTP Verb

指定需要对资源执行的HTTP方法。这些方法可以是GET、POST、PUT、DELETE或OPTIONS。可以选择多个方法。

9.4 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分钟来刷新缓存。在这期间，服务从缓存返回旧的认证类型。如果你想改为立即返回，请在更改认证类型后重启服务。

9.5 小结

资源的参数缓存在APIGateway的资源缓存中。

一旦一个请求被资源接收，它将通过in-sequense中介处理。任何来自后端服务的响应消息被out-sequence处理。Fault sequences用于中介处理在sequences中可能发生的错误。默认的in-sequence、out-sequence和fault sequences在API发布时生成。

10 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禁止访问的错误，如下：

<ams:faultxmlns:ams="http://wso2.org/apimanager/security">

  <ams:code>900910</ams:code>

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

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

  </ams:description>

</ams:fault>

提示：调用通过scopes保护的API，需要通过Token API获取access token。而不是从API Store的My Subscriptions页面生成的token。

11 API templates

API template是使用XML来描述的，保存在<APIM_HOME>/repository/resources/api_templates/velocity_template.xml文件中。这个文件是API Manager的默认文件。可以修改这个默认的模板来改变所有已创建的API的synapse配置。

如果使用分布式方式部署的API Manager（即：Publisher、Store、Gateway、Key Manager组件运行在不同的JVM上），编辑Publisher节点的template。

12 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

注意以下几点：

l  通过API，支持以REST、SOAP方式将服务暴露给消费者。

l  不能调用在APIPublisher创建的使用OAuth保护的后端服务。在这种情况下，只能使用账户名、密码才能调用受保护的服务。

l  系统从<JAVA_HOME>/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>

l  如果两种类型的endpoints都定义了，会选择HTTPSendpoint作为这个服务器的endpoint。

提示：如果定义了安全的（HTTPS）endpoints，请在<APIM_HOME>/repository/conf/axis2/axis2.xml文件的HTTPS transport sender的配置处设置<parameter name="HostnameVerifier">元素的值为AllowAll：

<parameter name="HostnameVerifier">AllowAll</parameter>

如果不设置，服务器会抛出异常。

l  当通过PublisherUI(在Implement选项下)创建或更新Failoverendpoints时，需要进入每个endpoint的AdvancedOptions选项，为endpoint设置一套失败发生时的错误代码，设置InitialDuration的值为-1来去掉InitialDuration。

13 Sequences

在每个API调用时，会执行API Manager默认的mediation flow。有3个默认的sequences：in、out、fault。

14 Caching

关于响应消息的缓存，及在Gateway和Key Manager server调用API的缓存的配置信息，请查看缓存配置。