DBMS_CLOUD REST API

Prerequisites

作为开发人员，您可以将 DBMS_CLOUD 过程与部署在 Oracle Public Cloud 、 Multicloud 或 Exadata Cloud@Customer 上的 Autonomous Database 结合使用。

根据部署选择，必须满足以下先决条件，才能将 DBMS_CLOUD REST API 与 Amazon S3 、Azure Blob Storage 和 Google Cloud Storage 服务提供商一起使用。

Oracle Public Cloud 或多云
Exadata Cloud@Customer

您的组管理员必须使用 NAT 网关配置出站连接，如下所述：

按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明，在 Autonomous Database 资源所在的虚拟云网络 (Virtual Cloud Network，VCN) 中创建 NAT 网关。
创建 NAT 网关后，向每个子网（在 VCN 中）添加路由规则和出站安全规则，Autonomous Database 资源位于其中，以便这些资源可以使用网关从 Azure AD 实例获取公钥：
1. 转到子网的子网详细信息页。
2. 在子网信息选项卡中，单击子网的路由表的名称以显示其路由表详细信息页。
3. 在现有路由规则表中，检查是否已存在具有以下特征的规则：
  - 目标：0.0.0.0/0
  - 目标类型：NAT 网关
  - 目标：刚在 VCN 中创建的 NAT 网关的名称
  如果不存在此类规则，请单击添加路由规则并添加具有这些特征的路由规则。
4. 返回到子网的子网详细信息页。
5. 在子网的安全列表表中，单击子网的安全列表的名称以显示其安全列表详细信息页。
6. 在侧边菜单的资源下，单击出站规则。
7. 在现有出站规则表中，检查是否已存在具有以下特征的规则：
  - 目标类型： CIDR
  - 目标：0.0.0.0/0
  - IP 协议： TCP
  - 源端口范围： 443
  - 目标端口范围：全部
  如果不存在此类规则，请单击添加出站规则并添加具有这些特征的出站规则。

环境中的 HTTP 代理设置必须允许数据库访问云服务提供商。

这些设置由组管理员在创建 Exadata Cloud@Customer 基础结构时定义，如 Using the Console to Provision Exadata Database Service on Cloud@Customer 中所述。

注意：

只有在 Exadata 基础结构处于 Requires Activation 状态之前，才能编辑包括 HTTP 代理的网络配置。一旦激活，就无法编辑这些设置。

为已预配的 Exadata 基础结构设置 HTTP 代理需要在 My Oracle Support 中创建服务请求 (SR)。有关详细信息，请参见在 My Oracle Support 中创建服务请求。

DBMS_CLOUD REST API

本部分介绍 Autonomous Database 随附的 DBMS_CLOUD REST API。

REST API	说明
GET_RESPONSE_HEADERS 函数	此函数以 Autonomous Database 中 JSON 对象的 JSON 数据形式返回 HTTP 响应标头。
GET_RESPONSE_TEXT 函数	此函数以 Autonomous Database 中的 TEXT 格式（`VARCHAR2` 或 `CLOB`）返回 HTTP 响应。通常，大多数云 REST API 以文本格式返回 JSON 响应。如果您希望 HTTP 响应采用文本格式，则此函数非常有用。
GET_API_RESULT_CACHE_SIZE 函数	此函数返回配置的结果高速缓存大小。
SEND_REQUEST 函数和过程	此函数启动 HTTP 请求，获取响应，并在 Autonomous Database 中结束响应。此函数提供工作流，用于发送包含参数的云 REST API 请求以及返回响应代码和有效负载。
SET_API_RESULT_CACHE_SIZE 过程	此过程设置当前会话的最大高速缓存大小。

DBMS_CLOUD REST API 概述

当您在应用中使用 PL/SQL 并且需要调用云 REST API 时，您可以使用 DBMS_CLOUD.SEND_REQUEST 发送 REST API 请求。

DBMS_CLOUD REST API 函数允许您使用 DBMS_CLOUD.SEND_REQUEST 发出 HTTP 请求并获取和保存结果。这些功能提供了一个通用的 API，支持您通过以下受支持的云服务调用任何 REST API：

Oracle Cloud Infrastructure
有关 Oracle Cloud Infrastructure REST API 的信息，请参阅 API 参考和端点。
Azure 云^{脚注 1}
有关 Azure REST API 的信息，请参阅 Azure REST API 参考。

DBMS_CLOUD REST API 常量

介绍使用 DBMS_CLOUD.SEND_REQUEST 发出 HTTP 请求的 DBMS_CLOUD 常量。

DBMS_CLOUD 支持 GET、PUT、POST、HEAD 和 DELETE HTTP 方法。用于 HTTP 请求的 REST API 方法通常记录在云 REST API 文档中。

名称	类型	值
`METHOD_DELETE`	`VARCHAR2(6)`	`'DELETE'`
`METHOD_GET`	`VARCHAR2(3)`	`'GET'`
`METHOD_HEAD`	`VARCHAR2(4)`	`'HEAD'`
`METHOD_POST`	`VARCHAR2(4)`	`'POST'`
`METHOD_PUT`	`VARCHAR2(3)`	`'PUT'`

DBMS_CLOUD REST API 结果高速缓存

使用 DBMS_CLOUD.SEND_REQUEST 将 cache 参数设置为 true 时，可以保存 DBMS_CLOUD REST API 结果。SESSION_CLOUD_API_RESULTS 视图描述了保存 REST API 结果时可以使用的列。

默认情况下，DBMS_CLOUD REST API 调用不会保存会话的结果。在这种情况下，可以使用 DBMS_CLOUD.SEND_REQUEST 函数返回结果。

使用 DBMS_CLOUD.SEND_REQUEST 并将 cache 参数设置为 TRUE 时，将保存结果，您可以在 SESSION_CLOUD_API_RESULTS 视图中查看过去的结果。当需要在应用程序中使用以前的结果时，保存和查询 DBMS_CLOUD REST API 请求的历史结果可以为您提供帮助。

例如，要查询最近的 DBMS_CLOUD REST API 结果，请使用视图 SESSION_CLOUD_API_RESULTS：

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

使用 DBMS_CLOUD.SEND_REQUEST 保存 DBMS_CLOUD REST API 结果时，保存的数据仅在同一会话（连接）中可用。会话退出后，保存的数据将不再可用。

使用 DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE 和 DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE 查看和设置 DBMS_CLOUD REST API 高速缓存大小，以及禁用高速缓存。

DBMS_CLOUD REST API 结果 cache_scope 参数

使用 DBMS_CLOUD.SEND_REQUEST 保存 DBMS_CLOUD REST API 结果时，将根据 cache_scope 的值提供对 SESSION_CLOUD_API_RESULTS 中结果的访问。

默认情况下，cache_scope 为 'PRIVATE'，只有会话的当前用户可以访问结果。如果将 cache_scope 设置为 'PUBLIC'，则所有会话用户都可以访问结果。cache_scope 的默认值指定每个用户只能看到 DBMS_CLOUD.SEND_REQUEST REST API 结果，这些结果是由他们使用调用者的权限调用的过程生成的。在会话中调用 DBMS_CLOUD.SEND_REQUEST 时，有三种可能性根据 cache_scope 值确定当前用户是否可以看到高速缓存中的结果：

您可以直接将 DBMS_CLOUD.SEND_REQUEST 作为顶级语句执行，对 DBMS_CLOUD.SEND_REQUEST 和 REST API 结果的调用使用相同的用户名进行保存。在这种情况下，您可以访问为 cache_scope 设置了默认值 'PRIVATE'' 的所有结果。
您可以编写包装调用者的权限过程，并且作为当前用户，您使用 DBMS_CLOUD.SEND_REQUEST 调用该过程，并且 REST API 结果使用相同的用户名进行保存。在这种情况下，您可以访问为 cache_scope 设置了默认值 'PRIVATE'' 的所有结果。
您编写了包装限定符的权限过程，并且该过程归其他用户所有。在过程中调用 DBMS_CLOUD.SEND_REQUEST 时，将使用过程所有者的用户名保存结果。

在这种情况下，另一个定义者的权限用户正在调用 DBMS_CLOUD.SEND_REQUEST ，REST API 结果将与该定义者过程的所有者一起保存。在这种情况下，默认情况下，当 cache_scope 为 PRIVATE' 时，调用者的会话将无法看到结果。

如果定义者的过程所有者希望向任何调用会话用户提供结果，则必须在 DBMS_CLOUD.SEND_REQUEST 中将 cache_scope 设置为 'PUBLIC'。

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS 视图

使用 DBMS_CLOUD.SEND_REQUEST 将 cache 参数设置为 true 时，可以保存 DBMS_CLOUD REST API 结果。SESSION_CLOUD_API_RESULTS 视图描述了保存 REST API 结果时可以使用的列。

视图 SESSION_CLOUD_API_RESULTS 是使用 DBMS_CLOUD.SEND_REQUEST 缓存结果时创建的视图。您可以查询属于您的用户会话的历史结果。会话结束时，将清除 SESSION_CLOUD_API_RESULTS 中的数据。

列	说明
`URI`	`DBMS_CLOUD` REST API 请求 URL
`TIMESTAMP`	`DBMS_CLOUD` REST API 响应时间戳
`CLOUD_TYPE`	`DBMS_CLOUD` REST API 云类型，例如 Oracle Cloud Infrastructure 和 AZURE_BLOB
`REQUEST_METHOD`	`DBMS_CLOUD` REST API 请求方法，例如 `GET`、`PUT`、`HEAD`
`REQUEST_HEADERS`	`DBMS_CLOUD` REST API 请求标头
`REQUEST_BODY_TEXT`	`CLOB` 中的 `DBMS_CLOUD` REST API 请求正文
`RESPONSE_STATUS_CODE`	`DBMS_CLOUD` REST API 响应状态代码，例如 `200(OK)`、`404(Not Found)`
`RESPONSE_HEADERS`	`DBMS_CLOUD` REST API 响应标头
`RESPONSE_BODY_TEXT`	`CLOB` 中的 `DBMS_CLOUD` REST API 响应正文
`SCOPE`	由 `DBMS_CLOUD.SEND_REQUEST` 设置的 `cache_scope`。有效值为 `PUBLIC` 或 `PRIVATE`。

GET_RESPONSE_HEADERS 函数

此函数将 HTTP 响应标头作为 JSON 对象中的 JSON 数据返回。

语法

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

参数

Parameter (参数)	说明
`resp`	从 `DBMS_CLOUD.SEND_REQUEST` 返回的 HTTP 响应类型。

异常错误

例外	错误	说明
`invalid_response`	`ORA-20025`	传递给 `DBMS_CLOUD.GET_RESPONSE_HEADERS` 的响应类型对象无效。

GET_RESPONSE_TEXT 函数

此函数以 TEXT 格式（VARCHAR2 或 CLOB）返回 HTTP 响应。通常，大多数云 REST API 以文本格式返回 JSON 响应。如果您希望 HTTP 响应采用文本格式，则此函数非常有用。

语法

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

参数

Parameter (参数)	说明
`resp`	从 `DBMS_CLOUD.SEND_REQUEST` 返回的 HTTP 响应类型。

异常错误

例外	错误	说明
`invalid_response`	`ORA-20025`	传递给 `DBMS_CLOUD.GET_RESPONSE_TEXT` 的响应类型对象无效。

GET_API_RESULT_CACHE_SIZE 函数

此函数返回配置的结果高速缓存大小。高速缓存大小值仅适用于当前会话。

语法

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

SEND_REQUEST 函数和过程

此函数和过程启动 HTTP 请求，获取响应并结束响应。此函数提供用于发送包含参数的云 REST API 请求的工作流，该函数返回响应代码和有效负载。如果使用该过程，则可以使用 SESSION_CLOUD_API_RESULTS 视图查看已保存结果中的结果和响应详细信息。

语法

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

参数

Parameter (参数)	说明
`credential_name`	使用相应的云原生 API 进行验证的身份证明的名称。
`uri`	用于发出请求的 HTTP URI。
`method`	HTTP 请求方法：`GET`，`PUT`，`POST`，`HEAD`，`DELETE`。使用 `DBMS_CLOUD` 软件包常量指定方法。有关更多信息，请参见 DBMS_CLOUD REST API Constants 。
`headers`	JSON 格式的相应云原生 API 的 HTTP 请求标头。验证标头是自动设置的，仅通过定制标头。
`async_request_url`	异步请求 URL。要获取 URL，请从 API 列表中选择请求 API（请参见 https://docs.cloud.oracle.com/en-us/iaas/api/ ）。然后，导航以在左侧窗格中查找请求的 API。例如，Database Services API → Autonomous Database → StopAutonomousDatabase。此页显示 API 主目录（并显示基本端点）。然后，使用为工作请求 WorkRequest 链接获取的相对路径附加基本端点。
`wait_for_states`	等待状态的状态为 `DBMS_CLOUD_TYPES.wait_for_states_t` 类型。以下是预期状态的有效值：'`ACTIVE`'，'`CANCELED`'，'`COMPLETED`'，'`DELETED`'，'`FAILED`'，'`SUCCEEDED`'。 `wait_for_states` 允许有多个状态。`wait_for_states` 的缺省值为等待任何预期状态：'`ACTIVE`'、'`CANCELED`'、'`COMPLETED`'、'`DELETED`'、'`FAILED`'、'`SUCCEEDED`'。
`timeout`	指定参数为 `async_request_url` 和 `wait_for_states` 的异步请求的超时值（以秒为单位）。默认值为 `0`。这表示在没有任何超时的情况下等待请求的完成。
`cache`	如果 `TRUE` 指定请求应在 REST 结果 API 高速缓存中缓存。默认值为 `FALSE`，这意味着不缓存 REST API 请求。
`cache_scope`	指定是否所有人都可以访问此请求结果高速缓存。有效值：`"PRIVATE"` 和 `"PUBLIC"`。默认值为 `"PRIVATE"`。
`body`	`PUT` 和 `POST` 请求的 HTTP 请求正文。

异常错误

例外	错误	说明
`invalid_req_method`	`ORA-20023`	传递给 `DBMS_CLOUD.SEND_REQUEST` 的请求方法无效。
`invalid_req_header`	`ORA-20024`	传递给 `DBMS_CLOUD.SEND_REQUEST` 的请求标头不是有效的 JSON 格式。

使用说明

如果您使用的是 Oracle Cloud Infrastructure ，则必须为 credential_name 使用基于签名密钥的身份证明值。有关更多信息，请参见CREATE_CREDENTIAL Procedure 。
可选参数 async_request_url、wait_for_states 和 timeout 允许您处理长时间运行的请求。使用此异步形式的 send_request，函数将等待 wait_for_states 中指定的完成状态，然后再返回。通过发送请求中的这些参数，可以在 wait_for_states 参数中传递预期的返回状态，并使用 async_request_url 参数指定关联的工作请求，该请求不会立即返回。相反，请求会探测 async_request_url，直到返回状态为预期状态之一或超过 timeout（timeout 是可选的）。如果未指定 timeout，则请求将一直等待，直到在 wait_for_states 中找到的状态发生。

SET_API_RESULT_CACHE_SIZE 过程

此过程设置当前会话的最大高速缓存大小。高速缓存大小值仅适用于当前会话。

语法

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

参数

Parameter (参数) 说明

Parameter (参数)	说明
`cache_size`	将最大高速缓存大小设置为指定值 `cache_size`。如果新的最大高速缓存大小小于当前高速缓存大小，则会删除较旧的记录，直到行数等于指定的最大高速缓存大小。最大值为 `10000`。如果高速缓存大小设置为 `0`，则会在会话中禁用高速缓存。默认高速缓存大小为 `10`。

cache_size

将最大高速缓存大小设置为指定值 cache_size。如果新的最大高速缓存大小小于当前高速缓存大小，则会删除较旧的记录，直到行数等于指定的最大高速缓存大小。最大值为 10000。

如果高速缓存大小设置为 0，则会在会话中禁用高速缓存。

默认高速缓存大小为 10。

异常错误

例外	错误	说明
`invalid API result cache size`	`ORA-20032`	最小值为 0，最大值为 10000。当输入值小于 0 或大于 10000 时，会显示此异常错误。

范例

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);