DBMS_CLOUD_FUNCTION 패키지

DBMS_CLOUD_FUNCTION 패키지를 사용하면 자율운영 AI 데이터베이스에서 OCI 및 AWS 람다 원격 함수를 SQL 함수로 호출할 수 있습니다.

주:

DBMS_CLOUD_FUNCTION에 대한 지원은 Oracle Database 19c 버전 19.29부터, Oracle AI Database 26ai 버전 23.26부터 제공됩니다.

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 프로시저는 데이터베이스에 카탈로그를 만듭니다. 카탈로그는 서브 루틴을 실행하는 데 필요한 Infrastructure를 생성하는 일련의 함수입니다. 이 프로시저는 오버로드됩니다.

구문

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name             IN VARCHAR2,
    catalog_name                IN VARCHAR2,
    service_provider            IN VARCHAR2, 
    cloud_params                IN CLOB
);

매개변수

매개변수	설명
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;
/

External 프로시저를 사용하여 라이브러리를 생성하려면 오버로드된 프로시저를 사용해야 합니다. 이 절차에는 자격 증명 객체가 필요하지 않습니다. 파라미터에는 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
);

매개변수

매개변수	설명
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의 반환 값은 <사용자 정의 유형>이고 response_json은 다음 형식의 두 필드가 있는 JSON 문서입니다.

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

매개변수

매개변수	설명
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 또는 함수 ARN(Amazon Resource Names)이 존재하지 않을 때 발생합니다.
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 클라우드 함수가 호출됩니다.

사용법 참고

External 프로시저 호출 시 유저 정의 함수에 사용된 것과 동일한 구문을 사용할 수 있습니다. 예를 들어, 외부 프로시저에 대한 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
 );

매개변수

매개변수	설명
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
);

매개변수

매개변수	설명
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
);

매개변수

매개변수	설명
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'
);

매개변수

매개변수	설명
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;
/

---

제목 및 저작권 정보

Copyright ©2025,2025,

Oracle and/or its affiliates.