DBMS_CLOUD_FUNCTION 程序包

通过 DBMS_CLOUD_FUNCTION 程序包，您可以在自治 AI 数据库中调用 OCI 和 AWS Lambda 远程函数作为 SQL 函数。

注意：

Oracle Database 19c（从版本 19.29 开始）和 Oracle AI Database 26ai（从版本 23.26 开始）提供了对 DBMS_CLOUD_FUNCTION 的支持。

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

参数

Parameter (参数) 说明

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 和包含外部过程的共享库的规范。请参见 External Procedures Overview 。

语法

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

参数

Parameter (参数) 说明

library_name

指定为数据库中的目录/库提供的名称。

此参数是必需的。

library_listener_url

指定承载共享库的 EXTPROC VM 的 FQDN（全限定域名），该共享库包含以第三代语言（如 C/C++）编写的外部过程，以及 EXTPROC VM 容器中运行的 SQL*Net 侦听器接受连接请求的端口号。

该参数以 host_name:port_number 格式指定为字符串。例如：

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

此参数是必需的。

library_wallet_dir_name

指定已将自签名 wallet 导入并存储的数据库中的 DIRECTORY 的名称。

library_ssl_server_cert_dn

指定从 wallet 获取的服务器证书标识名 (Distinguished Name，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 是包含两个字段的 JSON 文档，格式如下： 

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

参数

Parameter (参数) 说明

credential_name

指定用于验证的身份证明的名称。

此参数是必需的。

catalog_name

指定目录名称。

此参数是必需的。

function_name

指定 PL/SQL 函数名。

此参数是必需的。

function_id

function_id 参数值表示 OCI 函数或 AWS Lambda。

此参数是必需的。

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

参数

Parameter (参数) 说明

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

参数

Parameter (参数) 说明

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

参数

Parameter (参数) 说明

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

参数

Parameter (参数) 说明

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