DBMS_CLOUD_FUNCTION 套件

DBMS_CLOUD_FUNCTION 套裝程式可讓您在 Autonomous AI Database 中呼叫 OCI 和 AWS Lambda 遠端功能作為 SQL 函數。

附註：

從 19.29 版開始，Oracle Database 19c 以及從 23.26 版開始的 Oracle AI Database 26ai 中提供 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 和 (或) 其關係企業。