DBMS_CLOUD_FUNCTION-Package

Mit dem Package DBMS_CLOUD_FUNCTION können Sie OCI- und AWS Lambda-Remotefunktionen in Ihrer autonomen KI-Datenbank als SQL-Funktionen aufrufen.

Hinweis:

Unterstützung für DBMS_CLOUD_FUNCTION ist ab Version 19.29 in Oracle Database 19c und ab Version 23.26 in Oracle AI Database 26ai verfügbar.

Zusammenfassung der DBMS_CLOUD_FUNCTION-Unterprogramme

In dieser Tabelle werden die Unterprogramme zusammengefasst, die im Package DBMS_CLOUD_FUNCTION enthalten sind.

Tabelle - DBMS_CLOUD_FUNCTION-Unterprogramme

Unterprogramm Beschreibung
Prozedur CREATE_CATALOG Mit diesem Verfahren wird ein Katalog erstellt.
Prozedur CREATE_FUNCTION Mit dieser Prozedur werden Funktionen in einem Katalog erstellt.
Prozedur DROP_CATALOG Diese Prozedur löscht einen Katalog und Funktionen, die mit dem Katalog erstellt wurden.
Prozedur DROP_FUNCTION Diese Prozedur löscht Funktionen aus einem Katalog.
Prozedur LIST_FUNCTIONS Diese Prozedur listet alle Funktionen in einem Katalog auf.
Prozedur SYNC_FUNCTIONS Mit dieser Prozedur können Sie dem Katalog neue Funktionen hinzufügen und Funktionen entfernen, die aus dem Katalog gelöscht wurden.

Prozedur CREATE_CATALOG

Die Prozedur DBMS_CLOUD_FUNCTION.CREATE_CATALOG erstellt einen Katalog in der Datenbank. Ein Katalog ist eine Gruppe von Funktionen, mit denen die erforderliche Infrastruktur zur Ausführung von Unterroutinen erstellt wird. Diese Prozedur ist überladen.

Syntax

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

Parameter

Parameter Beschreibung

credential_name

Gibt den Namen der Zugangsdaten für die Authentifizierung an.

Dieser Parameter ist obligatorisch.

service_provider

Gibt den Typ des Serviceproviders an.

Dieser Parameter kann OCI oder AWS als Parameterwert haben.

Dieser Parameter ist obligatorisch.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

cloud_params

Stellt Parameter für die Funktion bereit. Beispiel: Compartment-OCID und Regionen.

Dieser Parameter ist obligatorisch.

Beispiele 

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

Sie müssen das überladene Verfahren verwenden, um eine Bibliothek mit externen Prozeduren zu erstellen. Für diese Prozedur ist kein Berechtigungsnachweisobjekt erforderlich. Für die Parameter sind Spezifikationen der EXTPROC VM und der Shared Library erforderlich, in der die externen Prozeduren enthalten sind. Siehe Überblick über externe Prozeduren.

Syntax

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

Parameter Beschreibungen

library_name

Gibt den Namen an, der dem Katalog/der Bibliothek in der Datenbank angegeben wird.

Dieser Parameter ist obligatorisch.

library_listener_url

Gibt den FQDN (vollqualifizierter Domainname) der EXTPROC-VM an, die die Shared Library hostet, welche die externen Prozeduren enthält, die in einer Sprache der dritten Generation wie C/C++ geschrieben wurden, und die Portnummer, unter der der der im EXTPROC-VM-Container ausgeführte SQL*Net-Listener Verbindungsanforderungen akzeptiert.

Der Parameter wird als Zeichenfolge im Format host_name:port_number angegeben. Beispiel:

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

Dieser Parameter ist obligatorisch.

library_wallet_dir_name

Gibt den Namen des DIRECTORY in der Datenbank an, in die das selbstsignierte Wallet importiert und gespeichert wurde.

library_ssl_server_cert_dn

Gibt den Distinguished Name (DN) des Serverzertifikats an, der aus dem Wallet abgerufen wird. Beispiel:

'CN=extproc-agent-170798'

Dieser Parameter ist obligatorisch.

library_remote_path

Gibt den vollständigen Pfadnamen des Verzeichnisses in EXTPROC VM an, in dem die Library mit den externen Prozeduren gespeichert ist. Beispiel:

'/u01/app/oracle/extproc_libs/helloCextproc.so'

Dieser Parameter ist obligatorisch.

Beispiele 

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

Fehler

Fehlercode Beschreibung

ORA-20000

Dieser Fehler wird in der folgenden Bedingung ausgelöst:

  • cloud_params-Wert fehlt, oder falsche Parameterwerte werden übergeben.

ORA-20001

Dieser Fehler wird in der folgenden Bedingung ausgelöst:

  • Die Zugangsdaten, auf die in credential_name verwiesen wird, sind nicht vorhanden.

ORA-20002

Dieser Fehler wird in der folgenden Bedingung ausgelöst:

  • Dieser Fehler wird ausgelöst, wenn der Katalog bereits vorhanden ist.

ORA-20009

Dieser Fehler wird ausgelöst, wenn der Serviceprovider nicht vorhanden ist.

Hinweis zur Verwendung

  • Um einen Katalog zu erstellen, müssen Sie als Benutzer ADMIN angemeldet sein oder über Berechtigungen für Folgendes verfügen:

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T

    • DBMS_CLOUD

    • Leseberechtigung auf USER_CLOUD_FUNCTION

    • Leseberechtigung auf USER_CLOUD_FUNCTION_CATALOG

Prozedur CREATE_FUNCTION

Sie können eine SQL-Funktion manuell erstellen, die ihre entsprechende Cloud-Funktion in Ihrem Katalog aufruft. Während SYNC_FUNCTIONS automatisch Wrapper für alle Cloudfunktionen in einem Katalog abruft und erstellt, können Sie mit CREATE_FUNCTION Funktionen mit benutzerdefinierten Rückgabetypen und Antwort-Handlern erstellen. Die Prozedur CREATE_FUNCTION gilt nur für Cloud-Funktionen.

Syntax

Die Prozedur DBMS_CLOUD_FUNCTION.CREATE_FUNCTION wird nur für Cloudfunktionen unterstützt. 

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

Die response_handler muss in folgendem Format definiert werden: 

<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;

Der Rückgabewert der response_handler ist <Benutzerdefinierter Typ>, und die response_json ist ein JSON-Dokument mit zwei Feldern im folgenden Format: 

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

Parameter

Parameter Beschreibung

credential_name

Gibt den Namen der Zugangsdaten für die Authentifizierung an.

Dieser Parameter ist obligatorisch.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

function_name

Gibt den PL/SQL-Funktionsnamen an.

Dieser Parameter ist obligatorisch.

function_id

Der Parameterwert function_id bezieht sich auf die OCI-Funktion oder AWS Lambda.

Dieser Parameter ist obligatorisch.

input_args

Gibt das JSON-Schlüsselwertpaar an, das Eingabeargumente und deren Typen akzeptiert.

return_type

Definiert den Rückgabetyp der Funktion.

Der Rückgabetyp ist der Datentyp CLOB.

response_handler

Gibt den benutzerdefinierten Rückruf an, der die Antwort verarbeitet.

Fehler

Fehlercode Beschreibung

ORA-20001

Dieser Fehler wird ausgelöst, wenn die in credential_name referenzierten Zugangsdaten nicht vorhanden sind.

ORA-20003

Dieser Fehler wird ausgelöst, wenn der angegebene Katalog nicht vorhanden ist.

ORA-20004

Dieser Fehler wird ausgelöst, wenn die angegebene Funktion bereits vorhanden ist.

ORA-20005

Dieser Fehler wird ausgelöst, wenn die Funktions-ID oder die Funktion "Amazon Resource Names" (ARN) nicht vorhanden ist.

ORA-20006

Dieser Fehler wird ausgelöst, wenn die Eingabeargumente ungültig sind.

ORA-20007

Dieser Fehler wird ausgelöst, wenn der Rückgabetyp fehlt oder ungültig ist.

ORA-20008

Dieser Fehler wird ausgelöst, wenn der Antwort-Handler fehlt oder ungültig ist.

Beispiel

Der einfache Fall mit nur Eingabeparametern für die Funktion:

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

Beispiel mit Rückgabetyp und Antwort-Handler:

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

Verwenden Sie als Nächstes diesen Typ und Response Handler bei der manuellen Erstellung der SQL Wrapper-Funktion.

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

Sobald die Funktion erstellt wurde, können Sie die Funktion BESCHREIBEN, um ihre Rückgabedetails abzurufen.

DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30

Anschließend können Sie die Funktion aufrufen und Werte für die Eingabeparameter angeben.

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

Dadurch wird die Cloudfunktion fintech_fun aufgerufen, indem die Funktionsreferenz oocid1.funfn.oci.phx.aaaaaa_example im Katalog OCI_DEMO_CATALOG aufgerufen wird.

Verwendungshinweise

Zum Aufrufen externer Prozeduren können Sie dieselbe Syntax verwenden, die für benutzerdefinierte Funktionen verwendet wird. Beispiel: Wenn Sie eine Library mit dem Namen EXTPROC_LIBRARY in der Datenbank mit der Prozedur CREATE_CATALOG für externe Prozeduren erstellt haben, können Sie eine SQL-Funktion wie in diesem Beispiel definieren und aus einer SQL-Anweisung aufrufen.

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

Prozedur DROP_CATALOG

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_CATALOG löscht den Katalog und die mit dem Katalog erstellten Funktionen.

Syntax

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parameter

Parameter Beschreibung

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

Fehler

Fehlercode Beschreibung

ORA-20003

Dieser Fehler wird ausgelöst, wenn der angegebene Katalog nicht vorhanden ist.

Beispiel: 

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      catalog_name     => 'OCI_DEMO_CATALOG'
  );
END;
/

Prozedur DROP_FUNCTION

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_FUNCTION löscht die Funktion.

Syntax

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_FUNCTION wird nur für Cloudfunktionen unterstützt. 

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2
);

Parameter

Parameter Beschreibung

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

function_name

Gibt den Namen der Funktion an, die gelöscht werden soll.

Dieser Parameter ist obligatorisch.

Fehler

Fehlercode Beschreibung

ORA-20003

Dieser Fehler wird ausgelöst, wenn die angegebene Funktion nicht vorhanden ist.

Beispiele 

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

Prozedur LIST_FUNCTIONS

Diese Prozedur listet alle Funktionen in einem Katalog auf.

Hinweis:

Die Prozedur LIST_FUNCTIONS gilt nur für Cloud-Funktionen.

Syntax

DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_list     OUT VARCHAR2
);

Parameter

Parameter Beschreibung

credential_name

Gibt den Namen der Zugangsdaten für die Authentifizierung an.

Dieser Parameter ist obligatorisch.

function_list

Gibt die Liste der Funktionen im JSON-Format zurück.

Dieser Parameter ist obligatorisch.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

Fehler

Fehlercode Beschreibung

ORA-20000

Dieser Fehler wird ausgelöst, wenn falsche Parameterwerte übergeben werden.

ORA-20001

Dieser Fehler wird ausgelöst, wenn die in credential_name referenzierten Zugangsdaten nicht vorhanden sind.

ORA-20003

Dieser Fehler wird ausgelöst, wenn der angegebene Katalog nicht vorhanden ist.

Beispiel: 

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;

Prozedur SYNC_FUNCTIONS

Mit dieser Prozedur können Sie dem Katalog neue Funktionen hinzufügen und Funktionen entfernen, die aus dem Katalog gelöscht wurden.

Hinweis:

Die Prozedur SYNC_FUNCTIONS gilt nur für Cloud-Funktionen.

Syntax

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

Parameter

Parameter Beschreibung

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist obligatorisch.

refresh_rate

Gibt die Aktualisierungsrate der Funktion an.

refresh_rate kann die folgenden Werte akzeptieren:

  • HOURLY

  • DAILY

  • WEEKLY

  • MONTHLY

Der Standardwert für diesen Parameter ist DAILY.

Fehler

Fehlercode Beschreibung

ORA-20003

Dieser Fehler wird ausgelöst, wenn der angegebene Katalog nicht vorhanden ist.

ORA-20004

Dieser Fehler wird ausgelöst, wenn ein ungültiger Wert für den Parameter refresh_rate übergeben wird.

Beispiel: 


BEGIN
    DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
       catalog_name     => 'OCI_DEMO_CATALOG'
 );
END;
/