目录

技术概要:InterSystems API 管理器

本文档将向您介绍InterSystems API管理器(InterSystems API Manager ,IAM),解释了它的工作原理,并让您开始在自己的实例上探索它的功能。

InterSystems API管理器是如何工作的?

InterSystems API管理器是 InterSystems IRIS®数据平台的一个组件,它允许您利用由 InterSystems IRIS 应用程序暴露或消费的微服务和 API。作为 InterSystems IRIS的 服务器和应用程序之间的 API 网关(gateway),API 管理器使您能够更有效地监视和控制服务器端 API 和客户端应用程序之间的调用流量。 要了解有关 InterSystems API管理器的更多信息,您可以观看这个概述视频

试一试!

InterSystems API管理器(InterSystems API Manager ,IAM)是与 InterSystems IRIS 实例分开安装的。要获得自己的 IAM 安装包,您可以从 InterSystems WRC 软件分发(Software Distribution)网站下载 ,或者联系您的 InterSystems 销售工程师。安装包包括一个脚本(iam-setup),用于设置 IAM 并将它与您的 InterSystems IRIS 实例连接。 这个练习假定您有 InterSystems IRIS 和 IAM 的实例,并且已经运行了安装脚本来连接它们。本练习使用 IAM 2.3 版本进行展示。

在 InterSystems IRIS 中设置 REST API

从位于 https://github.com/intersystems/FirstLook-IAM 的 GitHub 存储库中,将以下内容导入 InterSystems IRIS:
  1. /cls/cmAPI 包括使用 API 管理服务生成的三个类文件,以及一个coffeemaker对象定义:
    • impl.cls
    • disp.cls
    • spec.cls
    • coffeemaker.cls

要导入,请打开 InterSystems IRIS 管理门户(Management Portal),并导航到 Classes 页面(System Explorer(系统资源管理器) > Classes(类));如果您不在 USER 命名空间中,请使用左边的选择器来更改为它,如下图所示:

选择上面列出的四个类并点击 Import(导入)。这将 REST API 导入 InterSystems IRIS,同时导入相应的类,应用程序将使用这些类访问存储在数据库中的coffermakers集合。

  1. /gbl/coffeemakers.gof。

通过进入管理门户(Management Portal),并点击 System Explorer(系统资源管理器)> Globals > Import(导入)来导入。查找 coffeemakers.gof。导入到 User.cmAPI.coffeemaker 模式。

接下来,设置一个 Web 应用程序(Web Application),指向您刚刚导入的 REST 类。Web 应用程序层为自定义和安全提供了额外的机会。在管理门户(Management Portal)中,选择 System Administration(系统管理) > Security(安全) > Applications(应用程序)> Web Applications(Web 应用程序)。点击 Create New Web Application(新建Web 应用程序) 并填写以下设置:

在 IAM 中为您的 REST API 创建服务

正如您在 IAM 概述视频中所看到的,在 IAM 工作流中,有三个主要组件在发挥作用------消费者(Consumers)、路由(Route)和服务(Service)。IAM 中的服务是为您存在于 InterSystems IRIS 中的 API 创建的。在这种情况下,我们将为您的coffeemaker API 创建一个服务。

您从 WRC 下载的 IAM 包还包括一个脚本(iam-test),用于设置示例服务和路由。如果您运行了这个脚本,您将能够查看 test-iris 服务。

我们将取得类似的结果,使用 IAM 门户添加您的Coffeemakers服务。

iam-setup.sh是用来启动 IAM 的,可以通过输入iam-setup.sh 脚本中指定的门户的 URL 来启动 IAM 管理门户(management portal)。默认情况下,URL 是:

http://localhost:8002

选择 default Workspace(默认工作区)。如果默认工作区不可见,而且管理门户(Management Portal)似乎是空的,那么可能是您没有输入 iam-setup.sh 定义的确切 URL。

选择 API Gateway(API 网关) 中的 Services(服务),并选择 New Service(新的服务)。请按以下方式填写表格:

一旦创建了服务,您就可以查看服务,并需要创建路由。

在 IAM 中创建路由

当您在查看服务时,选择 "添加路由(Add a Route)"。请按以下方式填写表格:

一旦创建了路由,您将通过从 REST 客户端进行简单的 API 调用来测试您的路由和服务。

从 REST 客户端调用您的 API

使用 REST 客户端------可以使用Postman 或来自 Google Chrome 的高级 REST 客户端(Advanced REST Client)------在 InterSystems IRIS 中对您的咖啡机(Coffeemakers) API 进行一个简单的 API 调用。要做到这一点,创建一个请求 URL,其中包括您的 IAM 实例的 IP 地址和端口号,以及您的服务的路径和请求的端点。请务必使用用户名和密码授权您的请求。下面是一个示例;注意,默认情况下,IAM 处理 8000 端口上的代理请求。例如:

POST http://localhost:8000/rest/coffeemakerapp/coffeemakers

一旦您成功地进行了调用,您可以导航回您的 IAM 仪表板(Dashboard),查看来自所进行的调用的统计数据和其他信息。从这个仪表板上,您可以看到许多不同的信息集,这些信息将帮助您监控和控制客户端应用程序和 InterSystems IRIS 内的服务之间的流量。

添加速率限制插件

有效地监测您的 API 流量是有益的,但仅限于使用该信息适当地控制和优化流量。IAM 使您能够使用一些不同的插件来提高您控制客户端和 API 之间流量的能力。

在 IAM 管理门户(Management Portal)中,选择 API Gateway(API 网关) 中的 Plugins(插件) ,并选择 New Plugin(新的插件)。在 Traffic Control(流量控制) 类别中,找到 Rate Limiting(速率限制) 插件,并选择 Enable(启用)

在这个插件的配置屏幕上:

试一试!

您可以通过返回 REST 客户端并进行示例调用来测试这个速率限制插件。客户端超过限制后,它将得到一个 429 返回错误,并带有"超过 API 速率限制"的信息

添加您的 REST 规范到 IAM

REST 开发的最佳实践方法是规范优先,因此很可能您已经有了自己的 REST 规范。对于这个练习,您可以使用您从 github 下载 FirstLook-IAM 存储库时,spec 目录下的 swagger_100419.json 文件。您也可以直接从 GitHub 存储库的 spec 文件夹中下载 JSON 规范。

https://github.com/intersystems/FirstLook-IAM/blob/master/spec/swagger_100419.json

注意: 有关记录和管理 REST API 规范的更多信息,请参见 Creating REST Services(《创建 REST 服务》)中的 Discovering and Documenting REST APIs(发现和记录 REST API)。

一旦下载,您就能将您的规范添加到 IAM 中:

  1. 从 IAM 管理门户(management portal),选择 Workspaces(工作区) 标签并选择默认工作区。
  2. 为咖啡机服务(CoffeemakerService)服务选择 View(查看)
  3. Documents(文档) 区域(面板的底部)选择 Add a document(添加一个文档)到这个服务。
  4. 点击下面的文件选择器文本框 Or upload a new spec instead...(或者上传一个新的规范代替...) ,然后选择您下载的 swagger_100419.json 文件。

您现在可以查看咖啡机服务(CoffeemakerService)的 OpenAPI 规范。外部开发者也可以访问这个规范,这允许他们开发对它的 REST 调用。由于 curl 命令没有指定正确的服务,所以 "试一试(Try it Out)"选项将无法工作。

了解有关 InterSystems API管理器 的更多信息

注意: 如果没有设置默认的开发门户(dev portal),选择 Set up Dev Portal(设置开发门户)。如果默认的开发门户(Dev Portal)被禁用,选择 Enable Developer Portal(启用开发门户)。它可能需要几分钟的时间来设置。

了解有关 InterSystems API Manager 的更多信息

InterSystems 提供了一些参考资料来了解有关 IAM 的更多信息:

如果您想了解有关如何开发咖啡机服务(CoffeemakerService) REST 服务的更多详细信息,请参见 《技术概要:在 InterSystems 产品中开发 REST 接口》。