DBMS_CLOUD REST API

本節涵蓋專用 Exadata 基礎架構上自治式 AI 資料庫隨附的 DBMS_CLOUD REST API。

必備條件

身為開發人員，您可以將 DBMS_CLOUD 程序與部署在 Oracle Public Cloud、Multicloud 或 Exadata Cloud@Customer 上的 Autonomous AI 資料庫搭配使用。

視部署選項而定，必須符合下列先決條件，才能將 DBMS_CLOUD 程序與 Amazon S3、Azure Blob Storage 及 Google Cloud Storage 服務提供者搭配使用。

您的機組管理員必須使用 NAT 閘道設定輸出連線，如下所述：

請依照 Oracle Cloud Infrastructure 文件中 Create a NAT Gateway 的指示，在您自治式 AI 資料庫資源所在的虛擬雲端網路 (VCN) 中建立 NAT 閘道。
建立 NAT 閘道之後，請在自治式 AI 資料庫資源所在的每個子網路 (VCN 中) 新增路由規則和輸出安全規則，讓這些資源能夠使用閘道從您的 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 基礎架構時所定義，如使用主控台在 Cloud@Customer 上佈建 Exadata 資料庫服務中所述。

注意：只有在 Exadata 基礎架構處於需要啟用狀態時，才能編輯包含 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 參考與端點。
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 文件中。

名稱	Type	數值
`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 快取結果，則檢視 SESSION_CLOUD_API_RESULTS 會是建立的檢視。您可以查詢屬於使用者階段作業的歷史結果。階段作業結束時，會永久清除 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`	對應之雲端原生 API 的 HTTP 要求標頭 (JSON 格式)。認證標頭會自動設定，只傳送自訂標頭。
`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 程序以瞭解詳細資訊。
選擇性參數 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

必備條件

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 程序

語法

參數

異常狀況

範例

相關內容