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 和区域。此参数是必需的。

错误数

错误代码	说明
`ORA-20000`	在以下情况下会引发此错误：缺少 `cloud_params` 值或者传递的参数值不正确。
`ORA-20001`	在以下情况下会引发此错误： `credential_name` 中引用的身份证明不存在。
`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;
/

用法附注

要创建目录，您必须以 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 过程。

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>"
}'

参数

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

DROP_CATALOG 过程

DBMS_CLOUD_FUNCTION.DROP_CATALOG 过程删除使用目录创建的目录和函数。

语法

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

参数

Parameter (参数) 说明

Parameter (参数)	说明
`catalog_name`	指定目录名称。此参数是必需的。

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 (参数) 说明

Parameter (参数)	说明
`catalog_name`	指定目录名称。此参数是必需的。
`function_name`	指定要删除的函数的名称。此参数是必需的。

catalog_name

指定目录名称。

此参数是必需的。

function_name

指定要删除的函数的名称。

此参数是必需的。

错误数

错误代码	说明
`ORA-20003`	当指定的函数不存在时会引发此错误。

示例

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

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 过程

通过此过程，可以将新函数添加到目录并删除已从目录中删除的函数。

语法

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

参数

Parameter (参数) 说明

Parameter (参数)	说明
`catalog_name`	指定目录名称。此参数是必需的。
`refresh_rate`	指定函数的刷新率。 `refresh_rate` 可以接受以下值： `HOURLY` `DAILY` `WEEKLY` `MONTHLY` 此参数的默认值为 `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;
/

标题和版权信息

Oracle 和/或其关联公司。