DBMS_CLOUD REST API

必備條件

身為開發人員，您可以將 DBMS_CLOUD 程序與部署在 Oracle Public Cloud 、多重雲端或 Exadata Cloud@Customer 上的 Autonomous Database 搭配使用。

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

Oracle Public Cloud 或多雲端
Exadata 客戶私有雲

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

請依照 Oracle Cloud Infrastructure 文件中建立 NAT 閘道的指示，在 Autonomous Database 資源所在的虛擬雲端網路 (VCN) 中建立 NAT 閘道。
建立 NAT 閘道之後，請在 Autonomous Database 資源所在的每個子網路新增路由規則和傳出安全規則 (在 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 代理主機)。啟用之後，您就無法編輯這些設定值。

在 My Oracle Support 中設定已啟動設定之 Exadata 基礎架構的 HTTP 代理主機時，必須要有服務要求 (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，且需要呼叫 Cloud 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 Cloud ^{註腳 1}
如需 Azure REST API 的相關資訊，請參閱 Azure REST API Reference 。

DBMS_CLOUD REST API 常數

描述使用 DBMS_CLOUD.SEND_REQUEST 提出 HTTP 要求的 DBMS_CLOUD 常數。

DBMS_CLOUD 支援 GET、PUT、POST、HEAD 和 DELETE HTTP 方法。用於 HTTP 要求的 REST API 方法通常記錄在 Cloud 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 結果快取

當您將 cache 參數設為 true 並搭配 DBMS_CLOUD.SEND_REQUEST 時，您可以儲存 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 結果會以相同的使用者名稱儲存。在此情況下，您可以存取所有預設值為 'PRIVATE'' 且設為 cache_scope 的結果。
您會撰寫包裝函式定義器的權限程序，此程序由其他使用者所擁有。當您在程序中呼叫 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 檢視

當您將 cache 參數設為 true 並搭配 DBMS_CLOUD.SEND_REQUEST 時，您可以儲存 DBMS_CLOUD REST API 結果。SESSION_CLOUD_API_RESULTS 檢視說明儲存 REST API 結果時，您可以使用的資料欄。

如果您使用 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 函數

此函數會以 JSON 物件中的 JSON 資料形式傳回 HTTP 回應標頭。

語法

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 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);