IRIS 2021 技术文档 First Look 18 - 在 InterSystems 产品中开发 REST 接口

本文档将向您展示如何开发 REST 接口。您可以将这些 REST 接口与 UI 工具(如 Angular)一起使用，以提供对数据库和互操作性产品的访问。您也可以使用它们支持外部系统访问 InterSystems IRIS®数据平台应用程序。
要浏览所有的技术概要(First Look)，包括可以在 InterSystems IRIS 免费的评估实例上执行的那些，请参见 InterSystems First Looks(《InterSystems 技术概要》)。

1    为什么提供 REST 接口
如果您需要从外部系统访问 InterSystems IRIS 数据库中的数据，或者想为这些数据提供用户界面，您可以通过定义 REST 接口来实现。REST——REpresentational State Transfer——是一种使用公开的 URL 从另一个系统检索、添加、更新或删除数据的方法。REST 基于 HTTP，并使用 HTTP 动词 POST、GET、PUT 和 DELETE 映射到数据库应用程序常见的创建、读取、更新和删除 (CRUD)功能。您还可以在 REST 中使用其他 HTTP 动词，如 HEAD、PATCH 和 OPTIONS。
REST 是在应用程序之间共享数据的众多方式之一，因此，如果您选择直接使用其他协议，如 TCP、SOAP 或 FTP 进行通信，则您可能并不总是需要设置 REST 服务。但是使用 REST 有以下优点：
•    REST 通常只有一个很小的开销(overhead)。它通常使用 JSON，这是一个轻量级的数据包装器。JSON 使用标签标识数据，但标签未在正式模式定义中指定，也没有显式的数据类型。REST 通常比 SOAP 更易于使用，SOAP 使用 XML 且开销(overhead)更大。
•    通过在 REST 中定义一个接口，可以很容易地将客户端和数据库服务器之间的依赖关系降到最低。这使您可以在不影响数据库实现的情况下更新用户界面。您还可以在不影响用户界面或访问 REST API 任何外部应用程序的情况下更新数据库实现(database implementation)。

2    对 InterSystems IRIS 的 REST 调用    在定义 REST 接口之前，您应该了解 REST 调用如何流经 InterSystems IRIS。首先，考虑 REST 调用的部分，如：GET http://localhost:52773/rest/coffeemakerapp/coffeemakers
在定义 REST 接口之前，您应该了解 REST 调用如何流经 InterSystems IRIS。首先，考虑 REST 调用的部分，如：
GET

这由以下部分组成：
•    GET——这是 http 动词。
•    http：——这指定了通信协议。
•    //localhost:52773——这指定了托管 REST 接口的 InterSystems IRIS 实例的服务器和端口号。
如何在 InterSystems IRIS 中定义 REST 接口

•    /rest/coffeemakerapp/coffeemakers——这是 URL 的主要部分，标识了 REST 调用所指向的资源。在下面的讨论中，URL 指的是 REST 调用的这一部分。

注意：    尽管这个技术概要(First Look)使用安装了 InterSystems IRIS 的 Web 服务器(在本例中是在本地系统的端口 52773 上)，但对于部署的任何代码，您都应该使用一个商业 Web 服务器来替换它。安装 InterSystems IRIS 的 web 服务器仅供开发代码时临时使用，并不具备商业 web 服务器的强大功能。

当客户端应用程序进行 REST 调用时：
1.    InterSystems IRIS 将它指向与 URL 对应的 web 应用程序。例如，以 /coffeemakerapp 开头的 URL 将被发送到处理咖啡机的应用程序，以 /api/docdb 开头的 URL 将被发送到处理文档数据模型(Document Data Model)的 web 应用程序。
2.    Web 应用程序根据 HTTP 动词(verb)和 URL 中标识 web 应用程序的部分之后的任何部分，将调用指向一个方法。它通过将动词(verb)和 URL 与称为 URLMap 的结构进行比较来实现这一点。
3.    该方法使用 URL 来标识 REST 调用所指定的资源，并根据动词(verb)来执行操作。例如，如果动词(verb)是 GET，该方法返回关于资源的一些信息；如果动词(verb)是 POST，该方法创建一个新的资源实例；如果动词(verb)是 DELETE，该方法删除指定资源。对于 POST 和 PUT 动词(verb)，通常有一个提供更多信息的数据包。
4.    该方法执行所请求的操作，并向客户端应用程序返回一个响应信息。

REST 调用需要执行方法和访问数据所需的任何权限。用户或 web 应用程序都可以拥有这些权限。您可以把这些权限分配给角色，然后把角色分配给用户或 web 应用程序。在这个示例中，%All 角色被分配给 web 应用程序。这允许未知用户(未经身份认证)访问 coffeemakerapp 数据。如果您没有把这个角色分配给 web 应用程序，未知用户将收到 401 未经授权的错误。您必须在 REST 身份认证调用中指定一个有足够权限的用户。详情请参见 "Securing REST Services(《确保 REST 服务》)"。

3    如何在 InterSystems IRIS 中定义 REST 接口
在 InterSystems IRIS 中，有两种方法来定义 REST 接口：
•    定义 OpenAPI 2.0 规范，然后使用 API 管理(API  Management)工具来生成 REST 接口的代码。
•    手动编码 REST 接口，然后在管理门户(Management Portal)中定义一个 web 应用程序。

本技术概要(First Look) 展示了如何手动编码 REST 接口，包括开发一个调度类(dispatch class)。如果您更喜欢使用规范优先的方法，这些调度类(dispatch class)是自动生成的，不应该被编辑。使用规范优先定义的优点包括能够从规范自动生成文档和客户端代码，但您可以使用任何一种方式来定义 REST 接口。有关使用规范定义 REST 接口的更多信息，请参见 Creating Rest Services(《创建 REST 服务》)。

4    手动编码 REST 接口    
手动编码 REST 接口包括以下步骤：
•    创建 %CSP.REST 的子类并定义 UrlMap。
手动编码 REST 接口

•    对处理 REST 调用的方法进行编码。
•    定义 web 应用程序——您通常使用管理门户(Management Portal)来执行此操作。

本技术概要(First Look)使用了一个访问咖啡机数据库的示例应用程序 coffeemakerapp 来演示如何手动编码 REST 接口。Coffeemakerapp 提供 REST 接口来获取咖啡机的信息、在数据库中创建新的记录、更新现有的记录或删除记录。以下几节通过注释探讨了此示例应用程序的类定义和一些方法，以增强您对代码的理解。您将在完成本技术概要(First Look) 的练习部分后，从 GitHub 下载整个应用程序的代码。

4.1    创建 %CSP.REST 的子类并定义 URLMap    
这是 demo.CoffeeMakerRESTServer 类定义的第一部分。它扩展了 %CSP.REST 类。

Class Demo.CoffeeMakerRESTServer Extends %CSP.REST{Parameter HandleCorsRequest = 1;XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]{<Routes><Route Url="