WSO2 APIM

快速开始

前置

• 了解HTTP协议基础知识
• 了解docker基础命令
• 使用环境装有docker；如何安装docker请参考Docker 教程 | 菜鸟教程

如何部署

这里只推荐docker容器部署的方式，本地运行war包请参考官方文档。

1. 首先拉取APIM的官方docker镜像；docker pull wso2/wso2am:4.1.0
2. 运行docker镜像；docker run -it -d -p 9443:9443 -p 8243:8243 --name apim wso2/wso2am:4.1.0
3. 查看容器启动日志，如果出现这样的日志，代表官方的APIM docker容器启动成功。

步骤 1 - 创建和发布 API

按照以下说明通过 WSO2 API-M 的发布者门户创建和发布 API。

1. 导航到发布者门户。https://localhost:9443/publisher
2. 登录方式admin/admin作为凭据。
3. 创建 API。让我们使用模拟 REST 服务从头开始创建 REST API。本次使用的服务为跨境贸易:http://integrated.io.superlucy.net/api/auth/oauth/pubKey
4. 从主屏幕中选择 REST API，然后单击从头开始。
5. 输入 API 详细信息。
6. 单击“创建并发布”。这将在开发人员门户上发布您的第一个 API，并将其部署到 API 网关上。现在，你有一个可供使用的 OAuth 2.0 安全 REST API。

步骤 2 - 订阅 API

按照以下说明订阅 API 并通过 WSO2 API-M 的开发人员门户生成密钥。

1. 导航到开发人员门户。https://localhost:9443/devportal已发布的 API 列在开发人员门户中，单击登录并输入admin/admin作为登录到开发人员门户的凭据。如下所示。
2. 注册 OAuth 2.0 应用程序。
   1. 单击屏幕左侧菜单栏上的Subscriptions
   2. 单击上方屏幕中的订阅和密钥生成向导。此向导将引导您完成 5 个步骤，这些步骤将注册将用于使用 API 的 OAuth 2.0 应用程序。
   3. 输入应用程序名称，然后单击下一步，而不更改任何其他默认值。后续重复下一步操作
   4. 在最后一步后，生成出的访问令牌，如下图，复制访问令牌后点击完成。

步骤 3 - 调用 API

按照以下说明使用生成的密钥调用之前创建的 API。

1. 单击左侧菜单栏上的Try Out。将列出 API 的资源。
2. 将之前复制的访问令牌粘贴到“访问令牌”字段中。如果忘记复制可以点击获取测试密钥获取一个测试令牌。
3. 单击 API 的资源以展开该资源，然后单击试用。单击执行。如果出现跨域问题或者404但是你接口配置的没有任何问题可以通过重启容器解决。或者直接脱离浏览器使用接口调试工具进行请求测试。

设计接口

创建 REST API

API 创建是将现有后端 API 实现链接到 API 发布者的过程，以便您可以管理和监控 API 的生命周期、文档、安全性、社区和订阅。或者，您可以在 API 发布服务器本身中以内联方式提供 API 实现。
按照以下说明使用基本流程创建 REST API：

1. 登录到 WSO2 API 发布服务器。https://localhost:9443/publisher
2. 从可用选项中选择“REST API”。
3. 单击从头开始。
4. 输入 API 详细信息。注意“创建和发布”选项仅在具有publisher权限的用户添加终结点的详细信息（可选字段）时显示。

   Name	PizaShack
   Version	1.0.0
   Content	/pizzashack
   endpoint	https://localhost:9443/am/sample/pizzashack/v1/api/

5. 单击创建以创建 API。如果单击“创建并发布”此时将显示新创建的 API 的概览页面。
6. 转到开发、门户配置，然后单击基本信息。

1. 配置API设计配置.
2. 添加标签，然后按回车键。让我们添加一个名为披萨的标签。信息标记可用于筛选出与特定搜索条件匹配的 API。最好添加说明 API 功能和用途的标记，以便订阅者可以根据标记搜索 API。
3. （可选）为“将此版本设为默认版本”选项选择“是”。当 API 是默认版本时会发生什么情况？
4. 单击保存。
5. 配置运行时配置。
   1. 单击“API 配置”部分下的“运行时”。传输级别安全性定义公开 API 的传输协议。
   2. 如果您希望将 API 可用性限制为仅一个传输（例如 HTTPS），请取消选中传输级别安全性复选框。默认情况下，HTTP 和 HTTPS 传输均处于选中状态。
6. 配置资源。默认情况下，API 将有五个资源作为 URL 模式。/*
   1. 单击“API 配置”部分下的“资源”。
   2. 按如下方式修改资源，然后单击保存以更新资源。
      1. 单击“删除”，如下所示，以删除所有现有资源。
      2. 从下拉列表中选择适当的 HTTP 请求方式，然后单击 （+） 添加新资源。新添加的资源显示如下。
      3. 展开创建的 GET 操作以添加“摘要”和“说明”和“操作治理”部分的详细信息。
         1. 为资源添加摘要和说明。
         2. 根据需要更新安全设置。
            • 如果要在不传递访问令牌的情况下使 API 的某些操作不受保护且可访问，请关闭安全设置。
            • 若要使整个 API 不受保护且无需访问令牌即可完全访问，请在 API 的所有操作中关闭安全设置。
         3. 如果需要，请使用“参数”部分添加资源参数。您可以根据添加的资源参数定义以下参数类型。

参数类型	描述
query	包含作为调用 URL 的一部分添加的字段，其中包含用于调用后端服务的数据。
header	包含区分大小写的名称，后跟冒号 （:)然后通过其值随请求一起携带附加信息，该请求定义了事务的操作参数。
cookie	操作还可以在 Cookie 标头中传递参数，如 .多个 cookie 参数在同一标头中发送，用分号和空格分隔。Cookie: name=value
body	任何类型的任意数量的数据都随 POST 消息一起发送。

9. （可选）查看 API 定义。单击“API 定义”。出现 PizzaShack API 的 OpenAPI 规范（又名 Swagger 定义）。

现在，您已成功创建并配置了 REST API。接下来，部署 API，测试 API，最后发布 API。

部署API

1. 登录到发布者。https://localhost:9443/publisher
2. 导航到部署部分，然后单击部署。当您没有任何现有修订时，“部署”页面将显示如下。当您至少有一个修订时，“部署”页面将显示如下。
3. 单击部署新修订。
4. （可选）提供修订的说明。
5. 选择要在其中部署 API 的 API 网关。
6. 单击部署。注意：不能部署超过 5 个修订。如果要在达到允许的最大修订数后部署新修订，则需要删除现有修订之一。

测试API

1. 登录到发布者。[https://localhost:9443/publisher](https://localhost:9443/publisher)
2. 单击要测试的 API。例如 PizzaShack
3. 转到测试，然后单击试用

4. 您可以通过单击“生成密钥”按钮来调用和测试 PizzaShack API，从而生成内部密钥。

5. 展开 GET 方法，单击“试用”，然后单击“执行”。

发布API

1. 登录到发布者。[https://localhost:9443/publisher](https://localhost:9443/publisher)
2. 单击处于CREATED状态的 API。例如 PizzaShack

3. 点击左侧菜单栏发布下的生命周期

左边为API的生命周期，分别为已创建、预发布、发布、锁定、弃用、退休，右边为发布需要满足的条件，如未满足会在右边提示哪些条件未满足。

在开发人员门户查看、调用API可以参考快速开始章节。

案例

设计、发布API

1. 登录到 WSO2 API 发布服务器。https://localhost:9443/publisher，按下图所示开始创建API

2. 输入API详细信息。

   Name	oauth
   Context	/oauth
   Version	1.0
   Endpoint	http://integrated.io.superlucy.net/api

3. 点击Create创建API，这样就拥有了一个已创建状态的API

4. 按下图依次点击左侧菜单栏配置API运行时参数

5. 配置请求头参数；配置API权限验证时使用的请求头验证字段为Proxy-Authorization，请注意API默认的是Authorization字段，我们日常开发的系统基本都是使用Authorization字段作为鉴权字段，APIM也是这样，所以我们需要改变APIM的默认字段为自定义字段；注意：如果配置了自定义鉴权字段则需要进行跨域配置。如下图所示。配置完成后点击保存。

6. 配置API接口
   1. 点击API配置下的资源菜单，添加如下所示的接口，pubKey：获取公钥，不需要目标系统权限；token：登陆接口，需要目标系统权限

2. 对token接口进行请求参数配置，最终如下图所示，配置完成点击保存
3. 对getUserInfo接口进行请求参数配置，最终如下图所示，配置完成点击保存
4. 进入发布菜单，进行接口的第一次发布

8. 进入API测试菜单，对pubKey接口进行测试，因为pubKey是不需要携带token的所以可以直接调通。

9. 进入API发布菜单进行API的发布操作，点击发布或者预发布按钮，发布接口到开发人员门户。

订阅、调用API

订阅API的步骤请参考快速开始。

调用API

1. 点击pubKey接口，复制生成的Curl导入到API调试工具，或者在API调试工具中手动新增接口。结果如下图所示。

2. 点击token接口，复制生成的Curl导入到API调试工具，或者在API调试工具中手动新增接口。填入相关参数，**Authorization:**Basic c3VwZXJsdWN5X3N5bmVyZ3k6c3luZXJneS0xcWF6LTJ3c3g=，如下图所示。
   1. 复制生成的Curl导入到API调试工具，或者在API调试工具中手动新增接口。结果如下图所示。
3. 复制token接口返回的token，作为getUserInfo接口的Authorization字段的值，填入接口相关参数如下图所示
   1. 复制生成的Curl导入到API调试工具，或者在API调试工具中手动新增接口。结果如下图所示。

常见问题

这里只阐述使用官方docker镜像运行APIM遇到的问题

1. 如果在接口测试的时候遇到CORS，也就是跨域问题，请检查API配置菜单内是否启用了自定义鉴权字段并且在CORS配置中也添加了鉴权字段，若这些都没有问题，则可以重启容器来解决跨域或者换API调试工具进行接口调用。
2. 如果在接口测试的时候遇到404，请重启容器解决问题。
3. 如果在接口测试的时候遇到错误代码900902，请检查API配置菜单内是否配置有错误信息提示的鉴权请求头，若配置没问题，则请重启容器已解决问题。