DBMS_CLOUD_FUNCTIONパッケージ

DBMS_CLOUD_FUNCTIONパッケージを使用すると、Autonomous DatabaseのOCIおよびAWS Lambdaリモート・ファンクションをSQLファンクションとして起動できます。

DBMS_CLOUD_FUNCTIONサブプログラムの概要

この表は、DBMS_CLOUD_FUNCTIONパッケージに含まれるサブプログラムの概要を示しています。

サブプログラム 説明

CREATE_CATALOGプロシージャ

このプロシージャは、カタログを作成します。

CREATE_FUNCTIONプロシージャ

このプロシージャは、カタログにファンクションを作成します。

DROP_CATALOGプロシージャ

このプロシージャは、カタログを使用して作成されたカタログおよびファンクションを削除します。

DROP_FUNCTIONプロシージャ

このプロシージャは、カタログからファンクションを削除します。

LIST_FUNCTIONSプロシージャ

このプロシージャは、カタログ内のすべての関数をリストします。

SYNC_FUNCTIONSプロシージャ

このプロシージャは、カタログに新しいファンクションを追加し、カタログから削除されたファンクションのラッパーを削除するためのPL/SQLラッパーを作成します。

CREATE_CATALOGプロシージャ

このプロシージャは、データベースにカタログを作成します。DBMS_CLOUD_FUNCTION.CREATE_CATALOGプロシージャはカタログを作成します。カタログは、サブルーチンを実行するために必要なインフラストラクチャを作成する一連の関数です。このプロシージャはオーバーロードされています。

構文

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name             IN VARCHAR2,
    catalog_name                IN VARCHAR2,
    service_provider            IN VARCHAR2, 
    cloud_params                IN CLOB
);

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    library_name                IN VARCHAR2,
    library_listener_url        IN VARCHAR2,
    library_wallet_dir_name     IN VARCHAR2,
    library_ssl_server_cert_dn  IN VARCHAR2,
    library_remote_path         IN VARCHAR2
);

パラメータ

パラメータ 説明

credential_name

認証用の資格証明の名前を指定します。

このパラメータは必須です。

service_provider

サービス・プロバイダのタイプを指定します。

このパラメータには、パラメータ値としてOCIAWSまたはAZUREを指定できます。

このパラメータは必須です。

catalog_name

カタログ名を指定します。

このパラメータは必須です。

cloud_params

関数にパラメータを提供します。たとえば、コンパートメントOCID、リージョンおよびAzure subscription_idです。

このパラメータは必須です。

library_name

リモートライブラリの作成時に、ライブラリの名前を指定します。

このパラメータは必須です。

library_listener_url

ライブラリのリモート位置を指定します。

パラメータは、host_name:port_number形式の文字列値を受け入れます。

たとえば: EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000

このパラメータは必須です。

library_remote_path

リモートライブラリのパスを指定します。

リモートライブラリへのフル絶対パスを指定する必要があります。

たとえば:/u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so

このパラメータは必須です。

library_wallet_dir_name

自己署名ウォレットが格納されるディレクトリを指定します。

このパラメータは必須です。

library_ssl_server_cert_dn

サーバー証明書の識別名(DN)を指定します。

このパラメータは必須です。

エラー

エラー・コード 説明

ORA-20000

このエラーは、次のいずれかの条件で発生します。

  • cloud_params値が欠落しているか、不正なパラメータ値が渡されています。

  • library_name値は、ライブラリの作成時に一意ではありません。

ORA-20001

このエラーは、次のいずれかの条件で発生します。

  • credential_nameで参照されている資格証明が存在しません。

  • library_listener_urlで指定されたリスナーは、ライブラリの作成時にアクセスできません。

ORA-20002

このエラーは、次のいずれかの条件で発生します。

  • このエラーは、カタログがすでに存在する場合に発生します。

  • ライブラリの作成時に指定されたサーバー証明書ディレクトリが空です。

ORA-20009

このエラーは、サービス・プロバイダが存在しない場合に発生します。

サンプル

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'DEFAULT_CREDENTIAL', 
        catalog_name     => 'OCI_DEMO_CATALOG', 
        service_provider => 'OCI',
        cloud_params     => ("region_id":"us-phoenix-1", "compartment_id":"compartment_id"
 );
END;
/
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'AZURE$PA', 
        catalog_name     => 'AZURE_DEMO_CATALOG', 
        service_provider => 'AZURE',
        cloud_params     => '{"subscription_id":"44495e6a-8ff1-4161-b387-0e14e675b878"}'
 );
END;
/
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (   
    library_name               => 'EXT_DEMOLIB',
    library_listener_url       => 'remote_extproc_hostname:16000',
    library_wallet_dir_name    => 'WALLET_DIR',
    library_ssl_server_cert_dn => 'CN=VM Hostname',
    library_remote_path        => '/u01/app/oracle/extproc_libs/library name'
 );
END;
/

使用上のノート

  • カタログを作成するには、ADMINユーザーとしてログインするか、次の権限を持っている必要があります。
    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T

    • DBMS_CLOUD

    • USER_CLOUD_FUNCTIONに対する読取り権限

    • USER_CLOUD_FUNCTION_CATALOGに対する読取り権限

CREATE_FUNCTIONプロシージャ

このプロシージャは、カタログにファンクションを作成します。DBMS_CLOUD_FUNCTION.CREATE_FUNCTIONプロシージャは、2種類オーバーロードされています。

CREATE_FUNCTION構文

DBMS_CLOUD_FUNCTION.CREATE_FUNCTIONプロシージャは、クラウド機能でのみサポートされています。

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2,
    function_id       IN VARCHAR2,
    input_args        IN CLOB      DEFAULT NULL,
    return_type       IN VARCHAR2  DEFAULT 'CLOB',
    response_handler  IN VARCHAR2  DEFAULT NULL
);

レスポンス・ハンドラ署名

<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;

この戻り値の型は、ユーザー定義タイプまたはPL/SQLタイプです。function_responseは、フィールドを含むJSONです。

'{  
"STATUS":"<RESPONCE STATUS>",  
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'

CREATE_FUNCTIONパラメータ

CREATE_FUNCTION例外

パラメータ 説明

credential_name

認証用の資格証明の名前を指定します。

このパラメータは必須です。

catalog_name

カタログ名を指定します。

このパラメータは必須です。

function_name

PL/SQL関数名を指定します。

このパラメータは必須です。

function_id

function_idパラメータ値は、OCI関数、AWSラムダまたはAzure関数を参照します。

このパラメータは必須です。

input_args

入力引数とその型を受け入れるキー値JSONペアを指定します。

return_type

関数の戻り型を定義します。

戻り値のタイプはCLOBデータ型です。

response_handler

レスポンスを処理するユーザー定義コールバックを指定します。

エラー・コード 説明

ORA-20001

このエラーは、credential_nameで参照される資格証明が存在しない場合に発生します。

ORA-20003

このエラーは、指定したカタログが存在しない場合に発生します。

ORA-20004

このエラーは、指定された関数がすでに存在する場合に発生します。

ORA-20005

このエラーは、関数IDまたは関数 Amazonリソース名(ARN)が存在しない場合に発生します。

ORA-20006

このエラーは、入力引数が無効な場合に発生します。

ORA-20007

このエラーは、戻り型がないか無効な場合に発生します。

ORA-20008

このエラーは、レスポンス・ハンドラがないか無効な場合に発生します。

CREATE_FUNCTION

VAR function_args CLOB;
EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
	credential_name  => 'DEFAULT_CREDENTIAL',    
       catalog_name     => 'OCI_DEMO_CATALOG',
       function_name    => 'demo_function', 
       function_id      => 'ocid1.fnfunc.oc1.phx.aaaaaaaazkrbjv6ntowwxlbbp5ct4otsj4o2hdw4ayosyosv4sthmya2lyza',
       input_args       => :function_args);
 );
END;
/

CREATE_FUNCTION構文

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
  library_name         IN VARCHAR2,
  function_name        IN VARCHAR2,
  function_id          IN VARCHAR2 DEFAULT NULL,
  plsql_params         IN CLOB DEFAULT NULL,
  external_params      IN CLOB DEFAULT NULL,
  api_type             IN VARCHAR2 DEFAULT 'FUNCTION',
  with_context         IN BOOLEAN DEFAULT FALSE,
  return_type          IN VARCHAR2 DEFAULT NULL
);

CREATE_FUNCTIONパラメータ

パラメータ 説明

library_name

リモート・ライブラリ名を指定します。

このパラメータは必須です。

function_name

PL/SQL関数名を指定します。

このパラメータは必須です。

function_id

function_idパラメータ値は、外部プロシージャ(extproc)を参照します。

function_idの値が指定されていない場合は、function_nameの値が使用されます。

plsql_params

PL/SQLラッパーのパラメータを受け入れるキー値JSONペアを指定します。

値は"var_name":"modetype, datatype"形式で指定する必要があります。

  • var_name: 変数の名前です。このパラメータは必須です。

  • modetype: 変数モードを指定します。変数モードは、次のいずれかです。
    • IN

    • OUT

    • IN OUT

  • datatype: 変数データ型を指定します。このパラメータは必須です。

plsql_paramsのデフォルト値はNULLです。

external_params

外部C関数に指定する必要があるパラメータを指定します。

external_paramsに値を指定しない場合、PL/SQLパラメータが使用されます。

api_type

APIのタイプ(ファンクションまたはプロシージャ)を指定します。

api_typeのデフォルト値はfunctionです。

with_context

コンテキスト・ポインタが外部プロシージャに渡されることを指定します。このコンテキストは、外部Cライブラリがデータベースへの接続に使用されます。

with_contextのデフォルト値はFALSEです。

return_type

作成された関数の戻り型を指定します。

CREATE_FUNCTION

DECLARE
    plsql_params clob    := TO_CLOB('{"sal": "IN, FLOAT", "comm" :"IN, FLOAT"}');
    external_params clob := TO_CLOB('sal FLOAT, sal INDICATOR SHORT, comm FLOAT, comm INDICATOR SHORT,
    RETURN INDICATOR SHORT, RETURN FLOAT');
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    LIBRARY_NAME    => 'demolib',
    FUNCTION_NAME   => '"PercentComm"',
    PLSQL_PARAMS    => plsql_params,
    EXTERNAL_PARAMS => external_params,
    API_TYPE        => 'FUNCTION',
    WITH_CONTEXT    => FALSE,
    RETURN_TYPE     => 'FLOAT'
);
END;
/

DROP_CATALOGプロシージャ

DBMS_CLOUD_FUNCTION.DROP_CATALOGプロシージャは、カタログを使用して作成されたカタログおよびファンクションを削除します。このプロシージャはオーバーロードされています。

構文

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_name      IN VARCHAR2
 );

パラメータ

パラメータ 説明

catalog_name

カタログ名を指定します。

このパラメータは必須です。

library_name

ライブラリ名を指定します。

このパラメータは必須です。

エラー

エラー・コード 説明

ORA-20003

このエラーは、指定されたカタログが存在しない場合に発生します。

次に例を示します:

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      catalog_name     => 'OCI_DEMO_CATALOG'
  );
END;
/

次に例を示します:

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      library_name     => 'library_name'
  );
END;
/

DROP_FUNCTIONプロシージャ

DBMS_CLOUD_FUNCTION.DROP_FUNCTIONプロシージャは、ファンクションを削除します。このプロシージャはオーバーロードされています。

構文

DBMS_CLOUD_FUNCTION.DROP_FUNCTIONプロシージャは、クラウド機能でのみサポートされています。

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2
);

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    library_name     IN VARCHAR2,
    function_name    IN VARCHAR2
);

パラメータ

パラメータ 説明

catalog_name

カタログ名を指定します。

このパラメータは必須です。

function_name

削除するファンクションの名前を指定します。

このパラメータは必須です。

library_name

ライブラリ名を指定します。

このパラメータは必須です。

サンプル

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       catalog_name     => 'OCI_DEMO_CATALOG',
       function_name    => 'demo_function');
END;
/
BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       library_name     => 'EXTPROC_DEMO_LIBRARY',
       function_name    => 'demo_function');
END;
/

LIST_FUNCTIONSプロシージャ

このプロシージャは、カタログ内のすべての関数をリストします。

構文

DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_list     OUT VARCHAR2
);

パラメータ

パラメータ 説明

credential_name

認証用の資格証明の名前を指定します。

このパラメータは必須です。

function_list

関数のリストをJSON形式で返します。

このパラメータは必須です。

catalog_name

カタログ名を指定します。

このパラメータは必須です。

エラー

エラー・コード 説明

ORA-20000

このエラーは、cloud_params値が欠落しているか、不正なパラメータ値が渡されると発生します。

ORA-20001

このエラーは、credential_nameで参照される資格証明が存在しない場合に発生します。

ORA-20003

このエラーは、指定したカタログが存在しない場合に発生します。

例:

VAR function_list CLOB;
BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
	credential_name  => 'DEFAULT_CREDENTIAL', 
	catalog_name     => 'OCI_DEMO_CATALOG',  
	function_list    => :function_list);
 );
END;
/
SELECT JSON_QUERY(:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

SYNC_FUNCTIONSプロシージャ

このプロシージャは、カタログに新しいファンクションを追加し、カタログから削除されたファンクションのラッパーを削除するためのPL/SQLラッパーを作成します。

構文

DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
    catalog_name      IN VARCHAR2,
    refresh_rate     IN VARCHAR2 DEFAULT 'DAILY'
);

パラメータ

パラメータ 説明

catalog_name

カタログ名を指定します。

このパラメータは必須です。

refresh_rate

関数のリフレッシュ率を指定します。

refresh_rateには、次の値を指定できます。
  • HOURLY

  • DAILY

  • WEEKLY

  • MONTHLY

このパラメータのデフォルト値はDAILYです。

エラー

エラー・コード 説明

ORA-20003

このエラーは、指定したカタログが存在しない場合に発生します。

ORA-20004

このエラーは、refresh_rateパラメータに無効な値が渡されると発生します。

例:


BEGIN
    DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
       catalog_name     => 'OCI_DEMO_CATALOG'
 );
END;
/