DBMS_CLOUD REST API

前提条件

開発者は、Oracle Public Cloud、マルチクラウドまたはExadata Cloud@CustomerにデプロイされたAutonomous DatabaseでDBMS_CLOUDプロシージャを使用できます。

デプロイメントの選択肢に応じて、Amazon S3、Azure Blob StorageおよびGoogle Cloud Storageサービス・プロバイダでDBMS_CLOUD REST APIを使用するには、次の前提条件を満たす必要があります。

Oracle Public Cloudまたはマルチクラウド
Exadata Cloud@Customer

アウトバウンド接続は、次に説明するようにフリート管理者によってNATゲートウェイを使用して構成されている必要があります:

Oracle Cloud InfrastructureドキュメンテーションのNAT Gatewayの作成の説明に従って、Autonomous Databaseリソースが存在するVirtual Cloud Network (VCN)でNATゲートウェイを作成します。
NAT gatewayを作成したら、ルート・ルールおよびエグレス・セキュリティ・ルールの各サブネット(VCN内)を追加して、これらのリソースがゲートウェイを使用してAzure ADインスタンスから公開キーを取得できるようにします:Autonomous Databaseリソースが存在します:
1. サブネットの「サブネットの詳細」ページに移動します。
2. 「Subnet Information」タブで、サブネットの「Route Table」の名前をクリックして、その「Route Table Details」ページを表示します。
3. 既存のルート・ルールの表で、次の特性を持つルールがすでに存在します:
  - 宛先: 0.0.0.0/0
  - ターゲット・タイプ: NAT Gateway
  - ターゲット: VCN内に作成したNATゲートウェイの名前
  このようなルールが存在しない場合は、「ルート・ルールの追加」をクリックし、これらの特性を持つルート・ルールを追加します。
4. サブネットの「サブネットの詳細」ページに戻ります。
5. サブネットの「セキュリティ・リスト」表で、サブネットのセキュリティ・リストの名前をクリックして、その「セキュリティ・リストの詳細」ページを表示します。
6. サイド・メニューの「リソース」で、「エグレス・ルール」をクリックします。
7. 既存のエグレス・ルールの表で、次の特性を持つルールがすでに存在します:
  - 宛先タイプ: CIDR
  - 宛先: 0.0.0.0/0
  - IPプロトコル: TCP
  - ソース・ポート範囲: 443
  - 宛先ポート範囲: すべて
  そのようなルールが存在しない場合は、「エグレス・ルールの追加」をクリックし、これらの特性を持つエグレス・ルールを追加します。

環境のHTTPプロキシ設定では、データベースがクラウド・サービス・プロバイダにアクセスできるようにする必要があります。

これらの設定は、Exadata Cloud@Customerインフラストラクチャの作成時にフリート管理者が定義します(コンソールを使用したExadata Database Service on Cloud@Customerのプロビジョニングを参照)。

ノート:

HTTPプロキシを含むネットワーク構成は、Exadataインフラストラクチャが「アクティブ化が必要」状態になるまで編集できます。いったんアクティブ化すると、それらの設定は編集できません。

すでにプロビジョニングされている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でHTTPレスポンス・ヘッダーをJSONオブジェクト内のJSONデータとして返します。
GET_RESPONSE_TEXTファンクション	このファンクションは、Autonomous DatabaseでHTTPレスポンスをTEXT形式(`VARCHAR2`または`CLOB`)で戻します。通常、ほとんどのクラウドREST APIはJSONレスポンスをテキスト形式で戻します。この関数は、HTTPレスポンスがテキスト形式であることが予想される場合に役立ちます。
GET_API_RESULT_CACHE_SIZEファンクション	このファンクションは、構成された結果キャッシュ・サイズを返します。
SEND_REQUESTファンクションおよびプロシージャ	このファンクションは、Autonomous DatabaseでHTTPリクエストを開始してレスポンスを取得し、レスポンスを終了します。このファンクションは、引数を使用してクラウド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リクエストを行い、結果を取得して保存できます。これらのファンクションは、サポートされている次のクラウド・サービスを使用して任意のREST APIをコールできる汎用APIを提供します:

Oracle Cloud Infrastructure
Oracle Cloud Infrastructure REST APIの詳細は、「APIリファレンスおよびエンドポイント」を参照してください。
Azure Cloud ^脚注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のドキュメントに記載されています。

名前	タイプ	Value
`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の値に基づいて、現在のユーザーがキャッシュ内の結果を表示できるかどうかを決定する3つの可能性があります:

ユーザーが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`	`DBMS_CLOUD` REST APIリクエスト本文(`CLOB`)
`RESPONSE_STATUS_CODE`	`DBMS_CLOUD` REST APIレスポンス・ステータス・コード(`200(OK)`、`404(Not Found)`など)
`RESPONSE_HEADERS`	`DBMS_CLOUD` REST APIレスポンス・ヘッダー
`RESPONSE_BODY_TEXT`	`DBMS_CLOUD` REST APIレスポンス本文(`CLOB`)
`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;

Parameters

パラメータ	説明
`resp`	`DBMS_CLOUD.SEND_REQUEST`から戻されるHTTPレスポンス・タイプ。

例外

例外	エラー・コード	説明
`invalid_response`	`ORA-20025`	無効なレスポンス・タイプ・オブジェクトが`DBMS_CLOUD.GET_RESPONSE_HEADERS`に渡されました。

GET_RESPONSE_TEXTファンクション

このファンクションは、HTTPレスポンスをTEXT形式(VARCHAR2またはCLOB)で戻します。通常、ほとんどのクラウドREST APIはJSONレスポンスをテキスト形式で戻します。この関数は、HTTPレスポンスがテキスト形式であることが予想される場合に役立ちます。

構文

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

Parameters

パラメータ	説明
`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);

Parameters

パラメータ	説明
`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パラメータを使用して関連する作業リクエストを指定すると、リクエストはすぐに戻りません。かわりに、リクエストは、戻り状態が予想される状態のいずれかになるか、timeoutを超えるまで(timeoutはオプション)、async_request_urlを調査します。timeoutが指定されていない場合、リクエストは、wait_for_statesで検出された状態が発生するまで待機します。

SET_API_RESULT_CACHE_SIZEプロシージャ

このプロシージャは、現在のセッションの最大キャッシュ・サイズを設定します。キャッシュ・サイズの値は、現在のセッションにのみ適用されます。

構文

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parameters

パラメータ説明

パラメータ	説明
`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);