DBMS_CLOUD_FUNCTION-Package

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

Hinweis: Die 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.

Übersicht über 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
CREATE_CATALOG - Prozedur	Mit diesem Verfahren wird ein Katalog erstellt.
CREATE_FUNCTION - Prozedur	Mit dieser Prozedur werden Funktionen in einem Katalog erstellt.
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.
LIST_FUNCTIONS-Prozedur	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.

CREATE_CATALOG - Prozedur

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.

Syntaxvariante 1

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

Parameter für Variante 1

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 für Variante 1

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.

Syntaxvariante 2

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 für Variante 2

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 für Variante 2

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: - Der Wert `cloud_params` 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

CREATE_FUNCTION - Prozedur

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 Cloud-Funktionen 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 kann nur für Cloud-Funktionen verwendet werden.

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 von response_handler ist "Benutzerdefinierter Typ", und 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 mit der Prozedur CREATE_CATALOG für externe Prozeduren eine Library namens EXTPROC_LIBRARY in Ihrer Datenbank 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

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

Parameter	Beschreibung
`catalog_name`	Gibt den Katalognamen an. Dieser Parameter ist obligatorisch.

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

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.

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

LIST_FUNCTIONS-Prozedur

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

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`.

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