DBMS_CLOUD REST API

この項では、Autonomous AI Database on Dedicated Exadata Infrastructureで提供されるDBMS_CLOUD REST APIについて説明します。

前提条件

開発者は、Oracle Public Cloud、MulticloudまたはExadata Cloud@CustomerにデプロイされたAutonomous AI DatabaseでDBMS_CLOUDプロシージャを使用できます。

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

DBMS_CLOUD REST APIのサマリー

この項では、Autonomous AI Databaseで提供されるDBMS_CLOUD REST APIについて説明します.

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

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 REST APIの結果をDBMS_CLOUD.SEND_REQUESTで保存すると、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 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;

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 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形式ではありません。

使用上のノート

SET_API_RESULT_CACHE_SIZEプロシージャ

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

構文

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parameters

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

関連コンテンツ