第十七章 源代码文件 REST API 教程（二）

获取在命名空间中定义的源代码文件

要获取有关命名空间中源代码文件的信息：

• 首先，使用 GetDocNames 方法获取文件的名称。
• 然后用GetDoc 方法获取一个文件的内容，也可以用GetDocs 方法获取多个文件的内容。
• 如果要提高应用程序的网络效率，可以保留源代码文件的名称和内容的本地缓存，并使用 GetModifiedDocNames 方法仅获取内容发生变化的源代码文件的名称或使用带有 If-None-Match HTTP 标头的 GetDoc 方法。

GetDocNames 方法返回映射到命名空间的所有数据库中的所有源代码文件的名称。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "name": "%Api.DocDB.cls",
        "cat": "CLS",
        "ts": "2016-08-03 20:01:42.000",
        "upd": true,
        "db": "IRISLIB",
        "gen": false
      },
      ...

第十六章 源代码文件 REST API 教程（一）

本章提供了一个简短的教程，通过一系列示例演示如何使用源代码文件 REST API。它包含以下部分：

API 基础

Atelier 用于访问 IRIS 源代码文件的 API 使用 REST 架构风格。 REST 的名字来源于“Representational State Transfer”。与许多 REST API 一样 IRIS 源代码文件 REST API 使用 HTTP GET、POST、PUT、DELETE 和 HEAD 方法，并将 JSON 用于传入和传出消息体。

要调用 API 方法，需要了解以下内容：

• HTTP 方法——它是以下之一：GET、POST、PUT、DELETE 或 HEAD。
• HTTP 标头——为调用提供上下文信息。此 API 中使用的 HEADERS 包括：
  • 授权，它提供对服务器的访问。除非安装了具有最低安全性的服务器，否则需要提供用户名和密码才能访问 API。
  • Content-Type application/json，指定入站负载以 JSON 格式提供。必须为所有 POST 和 PUT 方法指定此标头。
  • If-None-Match，它允许 GetDoc 或 PutDoc 调用检查源代码文件自上次访问以来是否被修改。
• URL - URL 由以下部分组成：
  • http://
  • server-name:port

第十四章 手动创建 REST 服务（二）

指定数据格式

可以定义 REST 服务以处理不同格式的数据，例如 JSON、XML、文本或 CSV。 REST 调用可以通过在 HTTP 请求中指定 ContentType 元素来指定它期望发送的数据的形式，并且可以通过在 HTTP 请求中指定 Accept 元素来请求返回数据格式。

在 DocServer 示例中，GetNamespaces() 方法检查 REST 调用是否使用以下内容请求 JSON 数据：

If $Get(%request.CgiEnvs("HTTP_ACCEPT"))="application/json"

本地化 REST 服务

REST 服务返回的任何字符串值都可以本地化，以便服务器以不同语言存储多个版本的字符串。然后，当服务接收到包含 HTTPAccept-Language 标头的 HTTP 请求时，服务会使用相应版本的字符串进行响应。

本地化 REST 服务：

1. 在实现代码中，不要包含硬编码的文字字符串，而是使用 $$$Text 宏的实例，为宏参数提供如下值：

• 默认字符串
• （可选）该字符串所属的域（将字符串分组到域中时，本地化更易于管理）
• （可选）默认字符串的语言代码

例如，而不是这个：

 set returnvalue="Hello world"

 set returnvalue=$$$TEXT("Hello

第十三章 手动创建 REST 服务（一）

本附录描述了如何通过继承 %CSP.REST 类来手动创建 REST 服务；此过程创建了一个手动编码的 REST 服务，它不能与所有 API 管理工具一起使用。

手动创建 REST 服务的基础知识

要手动定义 REST 服务，请执行以下操作：

• 创建一个 REST 服务类 — %CSP.REST 的子类。在子类中：
  • 定义一个 URL 映射，该映射指定为 REST URL 和 HTTP 方法执行的 IRIS 方法。
  • 可以选择指定 UseSession 参数。此参数控制每个 REST 调用是在其自己的 Web 会话下执行还是与其他 REST 调用共享一个会话。
  • （可选）覆盖错误处理方法。

如果想将实现代码与调度代码分开，可以在单独的类中定义实现 REST 服务的方法，并从 URL 映射中调用这些方法。

• 定义一个使用 REST 服务类作为其调度类的 Web 应用程序。

要定义 Web 应用程序及其安全性，请转至 Web 应用程序页面（单击System Administration > Security > Applications > Web Applications）。

定义 Web 应用程序时，将 Dispatch Class 设置为 REST 服务类的名称。

此外，将应用程序的名称指定为 REST 调用的 URL 的第一部分。示例名称为 /cs

第十二章 使用中的 OpenAPI 属性

本附录列出了 API 管理工具在生成 REST 服务类时使用的 OpenAPI 2.0 规范的属性。此处未列出的属性将被忽略。有几个扩展属性；它们的名称以 x-ISC 开头。

Swagger

• basePath

• consumes

• host

• produces

• definitions (请注意，API 管理工具在生成代码时不使用 Schema 对象的任何属性)

• parameters (for details, see “Parameter Object”)

• paths (for details, see “Path Item Object”)

• info (for details, see “Info Object”)

• swagger (must be "2.0")

有关这些属性的详细信息，请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object。

Info Object

• title

• description

• x-ISC_RequiredResource (访问 REST 服务的任何端点所需的已定义资源及其访问模式 (resource:mode) 的逗号分隔列表)

• version

第十一章 /api/mgmnt/ API 参考

此参考列出了 /api/mgmnt/ 服务中的端点，所有这些端点都适用于较新的 REST 服务。下表总结了端点并指出它们是否也适用于手动编码的 REST 服务。

第十章 发现和记录 REST API

本章讨论如何发现实例上可用的 REST 服务以及如何为 REST 服务生成文档。

使用 /api/mgmnt 服务发现 REST 服务

/api/mgmnt 服务包括可用于发现 REST 服务类和启用 REST 的 Web 应用程序的调用。

发现 REST 服务

要使用 /api/mgmnt 服务来发现实例上可用的 REST 服务，请使用以下 REST 调用：

• 对于 HTTP 操作，选择或指定 GET。
• 对于 URL，请指定以下形式的 URL：

http://localhost:52773/api/mgmnt/v2/

或者，如果只想检查一个命名空间：

http://localhost:52773/api/mgmnt/v2/:namespace

其中 localhost 是服务器的名称，52773 是运行 IRIS 的 Web 服务器端口，命名空间是要检查的命名空间。

（请注意，这些调用会忽略手动编码的 REST 服务。要发现手动编码的 REST 应用程序，请使用调用 GET /api/mgmnt/ 和 GET /api/mgmnt/:v1/:namespace/restapps。）

如果调用成功，IRIS 以 JSON 格式返回一个列出 REST 服务的数组。例如：

[
  {
    "name": "%Api.Mgmnt.v2",

第九章 REST 服务安全

如果 REST 服务正在访问机密数据，应该对服务使用身份验证。如果需要为不同的用户提供不同级别的访问权限，还要指定端点所需的权限。

为 REST 服务设置身份验证

可以对 IRIS REST 服务使用以下任何形式的身份验证：

• HTTP 身份验证标头 — 这是 REST 服务的推荐身份验证形式。
• Web 会话身份验证 — 其中用户名和密码在 URL 中的问号后面指定。
• OAuth 2.0 身份验证 - 请参阅以下小节。

REST 应用程序和 OAuth 2.0

要通过 OAuth 2.0 对 REST 应用程序进行身份验证，请执行以下所有操作：

• 将包含 REST 应用程序的资源服务器配置为 OAuth 2.0 资源服务器。
• 允许对 %Service.CSP 进行委派身份验证。
• 确保将 Web 应用程序（用于 REST 应用程序）配置为使用委托身份验证。
• 在 %SYS 命名空间中创建一个名为 ZAUTHENTICATE 的例程。 提供了一个示例例程 REST.ZAUTHENTICATE.mac，可以复制和修改它。此例程是 GitHub (https://github.com/intersystems/Samples-Security) 上 Samples-Security 示例的一部分。可以按照“下载用于 IRIS 的示例”中的说明下载整个示例，但在 GitHub

第七章 在 REST 服务中支持 CORS

概述

本节提供 CORS 的概述以及如何在 IRIS REST 服务中启用 CORS 的概述。

CORS 简介

跨域资源共享 (CORS) 允许在另一个域中运行的脚本访问服务。

通常，当浏览器从一个域运行脚本时，它允许对同一个域进行 XMLHttpRequest 调用，但在对另一个域进行调用时不允许它们。此浏览器行为限制某人创建可滥用机密数据的恶意脚本。恶意脚本可能允许用户使用授予用户的权限访问另一个域中的信息，但随后在用户不知道的情况下，将机密信息用于其他用途。为了避免这种安全问题，浏览器一般不允许这种跨域调用。

在不使用跨域资源共享 (CORS) 的情况下，具有访问 REST 服务的脚本的网页通常必须与提供 REST 服务的服务器位于同一域中。在某些环境中，将带有脚本的网页与提供 REST 服务的服务器放在不同的域中是很有用的。 CORS 支持这种安排。

下面提供了浏览器如何使用 CORS 处理 XMLHttpRequest 的简化描述：

1. 域 DomOne 中的网页中的脚本包含对 DomTwo 域中的IRIS REST 服务的 XMLHttpRequest。 XMLHttpRequest 具有 CORS 的自定义标头。
2. 用户查看此网页并运行脚本。用户的浏览器检测到与包含网页的域不同的域的 XMLHttpRequest。
3. 用户的浏览器向 IRIS

第六章 修改规范（SPEC）类

概述

下表列出了修改规范类的原因并简要总结了所需的更改：

无论何时编译规范类，编译器都会在同一个包中重新生成调度类并更新实现类。

覆盖内容类型、响应字符集或输入流处理

只需将类参数添加到规范类并重新编译，就可以覆盖 REST 服务的几个关键方面。

• 默认情况下，REST 服务需要 application/json 内容类型。要覆盖它，请将以下内容添加到规范类：

Parameter CONTENTTYPE = "some-content-type";

其中 some-content-type 是 MIME 内容类型。

• 默认情况下，REST 服务的响应消息采用 UTF-8 格式。要覆盖它，请将以下内容添加到规范类：

Parameter CHARSET =

第五章 修改实现（IMPL）类

本章讨论如何修改 REST 服务的实现类。

初始方法定义

实现类最初包含存根方法，如下例所示：

/// Returns all pets from the system that the user has access to<br/>
/// The method arguments hold values for:<br/>
///     tags, tags to filter by<br/>
///     limit, maximum number of results to return<br/>
ClassMethod findPets(tags As %ListOfDataTypes(ELEMENTTYPE="%String"), limit As %Integer) As %Stream.Object
{
    //(Place business logic here)
    //Do ..%SetStatusCode(<HTTP_status_code>)
    //Do ..%SetHeader(<name>,<value>)
    //Quit (Place response here) ; response may be a string, stream or dynamic object
}

在每种情况下，这些存根方法都具

第四章 使用 %REST.API 类创建 REST 服务

本章介绍如何使用 %REST.API 类来创建、更新和删除 REST 服务。

使用 %REST.API 类创建或更新 REST 服务

创建 REST 服务的推荐方法是从 REST 服务的 OpenAPI 2.0 规范开始，并使用它来生成 REST 服务类。要使用 %REST.API 类执行此操作：

1. 获取 REST 服务的 OpenAPI 2.0 规范，采用 JSON 格式，并将规范保存为文件。该文件必须是 UTF-8 编码的。
2. 在要定义 REST 服务的命名空间中，使用该文件创建 %DynamicObject 的实例。
3. 然后调用 %REST.API 类的 CreateApplication() 方法。此方法具有以下签名：

classmethod CreateApplication(applicationName As %String, 
                              swagger As %DynamicObject = "", 
                              ByRef features, 
                              Output newApplication As %Boolean,

第三章 使用 ^%REST 例程创建 REST 服务

本章介绍如何使用 ^%REST 例程创建和删除 REST 服务。

提示：还可以使用此例程更新REST服务；只需删除REST服务，然后重新创建它。

使用^%REST例程

^%REST例程是一个简单的命令行界面。在任何提示下，可以输入以下答案：

• ^ - 使例程跳回上一个问题。
• ? - 使例程显示一条列出所有当前选项的消息。
• q或quit - 结束例程。

此外，每个问题都会在括号中显示该问题的默认答案。

使用^%REST例程创建REST服务

创建REST服务的推荐方法是从REST服务的OpenAPI2.0规范开始，并使用该规范生成REST服务类。要使用^%REST例程执行此操作：

1. 获取JSON格式的REST服务的OpenAPI 2.0规范。将规范另存为文件或记下可访问规范的URL。
2. 在终端中，更改到要在其中定义REST服务的名称空间。
3. 输入以下命令以启动^%REST例程：

do ^%REST

4. 在第一个提示符处，输入 REST 服务的名称。该名称用作生成类的包名；使用有效的包名。如果想使用名称列表、l、quit 或 q（在任何情况下都是变体），请将名称用双引号括起来。例如："list"
5. 在下一个提示符处，输入 Y（不区分大小写）以确认您要创建此服务。

然后，该例程会提示输入要使用的 OpenAPI 2.0 规范的位置。输入完整路径名或 URL。

第一章 创建 REST 服务简介

本文介绍 IRIS® 中的 REST 和 REST 服务。

REST 简介

REST 命名自“Representational State Transfer”，具有以下属性：

• REST 是一种架构风格，而不是一种格式。尽管 REST 经常使用 HTTP 来传输消息并使用 JSON 来传递数据，但也可以将数据作为 XML 或纯文本传递。 REST 利用现有的 Web 标准，例如 HTTP、URL、XML 和 JSON。
• REST 是面向资源的。通常，资源由 URL 标识并使用基于 HTTP 方法的操作，例如 GET、POST、PUT 和 DELETE。
• REST 通常有少量开销。虽然它可以使用 XML 来描述数据，但它更常用的是 JSON，它是一种轻量级的数据包装器。 JSON 使用标签标识数据，但标签没有在正式的模式定义中指定，也没有明确的数据类型。

REST 服务简介

在 IRIS 2019.2 及更高版本中定义 REST 接口有两种方法：

• 规范优先定义——首先创建一个 OpenAPI 2.0 规范，然后使用 API 管理工具生成 REST 接口的代码。
• 手动编码 REST 接口。

使用规范优先的定义，REST 服务正式由以下组件组成：

• 规范类（%REST.Spec 的子类）。此类包含 REST 服务的 OpenAPI 2.0 规范。

在检查我们的^pButtons（在IRIS中改名为^SystemPerformance）性能监控工具的文档时，一位客户告诉我。"我理解所有内容，但我希望它能更简单......更容易定义配置文件，管理它们等等"。

在这次会议之后，我认为尝试为其提供一些更简单的人机界面是一个不错的试验。

这方面的第一步是在现有的pButtons例程上包裹一个基于类的API。

我还能够添加一些更多的 "功能"，比如显示当前正在运行的配置文件，它们剩余的运行时间，以前运行的进程等等。

下一步是在这个API的基础上添加一个REST API类。

有了这个工件（pButtons REST API），人们就可以在上面建立一个比较时髦的用户界面。

举个🌰： -

本文向你推荐一些使用IRIS创建REST API应用程序的模式。

注：所有源代码在https://github.com/yurimarx/movie

类模式到REST应用

首先，请看我对创建IRIS API应用程序所需类的建议:

• IRISRESTApplication: CSP.REST 类会作为中央控制者来控制业务服务处理的所有REST请求和响应.
• BusinessService: 具有业务主题的类实现。它可以使用一个或多个持久化域类来持久化和查询业务主题要求的数据。
• Persistent Domain: 管理SQL表的持久化类.

环境准备

• VSCode;
• Docker Desktop;
• InterSystems ObjectScript Extension Pack.

示例应用的类图

我将创建一个电影目录应用程序来演示文章中建议的模式:

Note: 感谢IRIS API 模版应用 https://openexchange.intersystems.com/package/iris-rest-api-template . 这是本教程的基础.

搭建样本应用

1. 在你的文件系统中创建一个movie文件夹。在一个新的VSCode窗口中打开这个文件夹。

2. 在movie 文件夹中创建 Dockerfile 文件来在Docker container实例中运行IRIS社区版. 内容:

REST是一种架构风格，而不是一种格式。尽管REST经常使用HTTP来传输消息，使用JSON来传递数据，但你也可以用XML或纯文本来传递数据。REST利用了现有的网络标准，如HTTP、URL、XML和JSON。

虽然它可以使用XML来描述数据，但它更常使用JSON，这是一个轻量级的数据封装器。

InterSystems REST服务

InterSystems REST服务由以下组件组成：

规范类（%REST.Spec的一个子类）：这个类包含了REST服务的OpenAPI 2.0规范（Swagger）。InterSystems支持几个扩展属性，你可以在规范中使用。

调度类（%CSP.REST的一个子类）：这个类负责接收HTTP请求并在实现类中调用合适的方法。

实现类（%REST.Impl的子类）：这个类定义了实现REST调用的方法。

Web应用程序：它通过InterSystems Web Gateway提供对REST服务的访问。

使用API 管理工具创建REST服务 - 基于 OpenAPI 2.0规范

/api/mgmnt/

可以使用/api/mgmnt服务来创建、更新和删除REST服务。

1. 使用/api/mgmnt创建 .disp .impl 和 .spec 类

使用http://localhost:52773/api/mgmnt/v2/namespace/myapp

注意:

大家好!

InterSystems IRIS有一个叫做互操作性Interoperability的菜单。

它提供了轻松创建系统集成的机制（适配器、记录图、BPM、数据转换等），因此不同的系统可以轻松地连接起来。

在数据中继过程中可以包括各种操作，比如：为了连接那些通常不连接的系统，可以根据目的系统的规格要求来接收（或发送）数据。另外，在发送数据之前，可以从另一个系统获取和添加信息。以及，信息可以从数据库（IRIS或其他）获取和更新。

为此，我们会撰写一系列的文章，将讨论以下主题，同时看一下示例代码，以帮助你了解它是如何工作的，以及在用互操作性整合系统时需要什么样的开发。

* How it works 它是如何工作的
* What a Production is 什么是Production ?
* Message 消息
* Component Creation 组件的创建

* 1）Business Operations  业务操作

*2）Business Processes 业务流程
*3） Business Services 业务服务

  首先，介绍一下我们在这个系列中要使用的案例。

 一家经营着一个购物网站的公司，目前正在改变其产品信息的显示顺序，以配合季节的变化。

对于那些在某种程度上需要测试ECP的水平可扩展性（计算能力和/或用户和进程的并发性），但又懒得建立环境、配置服务器节点等的人来说，我刚刚在Open Exchange上发布了OPNEx-ECP部署的应用/示例。 

可以使用内嵌REST API用描述文件生成REST服务

请求消息如下：

POST： http://[YourServer]/api/mgmnt/v2/INTEROP/cmAPI

Body： API 描述文件，例如下面的Json文件
Basic Authorization Username: 用户名

Basic Authorization Password: 密码

Content-Type Header:application/json

** 注意**：调用接口前，需要创建相应命名空间，本示例为INTEROP

API 描述文件：

{
 "swagger": "2.0",
 "info": {
   "description": "An API for coffee sales using InterSystems IRIS",
   "version": "1.0.0",
   "title": "Coffee Maker API",
   "license": {
     "name": "Apache 2.0",
     "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  }
},
 "schemes": [
   "https"
],
 "paths": {

当前医院面临更多互联互通需求，如预约挂号与分级诊疗、检验结果共享、医联体信息化、监管数据上报、临床辅助决策支持等，都需要对多源数据进行集成与整合。医疗机构内部和跨机构数据交换与共享，对互联互通提出新的要求。HL7 FHIR是国际上医疗行业实现数据交换和信息共享的标准之一，正在快速得到医疗行业广泛关注。InterSystems中国技术总监乔鹏在视频中分享了FHIR标准与国际互联互通的一些实践经验。

国际互联互通的需求是在不断增长，这跟咱们国内的情况是非常类似的。这些年美国在互联互通领域的政策跟实践还是不少的，比如大家可能听到过包括“有意义的使用（Meaningful Use）”，“21世纪治愈法案（21st Century Cures Act）”，还有更多的政策上的驱动。这里先介绍一下“有意义的使用（Meaningful Use）”。

回过头来，业务场景都是千人千面的， FHIR怎么能够用一个标准涵盖尽可能多的用例？HL7吸收了V3的教训，在V3里面不成功的、或者说采纳度比较低的一个原因就V3试图穷举所有用例，由HL7组织自己来规范这些用例。这个是蛮沉重的教训，这也是V3的方法论虽然好，但是这套实施的路线在国际上有很大障碍的原因。

FHIR是快速医疗互操作资源（Fast Healthcare Interoperability Resources）的缩写，所以FHIR的核心是资源模型。它的颗粒度和结构都优于之前的V2 、V3、CDA标准，而且能够灵活扩展。另外一个优势就是它的API，它不仅提供了针对于资源模型本身的原子化的CRUD（创建、读取、更新、删除的这样一些原子化操作），而且提供了查询这种更复杂操作的能力，同样API是可以扩展的。

在国际上有很多互操作标准的开发组织，在我们医院信息化、医疗信息化领域有40多个标准开发组织，最广为人知的就是HL7国际、IHE，当然SNOMED也是，它开发的是行业术语跟语义的标准。

实现互通的方式方法有很多种，我们通常会见到4种：消息交换、文档交换、服务和 API。

在医疗行业要实现互操作，应该要达到语义级别。只有达到语义级别才能保障医疗信息的准确和医疗行为的安全。而要达到语义级别，我们需要基于标准。

什么是互联互通？我们所说的互联互通其实就是国际上的互操作性，HIMSS对于互操作性定义的是：不同的信息系统、设备、应用系统之间、程序之间，在机构区域和国家边界之内，以及跨机构、区域和国家边界，以协调的方式来访问交换集成和协作使用数据的能力。

大家好！

InterSystems IRIS 有一个名为 Interoperability（互操作性）的菜单。

它提供了轻松创建系统集成（适配器、记录映射、BPM、数据转换等）的机制，因此可以轻松连接不同的系统。

数据中继过程中可以包括各种操作，例如：为了连接没有正常连接的系统，可以根据目标系统的规范来接收（或发送）数据。 此外，在发送数据之前，可以从其他系统获取和添加信息。 还可以从数据库（IRIS 等）获取和更新信息。

在本系列文章中，我们将讨论以下主题，同时查看 示例代码 以帮助您了解工作原理以及在系统中集成互操作性时需要进行哪种开发。

• 工作原理
• 什么是Production
• 消息
• 组件创建
  • 业务操作
  • 业务流程
  • 业务服务

首先，我介绍一下我们将在本系列文章中使用的案例研究。

某公司运营着一个购物网站，他们正在更改产品信息的显示顺序以配合季节变化。
但是，有些商品无论季节如何都能卖得很好，而有些商品在意料之外的时间卖出，这不符合当前的显示顺序更改规则，
因此，我们研究了按照当天的温度而不是季节来更改显示顺序的可能性。 调查购买产品时的温度变得非常必要。
由于可以使用外部 Web API 来查询天气信息，因此我们计划收集购买时的天气信息，并将其记录在后面的审核数据库中。

案例非常简单，但您需要使用“外部 Web API”来收集信息，并且需要将获得的信息和购买信息结合起来记录在数据库中。

具体

InterSystems API Manager (IAM) 版本1.5已正式发布。

IAM容器，包括从原有IAM版本升级的所有相关工件, 现在可以在 WRC 软件发布网址 组件区下载。

该版本的小版本号是 IAM 1.5.0.9-4。

InterSystems API Manager 1.5 使管理API通讯、与你的环境集成、加载API用户更加容易。它包含很多新特性，包括:

• 改进的用户体验
• 新的开发者门户工具
• 对Kafka connectivity的支持

这个版本基于Kong Enterprise version 1.5.0.9。之前的IAM版本包括一个贴牌版本的Kong Enterprise, 在本版本中的Kong Enterprise不再贴牌。 这个变化让我们可以更快的节奏带给您新的版本，并更有效地利用Kong提供的文档和其它资源。

请在 这里 查看IAM 1.5 的文档。这个文档仅说明IAM特殊的元素。产品中的文档链接直接打开Kong Enterprise的文档。

从IAM 0.34-1 升级需要通过3个中间版本累积升级，在 文档中有详细的说明。

IAM 仅以OCI (Open Container Initiative) 或 Docker 容器格式发放。容器镜像可运行在Linux x86-64 和 Linux ARM64的OCI 兼容的运行引擎上, 详情请参考