Oracle Cloud Infrastructureドキュメント

DBMS_CLOUD_FUNCTIONパッケージ

DBMS_CLOUD_FUNCTIONパッケージを使用すると、Autonomous AI DatabaseのOCIおよびAWS Lambdaリモート関数をSQL関数として起動できます。

前提条件

DBMS_CLOUD_FUNCTIONパッケージのサブプログラムを使用するには、ADMINユーザーとしてログインし、次の権限を付与する必要があります。

GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_ T TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_FUNCTION TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD TO <user_or_role>;

DBMS_CLOUD_FUNCTIONサブプログラムの要約

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

サブプログラム 摘要
CREATE_CATALOGプロシージャ このプロシージャは、カタログを作成します。
LIST_FUNCTIONSプロシージャ このプロシージャは、カタログ内のすべての関数をリストします。
CREATE_FUNCTIONプロシージャ このプロシージャは、カタログにファンクションを作成します。
SYNC_FUNCTIONSプロシージャ このプロシージャは、カタログに新しいファンクションを追加したり、カタログから削除されたファンクションのラッパーを削除するためのPL/SQLラッパーを作成します。
DROP_FUNCTIONプロシージャ このプロシージャは、カタログからファンクションを削除します。
DROP_CATALOGプロシージャ このプロシージャは、カタログを使用して作成されたカタログおよび関数を削除します。

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

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

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

このパラメータは必須です。
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 (
        credential_name  => 'GCP$PA',
        catalog_name     => 'GCP_DEMO_CATALOG',
        service_provider => 'GCP',
        cloud_params     => '{"project_id":"example_XXXXXX"}'
 );
END;
/
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        CREDENTIAL_NAME  => 'AWS_CREDENTIAL',
        CATALOG_NAME     => 'AWS_DEMO_CATALOG',
        SERVICE_PROVIDER => 'AWS',
        CLOUD_PARAMS     => '{"region_id":"us-phoenix-1"}'
 );
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に対する読取り権限

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 このエラーは、指定したカタログが存在しない場合に発生します。

例:

SET SERVEROUTPUT ON
SET LINESIZE 32767
SET LONG 1000000
SET LONGCHUNKSIZE 32767
SET TRIMSPOOL ON
SET WRAP OFF

DECLARE
  l_function_list CLOB;
  l_function_array JSON_ARRAY_T;
  l_object JSON_OBJECT_T;
BEGIN
 DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS(
                                     credential_name => 'DEFAULT_CREDENTIAL',
                                     catalog_name    => 'OCI_DEMO_CATALOG',
                                     function_list   => l_function_list);
  l_function_array := JSON_ARRAY_T.parse(l_function_list);
  FOR i IN 0 .. l_function_array.get_size - 1
  LOOP
     l_object := TREAT(l_function_array.get(i) AS json_object_t);
     dbms_output.put_line('Function ID   = ' || l_object.get_string('functionId'));
     dbms_output.put_line('Function Name = ' || l_object.get_string('functionName'));
     dbms_output.put_line('--------------------------');
  END LOOP;
END;
/

CREATE_FUNCTIONプロシージャ

このプロシージャは、カタログにファンクションを作成します。オーバーロードされた2つのDBMS_CLOUD_FUNCTION.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>"
}'

パラメータ

パラメータ 摘要
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 このエラーは、レスポンス・ハンドラがないか無効である場合に発生します。

例

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

構文タイプ2

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

構文タイプ2のパラメータ

パラメータ 摘要
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 作成されるファンクションの戻り型を示します。

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

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

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