DBMS_CLOUD REST API

本节介绍在专用 Exadata 基础结构上随 Autonomous AI Database 提供的 DBMS_CLOUD REST API。

Prerequisites

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

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

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

按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明，在自治 AI 数据库资源所在的虚拟云网络 (VCN) 中创建 NAT 网关。
创建 NAT 网关后，在自治 AI 数据库资源所在的 VCN 中添加路由规则和出站安全规则到每个子网，以便这些资源可以使用网关从 Azure AD 实例获取公钥：
1. 转到子网的 Subnet Details（子网详细信息）页面。
2. 在 Subnet Information（子网信息）选项卡中，单击子网的 Route Table（路由表）的名称以显示 Route Table Details（路由表详细信息）页面。
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 汇总

本节介绍自治 AI 数据库随附的 DBMS_CLOUD REST API。

REST API	说明
GET_RESPONSE_HEADERS 函数	此函数将 HTTP 响应标头作为自治 AI 数据库中 JSON 对象中的 JSON 数据返回。
GET_RESPONSE_TEXT 函数	此函数返回自治 AI 数据库中 TEXT 格式（`VARCHAR2` 或 `CLOB`）的 HTTP 响应。通常，大多数云 REST API 以文本格式返回 JSON 响应。如果希望 HTTP 响应为文本格式，则此函数非常有用。
GET_API_RESULT_CACHE_SIZE 函数	此函数返回配置的结果高速缓存大小。
SEND_REQUEST 函数和过程	此函数将启动 HTTP 请求，获取响应，并在自治 AI 数据库中结束响应。此函数提供用于发送包含参数的云 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 Reference and Endpoints 。
Azure 云

有关 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 视图

视图 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 常量。
`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 AI 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);

DBMS_CLOUD REST API

Prerequisites

DBMS_CLOUD REST API 汇总

DBMS_CLOUD REST API 概述

DBMS_CLOUD REST API 常量

DBMS_CLOUD REST API 结果高速缓存

DBMS_CLOUD REST API 结果 cache_scope 参数

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS 视图

GET_RESPONSE_HEADERS 函数

语法

参数

异常错误

GET_RESPONSE_TEXT 函数

语法

参数

异常错误

GET_API_RESULT_CACHE_SIZE 函数

语法

SEND_REQUEST 函数和过程

语法

参数

异常错误

使用说明

SET_API_RESULT_CACHE_SIZE 过程

语法

参数

异常错误

范例

相关内容