DBMS_CLOUD_FUNCTIONパッケージ

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

ノート:

DBMS_CLOUD_FUNCTIONのサポートは、バージョン19.29以降のOracle Database 19c、およびバージョン23.26以降のOracle AI Database 26aiで使用できます。

DBMS_CLOUD_FUNCTIONサブプログラムの要約

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

表- DBMS_CLOUD_FUNCTIONサブプログラム

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

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

Parameters

パラメータ 説明

credential_name

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

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

service_provider

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

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

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

catalog_name

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

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

cloud_params

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

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

例

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'OCI_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  => 'AWS_CREDENTIAL',
        catalog_name     => 'AWS_DEMO_CATALOG',
        service_provider => 'AWS',
        cloud_params     => '{"region_id":"us-phoenix-1"}'
 );
END;
/

外部プロシージャを使用してライブラリを作成するには、オーバーロードされたプロシージャを使用する必要があります。この手順では、資格証明オブジェクトは必要ありません。パラメータには、EXTPROC VMおよび外部プロシージャを含む共有ライブラリの指定が必要です。「外部プロシージャの概要」を参照してください。

構文

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

Parameters

パラメータ 説明

library_name

データベース内のカタログ/ライブラリに指定した名前を指定します。

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

library_listener_url

C/C++などの第3世代言語で記述された外部プロシージャを含む共有ライブラリをホストするEXTPROC VMのFQDN (完全修飾ドメイン名)と、EXTPROC VMコンテナで実行されているSQL*Netリスナーが接続リクエストを受け入れるポート番号を指定します。

パラメータは、host_name:port_number形式の文字列として指定されます。たとえば:

'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'

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

library_wallet_dir_name

自己署名ウォレットがインポートされて格納されているデータベース内のDIRECTORYの名前を指定します。

library_ssl_server_cert_dn

ウォレットから取得したサーバー証明書識別名(DN)を指定します。たとえば:

'CN=extproc-agent-170798'

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

library_remote_path

外部プロシージャを含むライブラリが格納されるEXTPROC VM内のディレクトリのフルパス名を指定します。たとえば:

'/u01/app/oracle/extproc_libs/helloCextproc.so'

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

例

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        library_name               => 'EXTPROC_LIBRARY',
        library_listener_url       => 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000',
        library_wallet_dir_name    => 'EXTPROCWALLETDIR',
        library_ssl_server_cert_dn => 'CN=extproc-agent-170798',
        library_remote_path        => '/u01/app/oracle/extproc_libs/helloCextproc.so'
    );
END;
/

エラー数

エラー・コード 説明

ORA-20000

このエラーは、次の状況で発生します。

  • cloud_params値がないか、パラメータ値が正しくありません。

ORA-20001

このエラーは、次の状況で発生します。

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

ORA-20002

このエラーは、次の状況で発生します。

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

ORA-20009

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

使用上のノート

  • カタログを作成するには、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プロシージャ

カタログ内の対応するクラウド関数をコールするSQL関数を手動で作成できます。SYNC_FUNCTIONSでは、カタログ内のすべてのクラウド・ファンクションのラッパーが自動的に取得および作成されますが、CREATE_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
);

response_handlerは、次の形式で定義する必要があります。 

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

response_handlerの戻り値は<User Defined Type>で、response_jsonは2つのフィールドを持つJSONドキュメントで、次の形式になります。 

'{  
"status":"<response status>",  
"response_body":"<response from the function>"
}'

Parameters

パラメータ 説明

credential_name

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

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

catalog_name

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

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

function_name

PL/SQLファンクション名を指定します。

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

function_id

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

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

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

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

例

関数への入力パラメータのみを含む単純なケース:

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

戻り型とレスポンス・ハンドラを使用する例:

VAR input_param CLOB;
VAR l_return_type VARCHAR2(100);
VAR l_response_handler VARCHAR2(1000);

-- Define function parameters
exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');

PL/SQL procedure successfully completed.

exec :l_return_type     := 'fintech_rt';

PL/SQL procedure successfully completed.

exec :l_response_handler := 'fintech_response_handler';

PL/SQL procedure successfully completed.

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
        credential_name  => 'OCI_CRED',
        catalog_name     => 'OCI_DEMO_CATALOG',
        function_name    => 'FINTECH_FUNCTION',
        function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
        input_args       => :input_param,
        return_type      => :l_return_type,
        response_handler => :l_response_handler
 );
END;
/

次に、SQLラッパー・ファンクションの手動作成時に、このタイプおよびレスポンス・ハンドラを使用します。

VAR input_param CLOB;
VAR l_return_type VARCHAR2(100);
VAR l_response_handler VARCHAR2(1000);

-- Define function parameters
exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');

PL/SQL procedure successfully completed.

exec :l_return_type     := 'fintech_rt';

PL/SQL procedure successfully completed.

exec :l_response_handler := 'fintech_response_handler';

PL/SQL procedure successfully completed.

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
        credential_name  => 'OCI_CRED',
        catalog_name     => 'OCI_DEMO_CATALOG',
        function_name    => 'FINTECH_FUNCTION',
        function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
        input_args       => :input_param,
        return_type      => :l_return_type,
        response_handler => :l_response_handler
 );
END;
/

関数が作成されると、関数をDESCRIBEしてその戻り詳細を取得できます。

DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30

その後、関数を起動して、入力パラメータの値を指定できます。

SET SERVEROUTPUT ON

DECLARE
    l_comp fintech_rt;
BEGIN
    l_comp := fintech_fun(command=>'tokenize',value => 'PHI_INFORMATION');

    DBMS_OUTPUT.put_line ('Status of the function   =  '|| l_comp.status);
    DBMS_OUTPUT.put_line ('Response of the function =  '|| l_comp.output);
END;
/

これにより、OCI_DEMO_CATALOGカタログのファンクション参照oocid1.funfn.oci.phx.aaaaaa_exampleをコールして、fintech_funクラウド・ファンクションが起動されます。

使用上のノート

外部プロシージャを起動する場合、ユーザー定義関数と同じ構文を使用できます。たとえば、外部プロシージャのCREATE_CATALOGプロシージャを使用してEXTPROC_LIBRARYというライブラリをデータベースに作成した場合、この例に示すようにSQLファンクションを定義して、SQL文から起動できます。

SQL> CREATE OR REPLACE FUNCTION HELLOCEXTPROC RETURN VARCHAR2 AS
    LANGUAGE C
    LIBRARY EXTPROC_LIBRARY
    NAME "helloCextproc";
/

Function created.

SQL> SELECT HELLOCEXTPROC() FROM dual;

HELLOCEXTPROC()
----------------------------------------------------------------------------------
Hello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com

DROP_CATALOGプロシージャ

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

構文

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parameters

パラメータ 説明

catalog_name

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

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

エラー数

エラー・コード 説明

ORA-20003

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

次に例を示します: 

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      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
);

Parameters

パラメータ 説明

catalog_name

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

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

function_name

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

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

エラー数

エラー・コード 説明

ORA-20003

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

例

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

LIST_FUNCTIONSプロシージャ

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

ノート:

LIST_FUNCTIONSプロシージャは、クラウド・ファンクションにのみ適用できます。

構文

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

Parameters

パラメータ 説明

credential_name

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

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

function_list

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

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

catalog_name

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

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

エラー数

エラー・コード 説明

ORA-20000

不正なパラメータ値が渡されると、このエラーが発生します。

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プロシージャ

このプロシージャを使用すると、カタログに新しい機能を追加したり、カタログから削除された機能を削除できます。

ノート:

SYNC_FUNCTIONSプロシージャは、クラウド・ファンクションにのみ適用できます。

構文

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

Parameters

パラメータ 説明

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