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 和區域。

此參數為必要參數。

範例

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

參數

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

指定資料庫中已匯入並儲存自行簽署公事包的 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 為具有兩個欄位的 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;
/