第十八章 源代码文件 REST API 教程（三）

编译文件

Compile 方法编译传入 JSON 数组中名称指定的源代码文件。例如，要编译 xyz.mac，请发布以下内容：

http://localhost:52773/api/atelier/v1/INVENTORY/action/compile

使用以下 JSON 消息：

["xyz.mac"]

该方法返回：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
    "",
    "Compilation started on 08/14/2016 15:25:20 with qualifiers 'cuk'",
    "xyz.int is up to date. Compile of this item skipped.",
    "Compilation finished successfully in 0.008s."
  ],
  "result": {
    "content": []
  }
}

对于一些源代码文件，例如类，Compile 在返回的内容中返回存储信息。

删除文件

DeleteDoc 方法删除 URL 中指定的文件。

第十七章 源代码文件 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 调用检查源代码文件自上次访问以来是否被修改。

推荐一篇文章，南方医院HIS系统的更换与建设探索！

第十五章 源代码文件 REST API 简介

源代码文件 REST API 简介

此 REST API 提供对源代码文件的访问。我们开发此 API 是为了允许 Atelier（我们基于 Eclipse 的 IDE）访问 IRIS 服务器上的 IRIS 代码文件。可以使用 API 执行访问 IRIS 代码文件所需的操作。这些行动包括：

• 获取 IRIS 实例上可用的命名空间
• 查找命名空间中定义的类定义和例程
• 获取类和例程的文本定义
• 更新类定义或例程
• 创建新的类定义或例程
• 删除类定义或例程
• 编译 IRIS 类或例程
• 通过对表执行 SQL 查询来发现 IRIS 环境的属性

这些操作提供了访问 IRIS 源代码文件的机制。为了创建 IRIS 开发环境，应该了解此 API 并全面了解 IRIS 源代码文件如何在 IRIS 中使用。

这是一个特殊用途的 API。如果正在创建开发环境或处理类似的应用程序，例如类浏览器，可能会发现此 API 很有用。但是，它不是用于访问 IRIS 对象的通用 REST API。

本文档描述了 IRIS 源代码文件 REST API 的版本 1 和 2。 IRIS 的未来版本可能支持此 REST API 的更高版本，提供额外的调用，但将始终能够调用早期版本。版本 1 的 API 在 URL 中包含 /v1/，版本 2的 API 包含 /v2/。

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

指定数据格式

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

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

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

本地化 REST 服务

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

第十三章 手动创建 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 的第一部分。

第十二章 使用中的 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。

第十一章 /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.

第九章 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 示例的一部分。

第七章 在 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。

第六章 修改规范（SPEC）类

概述

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

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

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

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

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

Parameter CONTENTTYPE = "some-content-type";

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

• 默认情况下，REST 服务的响应消息采用 UTF-8 格式。

第五章 修改实现（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 .

第四章 使用 %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() 方法。

第三章 使用 ^%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。

第二章 使用 /api/mgmnt/ 服务

本章介绍如何使用 /api/mgmnt 服务来创建、更新和删除 REST 服务。

/api/mgmnt 服务还提供了可用于发现和记录 Web 服务的选项，如本书后面所述。

使用 /api/mgmnt 服务创建 REST 服务

创建 REST 服务的推荐方法是为 REST 服务创建 OpenAPI 2.0（也称为 Swagger）描述，并使用它来生成 REST 服务类。如果您正在实现由第三方定义的 REST 服务，他们可能会提供此 OpenAPI 2.0 描述。有关 OpenAPI 2.0 描述格式的详细信息，请参阅 OpenAPI 2.0 规范。以下主题描述了如何使用 /api/mgmnt 服务来执行此操作。

使用 /api/mgmnt 服务生成类

第一步，生成 REST 服务类，如下所示：

1. 以 JSON 格式创建或获取 REST 服务的 OpenAPI 2.0 描述。
2. 获取 REST 测试工具，例如 PostMan (https://www.getpostman.com/)。
3. 在测试工具中，创建如下 HTTP 请求消息：

• 对于 HTTP 操作，选择或指定 POST。

第一章 创建 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 规范。

大家好，

我想知道是否有可能获取自身的值来运行查询。

我想创建一些查询以在％Persistent类中找到一个值，但是每个查询都使用不同的值。

Class Kurro.MyClass Extends %Persistent
{

/// Key of process
Property KeyProcess As %String(MAXLEN = "");

/// Specialist
Property CodeSpecialist As %String;

/// Provider
Property CodeProvider As %String;

/// Center
Property CodeCenter As %String;

/// Date
Property Date As %TimeStamp;

/// IdList
Property IdList As %String;

/// IdProcess
Property IdProcess As %String;

/// Duration
Property Duration As %String;

Query GetInfo(pObject AS Kurro.

我想安装Windows版本的管理门户引擎来创建Cache InterSystems数据库
我想为Cache InterSystems创建一个样本数据库，并想通过Cache Entity Framework Provider访问它。但是，我无法找到一个特定的管理门户引擎来创建数据库。

你能指导一下如何在Windows中安装管理门户吗？

I want to install Management Portal Engine for Windows to create Cache InterSystems DB

I want to create a Sample Database for Cache InterSystems and want to access it via Cache Entity Framework Provider. But, I cannot find a particular engine of Management Portal to create a database. 

Can you guide how to install Management Portal in Windows?

大家好，我可以在RSA和DSA之间进行选择。 ECC似乎不受支持。有没有不使用外部二进制（例如curl）的解决方法？

RY

大家好，

我需要根据用户请求删除Ensemble接口。我想为此编写一个程序，执行的时候将通过代码删除接口组件。
能否提供以下操作的代码示例？

• 从规则类中删除单个规则
• 从Ensemble删除一个类
• 从生产环境中删除主机（服务/操作/流程）。

感谢帮助。
谢谢，

普鲁索他曼

Ensemble Delete Individual Rules and Ensemble classes programmatically
Hi Team,

I have a requirement to delete the Ensemble interfaces , as per User request. I would like to write a routine for that and once I execute, it should remove the interface components through code.
Could you please provide code samples for the following actions ?

大家好，

我目前正在开发TCP入站服务，以读取从使用EnsLib.TCP.CountedOutboundAdapter的TCP操作发送的一些XML。

1）我尝试过EnsLib.TCP.Inbound适配器，但是会出现此错误：

错误<Ens> ErrException：<METHOD不存在> zinitConfig + 7 ^ Ens.Host.1 *％New，EnsLib.TCP.InboundAdapter-登录为'-'
数字 - @'
设置..Adapter = $ classmethod（..＃ADAPTER，“％New”）'

因此，适配器无法开始侦听传入的连接。

2）当我改用EnsLib.TCP.CountedXMLInboundAdapter或EnsLib.TCP.CountedInboundAdapter时，适配器开始侦听给定的端口，但OnProcessinput（）方法未在pInput流中接收任何数据。流始终为空，并在事件日志中引发此错误。

错误<Ens> ErrTCPReadBlockSize：超时时间为（5）的TCP Read（32000）失败，错误如下：（1144）：l version =“ 1.0” encoding =“ UTF-8”？

我可以从AIX命令行提示符运行以下命令，而不会出现任何问题

-bash-2.05b$ echo t
t
-bash-2.05b$ echo œ
œ

当我从内部Cache调用时，我遇到了问题。

USER>D $ZF(-1,"echo t")
t

USER>D $ZF(-1,"echo œ")

D $ZF(-1,"echo œ")
^
<TRANSLATE>

我正在使用Cache 2017.2。有人可以帮忙吗？

谢谢你。

我想知道是否有更好的方法来使用动态SQL对数据集进行分页，而不是我下面使用的方法。问题是，当潜在的数据池变大时，这段代码就会变慢，以至于无法使用。在分析下面的每一行代码时，似乎速度变慢与最初的rset.%Next()迭代有关。 有没有什么不需要子查询/%VID的可用方法，比如简单的LIMIT/OFFSET？

我的代码类似于:

s sql=##class(%SQL.Statement).%New()

s query="SELECT *,%VID FROM (SELECT prop FROM table WHERE prop=x) WHERE %VID BETWEEN 1 AND 100"             

s sc=sql.%Prepare(query)

s rset=sql.%Execute()

while rset.%Next() {.....

答案见文档：https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls…

第八章 使用嵌入式 Python （五）

通过引用传递参数

用 ObjectScript 编写的方法中的参数可以通过值或引用传递。在下面的方法中，签名中第二个和第三个参数前面的 ByRef 关键字表示它们打算通过引用传递。

ClassMethod SandwichSwitch(bread As %String, ByRef filling1 As %String, ByRef filling2 As %String)
{
    set bread = "whole wheat"
    set filling1 = "almond butter"
    set filling2 = "cherry preserves"
}

从 ObjectScript 调用方法时，在参数前放置一个句点以通过引用传递它，如下所示：

USER>set arg1 = "white bread"
 
USER>set arg2 = "peanut butter"
 
USER>set arg3 = "grape jelly"
 
USER>do ##class(User.EmbeddedPython).SandwichSwitch(arg1, .arg2, .

第七章 使用嵌入式 Python （四）

弥合 ObjectScript 和嵌入式 Python 之间的差距

由于 ObjectScript 和 Python 语言之间的差异，将需要了解一些有助于弥合语言之间差距的信息。

在 ObjectScript 方面，%SYS.Python 类允许从 ObjectScript 使用 Python。

在 Python 方面，iris 模块允许使用 Python 中的 ObjectScript。在 Python 中，键入 help(iris) 以获取其方法和函数的列表。

使用 Python 内置函数

builtins 包在 Python 解释器启动时自动加载，它包含语言的所有内置标识符，例如基对象类和所有内置数据类型类、异常类、函数和常量。

可以将此包导入 ObjectScript 以访问所有这些标识符，如下所示：

set builtins = ##class(%SYS.Python).Import("builtins")

Python print() 函数实际上是内置模块的一个方法，因此现在可以在 ObjectScript 中使用此函数：

USER>do builtins.print("hello world!")
hello world!

第六章 使用嵌入式 Python （三）

从 ObjectScript 调用嵌入式 Python 代码

使用 Python 库

嵌入式 Python 让可以轻松访问数以千计的有用库。通常称为“包”，它们需要从 Python 包索引 (PyPI) 安装到 <installdir>/mgr/python 目录中，然后才能使用。

例如，ReportLab Toolkit 是一个用于生成 PDF 和图形的开源库。以下命令使用软件包安装程序 irispip 在 Windows 系统上安装 ReportLab：

C:\InterSystems\IRIS\bin>irispip install --target C:\InterSystems\IRIS\mgr\python reportlab

在基于 UNIX 的系统上，使用：

$ pip3 install --target /InterSystems/IRIS/mgr/python reportlab

安装包后，可以使用 %SYS.Python 类的 Import() 方法在 ObjectScript 代码中使用它。

给定一个文件位置，以下 ObjectScript 方法 CreateSamplePDF() 创建一个示例 PDF 文件并将其保存到该位置。

Class Demo.

第五章 使用嵌入式 Python （二）

在 Python 脚本文件 (.py) 中

还可以使用 irispython 命令执行 Python 脚本。

考虑 Windows 系统上的文件 C:\python\test.py，其中包含以下代码：

# print the members of the Fibonacci series that are less than 10
print('Fibonacci series:')
a, b = 0, 1
while a < 10:
    print(a, end=' ')
    a, b = b, a + b

# import the iris module and show the classes in this namespace
import iris
print('\nInterSystems IRIS classes in this namespace:')
status = iris.cls('%SYSTEM.OBJ').ShowClasses()
print(status)

可以从命令行运行 test.