Oracle Cloud Infrastructure-Dokumentation

DBMS_CLOUD_FUNCTION-Paket

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

Übergeordnetes Thema: Von Autonomous Database bereitgestellte Paketreferenz

Zusammenfassung der DBMS_CLOUD_FUNCTION-Unterprogramme

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

Unterprogramm Beschreibung

Prozedur CREATE_CATALOG

Mit dieser Prozedur wird ein Katalog erstellt.

Prozedur CREATE_FUNCTION

Diese Prozedur erstellt Funktionen in einem Katalog.

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

Diese Prozedur erstellt einen PL/SQL-Wrapper, um dem Katalog neue Funktionen hinzuzufügen und Wrapper für Funktionen zu entfernen, die aus dem Katalog gelöscht wurden.
  • Prozedur CREATE_CATALOG
    Diese Prozedur erstellt einen Katalog in der Datenbank. Die Prozedur DBMS_CLOUD_FUNCTION.CREATE_CATALOG erstellt einen Katalog. Ein Katalog ist eine Gruppe von Funktionen, mit denen die erforderliche Infrastruktur für die Ausführung von Unterprogrammen erstellt wird. Diese Prozedur ist überladen.
  • Prozedur CREATE_FUNCTION
    Diese Prozedur erstellt Funktionen in einem Katalog. Es gibt zwei überladene DBMS_CLOUD_FUNCTION.CREATE_FUNCTION-Prozeduren.
  • Prozedur DROP_CATALOG
    Die Prozedur DBMS_CLOUD_FUNCTION.DROP_CATALOG löscht den Katalog und die Funktionen, die mit dem Katalog erstellt wurden. Diese Prozedur ist überladen.
  • Prozedur DROP_FUNCTION
    Die Prozedur DBMS_CLOUD_FUNCTION.DROP_FUNCTION löscht die Funktion. Diese Prozedur ist überladen.
  • Prozedur LIST_FUNCTIONS
    Diese Prozedur listet alle Funktionen in einem Katalog auf.
  • Prozedur SYNC_FUNCTIONS
    Diese Prozedur erstellt einen PL/SQL-Wrapper, um dem Katalog neue Funktionen hinzuzufügen und Wrapper für Funktionen zu entfernen, die aus dem Katalog gelöscht wurden.

Übergeordnetes Thema: Paket DBMS_CLOUD_FUNCTION

Prozedur CREATE_CATALOG

Diese Prozedur erstellt einen Katalog in der Datenbank. Die Prozedur DBMS_CLOUD_FUNCTION.CREATE_CATALOG erstellt einen Katalog. Ein Katalog ist eine Gruppe von Funktionen, mit denen die erforderliche Infrastruktur für die Ausführung von Unterprogrammen 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
);

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 Beschreibung

credential_name

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

Dieser Parameter ist erforderlich.

service_provider

Gibt den Typ des Serviceproviders an.

Dieser Parameter kann OCI oder AWS oder AZURE oder GCP als Parameterwert haben.

Dieser Parameter ist erforderlich.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist erforderlich.

cloud_params

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

Dieser Parameter ist erforderlich.

library_name

Gibt den Namen der Bibliothek beim Erstellen einer Remote-Bibliothek an.

Dieser Parameter ist erforderlich.

library_listener_url

Gibt die Remote-Position der Bibliothek an.

Der Parameter akzeptiert einen Zeichenfolgenwert im Format host_name:port_number.

Beispiel: EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000

Dieser Parameter ist erforderlich.

library_remote_path

Gibt den Remote-Bibliothekspfad an.

Sie müssen den vollständigen absoluten Pfad zu der Remote-Bibliothek angeben.

Beispiel: /u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so

Dieser Parameter ist erforderlich.

library_wallet_dir_name

Gibt das Verzeichnis an, in dem das selbstsignierte Wallet gespeichert ist.

Dieser Parameter ist erforderlich.

library_ssl_server_cert_dn

Gibt den Distinguished Name (DN) des Serverzertifikats an.

Dieser Parameter ist erforderlich.

Fehler

Fehlercode Beschreibung

ORA-20000

Dieser Fehler wird unter einer der folgenden Bedingungen ausgelöst:

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

  • Der Wert library_name ist beim Erstellen einer Bibliothek nicht eindeutig.

ORA-20001

Dieser Fehler wird unter einer der folgenden Bedingungen ausgelöst:

  • Die in der credential_name referenzierten Zugangsdaten sind nicht vorhanden.

  • Der in library_listener_url angegebene Listener ist beim Erstellen einer Library nicht erreichbar.

ORA-20002

Dieser Fehler wird unter einer der folgenden Bedingungen ausgelöst:

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

  • Das angegebene Serverzertifikatverzeichnis ist beim Erstellen einer Bibliothek leer.

ORA-20009

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

Beispiele

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;
/
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'AZURE$PA', 
        catalog_name     => 'AZURE_DEMO_CATALOG', 
        service_provider => 'AZURE',
        cloud_params     => '{"subscription_id":"44495e6a-8ff1-4161-b387-0e14e675b878"}'
 );
END;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (   
    library_name               => 'EXT_DEMOLIB',
    library_listener_url       => 'remote_extproc_hostname:16000',
    library_wallet_dir_name    => 'WALLET_DIR',
    library_ssl_server_cert_dn => 'CN=VM Hostname',
    library_remote_path        => '/u01/app/oracle/extproc_libs/library name'
 );
END;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'GCP$PA', 
        catalog_name     => 'GCP_DEMO_CATALOG', 
        service_provider => 'GCP',
        cloud_params     => '{"project_id":"example_XXXXXX"}'
 );
END;
/

Hinweis zur Verwendung

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

    • 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

Diese Prozedur erstellt Funktionen in einem Katalog. Es gibt zwei überladene DBMS_CLOUD_FUNCTION.CREATE_FUNCTION-Prozeduren.

CREATE_FUNCTION-Syntax

Die Prozedur DBMS_CLOUD_FUNCTION.CREATE_FUNCTION wird nur für Cloud-Funktionen 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
);

Signatur des Antwort-Handlers

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

Der Rückgabetyp ist ein benutzerdefinierter Typ oder ein PL/SQL-Typ. Die function_response ist JSON mit Feldern. 

'{  
"STATUS":"<RESPONCE STATUS>",  
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'

CREATE_FUNCTION-Parameter

CREATE_FUNCTION Ausnahmen

Parameter Beschreibung

credential_name

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

Dieser Parameter ist erforderlich.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist erforderlich.

function_name

Gibt den Namen der PL/SQL-Funktion an.

Dieser Parameter ist erforderlich.

function_id

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

Dieser Parameter ist erforderlich.

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 hat den Datentyp CLOB.

response_handler

Gibt den benutzerdefinierten Callback zur Verarbeitung der Antwort an.
Fehlercode Beschreibung

ORA-20001

Dieser Fehler wird ausgelöst, wenn die in der 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 Funktion Amazon-Ressourcennamen (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.

CREATE_FUNCTION-Beispiel 

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

CREATE_FUNCTION-Syntax 

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
  library_name         IN VARCHAR2,
  function_name        IN VARCHAR2,
  function_id          IN VARCHAR2 DEFAULT NULL,
  plsql_params         IN CLOB DEFAULT NULL,
  external_params      IN CLOB DEFAULT NULL,
  api_type             IN VARCHAR2 DEFAULT 'FUNCTION',
  with_context         IN BOOLEAN DEFAULT FALSE,
  return_type          IN VARCHAR2 DEFAULT NULL
);

CREATE_FUNCTION-Parameter

Parameter Beschreibung

library_name

Gibt den Namen der Remote-Bibliothek an.

Dieser Parameter ist erforderlich.

function_name

Gibt den Namen der PL/SQL-Funktion an.

Dieser Parameter ist erforderlich.

function_id

Der Parameterwert function_id bezieht sich auf die externen Prozeduren (extproc).

Wenn der Wert für function_id nicht angegeben wird, wird der Wert im function_name verwendet.

plsql_params

Gibt das JSON-Schlüsselwertpaar an, das die Parameter für den PL/SQL-Wrapper akzeptiert.

Die Werte müssen im Format "var_name":"modetype, datatype" angegeben werden.

  • var_name: Der Name der Variablen. Dieser Parameter ist erforderlich.

  • modetype: Gibt den Variablenmodus an. Folgende Variablen können verwendet werden:

    • IN

    • OUT

    • IN OUT

  • datatype: Gibt den variablen Datentyp an. Dieser Parameter ist erforderlich.

Der Standardwert für plsql_params ist NULL.

external_params

Gibt die Parameter an, die der externen C-Funktion bereitgestellt werden müssen.

Wenn kein Wert für external_params angegeben wird, werden die PL/SQL-Parameter verwendet.

api_type

Gibt den API-Typ (Funktion oder Prozedur) an.

Der Standardwert für api_type ist function.

with_context

Gibt an, dass ein Kontextzeiger an die externe Prozedur übergeben wird. Dieser Kontext wird von der externen C-Bibliothek für die Verbindung zur Datenbank verwendet.

Der Standardwert für with_context ist FALSE.

return_type

Gibt den Rückgabetyp der erstellten Funktion an.

CREATE_FUNCTION-Beispiel 

DECLARE
    plsql_params clob    := TO_CLOB('{"sal": "IN, FLOAT", "comm" :"IN, FLOAT"}');
    external_params clob := TO_CLOB('sal FLOAT, sal INDICATOR SHORT, comm FLOAT, comm INDICATOR SHORT,
    RETURN INDICATOR SHORT, RETURN FLOAT');
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    LIBRARY_NAME    => 'demolib',
    FUNCTION_NAME   => '"PercentComm"',
    PLSQL_PARAMS    => plsql_params,
    EXTERNAL_PARAMS => external_params,
    API_TYPE        => 'FUNCTION',
    WITH_CONTEXT    => FALSE,
    RETURN_TYPE     => 'FLOAT'
);
END;
/

Prozedur DROP_CATALOG

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_CATALOG löscht den Katalog und die Funktionen, die mit dem Katalog erstellt wurden. Diese Prozedur ist überladen.

Syntax

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_name      IN VARCHAR2
 );

Parameter

Parameter Beschreibung

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist erforderlich.
library_name

Gibt den Library-Namen an.

Dieser Parameter ist erforderlich.

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

Beispiel: 

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

Prozedur DROP_FUNCTION

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_FUNCTION löscht die Funktion. Diese Prozedur ist überladen.

Syntax

Die Prozedur DBMS_CLOUD_FUNCTION.DROP_FUNCTION wird nur für Cloud-Funktionen unterstützt. 

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

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

Parameter

Parameter Beschreibung

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist erforderlich.

function_name

Gibt den Namen der zu löschenden Funktion an

Dieser Parameter ist erforderlich.

library_name

Gibt den Library-Namen an.

Dieser Parameter ist erforderlich.

Beispiele

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

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       library_name     => 'EXTPROC_DEMO_LIBRARY',
       function_name    => 'demo_function');
END;
/

Prozedur LIST_FUNCTIONS

Diese Prozedur listet alle Funktionen in einem Katalog auf.

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

function_list

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

Dieser Parameter ist erforderlich.

catalog_name

Gibt den Katalognamen an.

Dieser Parameter ist erforderlich.

Fehler

Fehlercode Beschreibung

ORA-20000

Dieser Fehler wird ausgelöst, wenn der Wert cloud_params fehlt oder falsche Parameterwerte übergeben werden.

ORA-20001

Dieser Fehler wird ausgelöst, wenn die in der 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

Diese Prozedur erstellt einen PL/SQL-Wrapper, um dem Katalog neue Funktionen hinzuzufügen und Wrapper für Funktionen zu entfernen, die aus dem Katalog gelöscht wurden.

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

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