创建 RESTful Web Services

使用“模块”、“模板”和“处理程序”页创建 RESTful Web 服务。

要创建 RESTful Web 服务，您需要：

• 定义资源模块

• 定义资源模板

• 定义一个或多个资源处理程序，例如 GET、PUT、POST 或 DELETE。（可选）定义需要传递给资源处理程序的参数。

以下各节提供了有关如何创建资源模块、资源模板和资源处理程序的信息。

• 管理资源模块

• 管理资源模板

• 管理资源处理程序

• 示例：使用 POST 处理程序插入记录

• 查看资源处理程序详细信息和管理参数

• 使用预先验证身份的请求访问 ORDS RESTful 服务

• 管理资源模块
  您可以在“模块”页中定义、编辑和删除资源模块。
• 管理资源模板
  您可以在“模板”页中为模块定义、编辑和删除资源模板。
• 管理资源处理程序
  您可以在“处理程序”页中为模板创建、编辑和删除资源处理程序。
• 示例：使用 POST 处理程序插入记录
  以下示例说明如何在 DEPT 表中插入记录。

另请参阅：

• REST 研讨会概述视频

• 《 Oracle REST Data Services Quick Start Guide 》中的 Creating a RESTful Service

管理资源模块

您可以在“模块”页中定义、编辑和删除资源模块。

要导航到“模块”页，请在“REST 概览”页中单击“对象”中的模块，或者从标题中的菜单中，选择模块。

下图显示了默认情况下在卡视图中显示的模块属性。

插图 module_card.png 的说明

模块状态可以发布或取消发布。如果状态为未发布，则图标将以红色显示。

单击卡视图中的模块名称可转到该模块的 "Templates" 页面。您还可以通过上下文菜单导航到“模板”页。

上下文菜单中可用的操作包括：

• 创建一个资源模块

• 导入资源模块

• 编辑资源模块

• 删除资源模块

• 发布/取消发布资源模块

• 导出资源模块

• 在 OpenAPI 视图中查看模块

• 导航到模块的 "Templates" 页面

• 创建资源模块
  本节介绍如何创建资源模块。
• 导入资源模块
  
• 编辑资源模块
  本节介绍如何编辑资源模块。
• 删除资源模块
  本节介绍如何删除资源模块。
• 发布/取消发布资源模块
  本节介绍如何使资源模块可用。
• 导出资源模块
  您可以导出资源模块或 RESTful 服务的 API 或 Open API (Swagger) JSON 代码的 PL/SQL 源代码。如果模块具有模板、处理程序、参数、角色等，则还会显示并导出这些对象。
• 在 OpenAPI 视图中查看模块
  本节介绍如何在 Open API 视图中打开模块。

另请参阅：

关于 REST 搜索工具栏

创建一个资源模块

本节介绍如何创建资源模块。

1. 在“模块”页中，单击创建模块。
2. 输入以下字段。带星号 (*) 标记的字段是必填字段：

   “模块定义”选项卡

   • 模块名称：输入模块的名称。此字段区分大小写。

   • 基本路径：输入用于访问 RESTful 服务的 URI 的基目录。例如：hr/ 表示所有以 hr/ 开头的 URI 将由此资源模块提供服务。在输入基本路径时，请注意预览 URL 中的更改。

   • 已发布：启用此项可使 RESTful 服务可供使用。

   • 分页大小：输入或选择基于数据库查询在每页上返回的结果数。默认值为 25。

   • Protected By Privilege（受权限保护）：从下拉列表中选择用于保护模块的权限。

   • 备注：输入说明性备注。

   • 创建后转至模块：选择此选项可在创建模块后转至“模板”页。

   “允许的来源”标签

   • 输入允许访问资源模板的源。单击 Add（添加） (+) 以添加每个源。例如：

     http://example1.org

     https://*.example2.com

   显示代码：选择此选项可查看与“创建模块”滑块等效的 PL/SQL 代码。您可以在工作表中复制并执行此 PL/SQL 代码，以执行与在“创建模块”滑块中单击创建时相同的操作。

3. 单击创建。

   新模块将显示在 "Modules"（模块）页面上。如果看不到该模块，请使用“Search（搜索）”字段找到该模块。

导入资源模块

本节介绍如何导入资源模块。

注意：

您只能以 JSON 格式导入 OpenAPI 版本 2.0 或 3.0 文档。

1. 在“模块”页的右上角，单击导入模块。
2. 浏览并选择要导入的 JSON 文件。单击打开。

   此时将显示“导入模块”滑块，其中预填充了基本路径和预览 URL 字段。根据需要编辑基本路径。编辑基本路径字段还将以滑块中显示的 JSON 格式更新基本路径。

3. 单击导入。

   导入模块时，将创建并设置特权配置以保护模块。特权的名称是通过使用基本路径并在基本路径字符串的末尾添加 "_priv" 以及将基本路径中的每个斜杠 "/" 替换为下划线 "_" 生成的。

4. 您的模块已准备好进行编辑。

   导入模块后，将创建模板和处理程序，但不会发布模块。您需要为每个处理程序提供 SQL 和 PL/SQL 块，并在模块可供测试或生产时发布模块。

编辑资源模块

本节介绍如何编辑资源模块。

1. 在“模块”页中，对于特定模块，单击 并选择编辑。
2. 编辑必填字段，然后单击保存。有关字段的说明，请参阅创建资源模块。

删除资源模块

本节介绍如何删除资源模块。

1. 在“模块”页中，对于特定模块，单击 并选择删除。

   此时将显示一个提示，要求您确认。

2. 单击确定以删除。

发布/取消发布资源模块

本节介绍如何使资源模块可用或不可用。

1. 在“模块”页中，对于特定模块，单击 ，然后选择发布或取消发布。

   您会看到确认提示。

2. 单击确定。

导出资源模块

您可以导出资源模块或 RESTful 服务的 API 或 Open API (Swagger) JSON 代码的 PL/SQL 源代码。如果模块具有模板、处理程序、参数、角色等，则还会显示并导出这些对象。

1. 在“模块”页中，对于特定模块，单击 并选择导出模块。
2. 选择 PL/SQL 可复制或导出 API 的 PL/SQL 源。选择 OpenAPI 以复制或导出模块的 Open API (Swagger) JSON 代码。

   注意：

   使用 Open API 导出的模块始终以未发布状态导入。
3. 单击复制到剪贴板以复制代码，或单击下载以下载到本地计算机。

在 OpenAPI 视图中查看模块

本节介绍如何在 Open API 视图中打开模块。

Open API 视图选项可用于已发布且不受保护的模块。

1. 在“模块”页中，对于特定模块，单击 并选择 OpenAPI 视图。
2. 该模块显示为 Swagger UI 实现。
   您可以查看和执行处理程序，将参数传递给处理程序，以及复制或下载响应。

   要了解有关 Swagger UI 实施的更多信息，请参阅官方 Swagger UI 网站。

管理资源模板

您可以在“模板”页面中定义、编辑和删除模块的资源模板。

要导航到此页，请在“模块”页中单击模块的 ，然后选择模板，或者在卡视图中单击模块的名称。

在页面顶部，模块卡提供上下文菜单选项，例如“编辑”、“删除”、“发布”和“导出”。

下图显示了默认情况下在卡视图中显示的模板属性。

插图 template_card.png 的说明

单击卡视图中的模板名称以转至“处理程序”页。您还可以通过上下文菜单导航到“处理器”页。

上下文菜单中可用的操作包括：

• 创建资源模板

• 编辑资源模板

• 删除资源模板

• 导航到模板的“处理程序”页

• 创建资源模板
  本节介绍如何创建资源模板。
• 编辑资源模板
  本节介绍如何编辑资源模板。
• 删除资源模板
  本节介绍如何删除资源模板。

创建资源模板

本节介绍如何创建资源模板。

1. 在模块的“模板”页中，单击创建模板。
2. 输入以下字段。带有星号 (*) 的字段表示这些字段是必需的：

   • URI 模板：输入资源模板的 URI 模式。

     例如，/objects/:object/：id？模式将匹配 /objects/emp/101（匹配 ID 为 101 的 emp 资源中项的请求），并且还将匹配 /objects/emp/（匹配 emp 资源的请求，因为 ：id 参数使用 ？修饰符进行注释，这表示 id 参数是可选的）。

     请注意，在键入 URI 模板时，预览 URL 会更改。

   • 优先级：输入或选择应如何评估资源模板的优先级（1 为低优先级，9 为高优先级）。

   • HTTP 实体标记类型：选择要由资源模板使用的实体标记类型。实体标记是充当资源的版本标识符的 HTTP 标头。

     包括以下选项：

     • Secure HASH (default) ：使用安全摘要函数散列返回的资源表示形式的内容，以便为给定资源版本提供唯一的指纹。

     • 查询：人工定义唯一标识资源版本的查询。手动定义的查询通常可以比散列整个资源表示形式更高效地生成实体标记。

     • 无：不生成实体标记。

   • 备注：输入说明性备注（如果有）。

   • 创建后转至处理程序：选择此选项可在创建模板后转至“处理程序”页。

   显示代码：选择此选项可查看“创建模板”滑块等效的 PL/SQL 代码。您可以在工作表中复制并执行此 PL/SQL 代码，以执行与在“创建模板”滑块中单击创建时相同的操作。

3. 单击创建。

   模块的新模板将添加到“模板”页。

   如果选择了“创建后转到处理程序”，则可以使用页面顶部的面包屑中的模块名称来查看模块的模板列表。

编辑资源模板

此部分介绍如何编辑资源模板。

1. 在“模板”页的特定模板中，单击 ，然后选择编辑。
2. 编辑必填字段，然后单击保存。

   有关字段的说明，请参阅创建资源模板。

删除资源模板

本节介绍如何删除资源模板。

1. 在“模板”页的指定模板中，单击 ，然后选择删除。

   系统将提示您确认。

2. 单击确定以删除。

管理资源处理程序

您可以在“处理程序”页中为模板创建、编辑和删除资源处理程序。

要导航到此页，请在“模板”页中，单击模板的 ，然后选择处理程序，或者在卡视图中单击模板的名称。

在页面顶部，模板卡提供上下文菜单选项，例如“编辑”和“删除”。

下图显示了默认情况下在卡视图中显示的处理程序属性。

插图 handler_card.png 的说明

HTTP 方法可以是以下方法之一：GET、PUT、POST 和 DELETE。

您可以使用上下文菜单导航到“HTTP 方法”页。HTTP 方法页中显示了三个选项卡：“Source（源）”、“Parameters（参数）”和“Pre-Authenticated Requests（预先验证的请求）”。

要创建资源处理程序，请参见 Creating a Resource Handler 。

注意：

如果模板创建了所有四个处理程序（GET、POST、PUT、DELETE），则此选项不可用。

上下文菜单中可用的操作包括：

• 编辑：请参阅编辑资源处理程序

• 删除：请参阅删除资源处理程序

• 详细信息：请参阅查看资源处理程序详细信息和管理参数

• 预先验证身份的请求：请参见预先验证身份的请求

• 创建资源处理程序
  本节介绍如何创建资源处理程序。
• 编辑资源处理程序
  本节介绍如何编辑资源处理程序。
• 删除资源处理程序
  本节介绍如何删除资源处理程序。
• 查看资源处理程序详细信息和管理参数
  您可以在 HTTP 方法页中查看资源处理程序详细信息并管理参数。
• 使用预先验证的请求访问 ORDS RESTful 服务
  要访问受保护的 RESTful 服务，可以创建和撤销预先验证的请求。

创建资源处理程序

本节介绍如何创建资源处理程序。

1. 在“处理程序”页中，单击创建处理程序。
2. 指定资源处理程序的属性。特定选项取决于方法类型。

   处理程序定义选项卡

   • 方法：输入用于此处理程序的 HTTP 请求方法：GET（检索资源的表示形式）、POST（创建新资源或向集合添加资源）、PUT（更新现有资源）或 DELETE（删除现有资源）。每个 HTTP 方法仅允许一个处理程序。

   • 每页的项数：输入或选择默认分页大小，或为数据库查询返回的行数。此选项仅对 GET 处理程序可用。如果未定义此值，则每页的项数是模块中定义的项数。

   • 源类型：为所选 HTTP 方法选择源实施。默认值为集合查询。

     • 集合查询：执行 SQL 查询并将结果集转换为 JSON 表示形式。HTTP 方法为 GET 时可用。

     • 集合项：执行 SQL 查询，将一行数据返回到 JSON 表示形式中。HTTP 方法为 GET 时可用。

     • 介质：执行符合特定格式的 SQL 查询，并将结果集转换为二进制表示形式，并使用随附的 HTTP Content-Type 标头标识表示形式的 Internet 介质类型。

     • PL/SQL ：执行匿名 PL/SQL 块并将任何 OUT 或 IN/OUT 参数转换为 JSON 表示形式。

   • 源：输入 HTTP 方法的 SQL 查询或 PL/SQL 块。在处理程序详细信息页中，可以在处理程序编辑器中测试 SQL 或 PL/SQL 处理程序代码。

   • 创建后转至处理程序：选择此选项可在创建处理程序后转至详细信息页。

   “允许的 MIME”选项卡

   标识 HTTP 请求正文中包含的信息类型。例如，如果 POST 处理程序在请求中需要 JSON，请添加 "Application/JSON" 作为 MIME 类型。

   显示代码：选择此选项可查看与“创建处理程序”滑块等效的 PL/SQL 代码。您可以在工作表中复制并执行此 PL/SQL 代码，以执行与在“创建处理程序”滑块中单击创建时相同的操作。

3. 单击创建。

   处理程序将显示在特定模板的“处理程序”页上。

   您可以使用 REST 客户端或命令行工具（例如 cURL）测试 REST 服务端点。

另请参阅：

《Oracle REST Data Services Developer's Guide 》中的 "About cURL and Testing RESTful Services"。

编辑资源处理程序

本节介绍如何编辑资源处理程序。

1. 在“处理程序”页中，对于特定处理程序，单击 ，然后单击详细信息。
2. 编辑必填字段，然后单击保存。

   有关字段的说明，请参阅创建资源处理程序。

删除资源处理程序

本节介绍了如何删除资源处理程序。

1. 在“处理程序”页中，对于特定处理程序，单击 ，然后单击删除。

   系统将提示您确认。

2. 单击确定以删除。

查看资源处理程序详细信息和管理参数

您可以在 HTTP 方法页中查看资源处理程序详细信息并管理参数。

要导航到此页，对于特定处理程序，请单击 ，然后选择详细信息，或者在卡视图中单击处理程序的名称。

在页面顶部，可使用带有上下文菜单选项（例如“编辑”和“删除”）的处理程序卡。

处理程序 HTTP 方法页包含两个主要部分：

• 用于执行在资源处理程序中定义的 SQL 或 PL/SQL 源代码的代码编辑器。您可以执行代码、保存、撤消、重做、下载和清除输出。有关编辑器的更多信息，请参见 Executing SQL Statements in the Code Editor 。

  REST 服务处理程序中使用的隐式参数显示在编辑器右侧的滚动列表中。请参阅隐式参数

• 用于管理运行 HTTP 方法所需的参数的部分。

默认情况下，参数显示在网格视图中。下图显示了卡视图中参数上显示的属性。

插图 parameter_card.png 的说明

上下文菜单中可用的操作包括：

• 正在创建参数

• 编辑某个参数

• 删除一个参数

• 创建参数
  本节介绍如何为资源处理程序创建参数。
• 编辑参数
  本节介绍如何编辑参数。
• 删除参数
  本节介绍如何删除参数。
• 隐式参数
  本节介绍“资源处理程序详细信息”页中的隐式参数。这些参数会自动添加到资源处理程序中。

另请参阅：

关于 REST 搜索工具栏

正在创建参数

本节介绍如何为资源处理程序创建参数。

1. 在处理程序 HTTP 方法页中，单击创建参数。
2. 输入以下字段。带星号 (*) 标记的字段是必填字段：

   • 参数名称：输入参数的名称，如 URI 模板或 HTTP 标头中指定的那样。名称定义在传入请求中如何标识参数或在响应中如何命名参数。

   • 绑定变量名称：输入参数的名称，SQL 中将引用该参数。如果指定了 NULL，则该参数是未绑定的。

   • 源类型：选择在 URI 模板或 HTTP 标头中确定参数的类型。

   • 参数类型：选择参数的本机类型。

   • 访问方法：选择参数访问方法。指明参数是输入值、输出值还是两者。

   显示代码：选择此选项可查看“创建参数”滑块等效的 PL/SQL 代码。您可以在工作表中复制并执行此 PL/SQL 代码，以执行与在“创建参数”滑块中单击创建时相同的操作。

3. 单击创建。

   参数将添加到“参数”部分中。

编辑某个参数

本节介绍如何编辑参数。

1. 在“参数”部分中，对于特定参数，单击 ，然后选择编辑。
2. 编辑必填字段，然后单击保存。

   有关字段的说明，请参阅创建参数。

删除一个参数

本节介绍如何删除参数。

1. 在“参数”部分中，对于特定参数，单击 ，然后选择删除。

   系统将提示您确认。

2. 单击是以删除。

隐式参数

本节介绍“资源处理程序详细信息”页中的隐式参数。这些参数会自动添加到资源处理程序中。

表 4-1 隐式参数

名称	类型	访问模式	HTTP 标头	说明
:body	BLOB	IN	不适用	将请求的正文指定为临时 BLOB。
:body_text	CLOB	IN	不适用	将请求的正文指定为临时 CLOB。
:content_type	VARCHAR	IN	Content-Type	指定请求正文的 MIME 类型，如 Content-Type 请求标头所示。
:current_user	VARCHAR	IN	不适用	指定请求的已验证用户。如果未对任何用户进行验证，则该值设置为 null。
:forward_location	VARCHAR	OUT	X-ORDS-FORWARD-LOCATION	指定 Oracle REST Data Services 必须转发 GET 请求以生成此请求的响应的位置。
:fetch_offset	NUMBER	IN	不适用	指定要在页面上显示的第一行的基于零的偏移量。
:fetch_size	NUMBER	IN	不适用	指定页面上要检索的最大行数。
:page_offset	NUMBER	IN	不适用	指定分页请求中基于零的页偏移量。 注：The :page_offset 参数已过时。改用 :row_offset 参数。
:page_size	NUMBER	IN	不适用	指定页面上要检索的最大行数。 :page_size 参数已过时。请改用 :fetch_size parameter 。
:row_offset	NUMBER	IN	不适用	指定要在分页请求中显示的第一行的基于一的索引。
:row_count	NUMBER	IN	不适用	指定要在分页请求中显示的最后一行的基于一个的索引。
:status_code	NUMBER	OUT	X-ORDS-STATUS-CODE	指定请求的 HTTP 状态代码。

有关隐式参数的更多信息，请参见Oracle REST Data Services Developer's Guide。

使用预先验证身份的请求访问 ORDS RESTful 服务

要访问受保护的 RESTful 服务，可以创建和撤销预先验证身份的请求。

通过预先验证的请求，无需用户凭证即可访问受保护的 ORDS RESTful 服务。创建预先验证的请求时，将生成唯一的 URL。您可以向外部用户提供此 URL，以便使用标准 HTTP 工具与特定 RESTful 实体进行交互。

有关预验证请求的更多信息，请参见《Oracle REST Data Services Developer's Guide 》中的 Oracle REST Data Services Pre-Authenticated Requests 。

要导航到“预先验证的请求”页面，您可以执行以下操作之一：

• 从 "Overview"（概览）页面中，单击 Pre-Authenticated Requests 磁贴。

• 从菜单栏中，展开安全性，然后选择预先验证身份的请求。

主题：

• 创建预先验证的请求
• 查看预先验证的请求

• 创建预先验证的请求
  
• 查看预先验证的请求
  
• 撤消预先验证的请求
  

创建预先验证的请求

要为现有处理程序创建预先验证的请求，请执行以下操作：

1. 从现有处理程序的上下文菜单中，选择 Create New Pre-authenticated Request 。

   此时将显示 "Create Pre-authenticated Request"（创建预先验证的请求）面板。

2. 在 Token Expiration（令牌失效）字段中，输入令牌失效持续时间（秒）。

   选择显示代码可查看用于创建预先验证的请求的基础源代码。

   单击创建。

   将显示用于访问资源的标记、别名和相对链接。必须跟踪标记和别名，因为以后无法获取其值。如果忘记了值，则可以撤消标记并再次创建新标记。

查看预先验证的请求

从现有处理程序的上下文菜单中，选择预先验证的请求，然后选择详细信息。

此时将显示针对特定处理程序的预验证请求。

撤消预先验证的请求

要撤消处理程序的预先验证的请求，请执行以下操作：

1. 从现有处理程序的上下文菜单中，选择预先验证的请求，然后选择详细信息。

   此时将显示针对特定处理程序的预先验证的请求。

2. 从预先验证的请求上下文菜单中，选择撤消。

   系统将提示您确认。

3. 单击确认可撤消请求。

示例：使用 POST 处理程序插入记录

以下示例说明如何在 DEPT 表中插入记录。

先决条件

• 使用 SQL 页面中的工作表，创建一个 DEPT 表。

  CREATE TABLE DEPT(  
    DEPTNO     number(2,0),  
    DNAME      varchar2(14),  
    LOC        varchar2(13),  
    CONSTRAINT PK_DEPT PRIMARY KEY (DEPTNO)  
  )
  

• 创建一个名为 example 的模块。请参见 Creating a Resource Module

• 为模块创建名为 emp/ 的模板。请参阅创建资源模板

要插入记录，请执行以下操作：

1. 在“处理程序”页中，单击创建处理程序。
2. 请输入以下详细信息：

   • 在方法字段中，选择 POST 。

   • 在源类型字段中，选择 PL/SQL 。

   • 在源字段中，输入以下 PL/SQL 块：

     DECLARE  
        id number;
     BEGIN
         INSERT INTO DEPT (DEPTNO, DNAME, LOC) VALUES (:DEPTNO, :DEPTNAME, :DEPTLOC) RETURNING DEPTNO INTO id;
         :status_code := 201;
         :forward_location := id;
     END;
     

     其中

     • RETURNING DEPTNO INTO id 将分配给 DEPTNO 的值返回到变量 id 中。

     • :status_code 是指定为 201 的隐式参数，用于指示资源已创建。

     • :forward_location 是为包含 DEPTNO 值的 id 分配的隐式参数。此参数指定用于转发 GET 请求以生成 POST 请求的响应的位置。

   • 确保选择了创建后转至处理程序页。

   • 在 MIMEs Allowed（允许的 MIME）选项卡中，从下拉列表中选择 application/json 并单击 Add（添加） +。

   • 单击创建。

   此时将显示“处理程序 POST”页。

   您可以通过单击“源”选项卡下的运行语句 来测试源代码。

3. 创建 GET 资源处理程序以生成 POST 请求的响应。

   在示例模块中，创建一个名为 emp/：id 的模板。

   创建一个 GET 资源处理程序，其中 Source Type（源类型）为 Collection Item（集合项）， Source（源）包含以下查询：

   SELECT * FROM DEPT WHERE DEPTNO = :id
   

4. 在 cURL 中使用以下命令测试 RESTful 服务端点。您可以使用顶部的 POST 处理程序卡中的“复制到剪贴板”图标复制 URL (http://xyz.us.comp.com:1234/ords/pdbdba/example/emp)。

   curl --location --request POST --header "Content-Type: application/json" 
   --data '{"DEPTNO": 54, "DEPTNAME": "HR", "DEPTLOC": "America" }' 'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'

   输出为：

   {"deptno":54,"dname":"HR","loc":"America","links":[{"rel":"collection",
   "href":"xyz.us.comp.com:1234/ords/pdbdba/example/emp/"}]}

5. 在“SQL”页面中，检查 DEPT 表，查看是否已使用以下语句插入新记录：

   SELECT * FROM DEPT;