Ensemble DBMS_CLOUD_FUNCTION

L'ensemble DBMS_CLOUD_FUNCTION vous permet d'appeler des fonctions distantes OCI et AWS Lambda dans votre base de données d'IA autonome en tant que fonctions SQL.

Note : La prise en charge de DBMS_CLOUD_FUNCTION est disponible dans Oracle Database 19c à partir de la version 19.29 et dans Oracle AI Database 26ai à partir de la version 23.26.

Sommaire des sous-programmes DBMS_CLOUD_FUNCTION

Ce tableau résume les sous-programmes inclus dans l'ensemble DBMS_CLOUD_FUNCTION.

Table - Sous-programmes DBMS_CLOUD_FUNCTION

Sous-programme	Description
Procédure CREATE_CATALOG	Cette procédure crée un catalogue.
Procédure CREATE_FUNCTION	Cette procédure crée des fonctions dans un catalogue.
Procédure DROP_CATALOG	Cette procédure supprime un catalogue et les fonctions créées à l'aide du catalogue.
Procédure DROP_FUNCTION	Cette procédure supprime les fonctions d'un catalogue.
Procédure LIST_FUNCTIONS	Cette procédure répertorie toutes les fonctions d'un catalogue.
Procédure SYNC_FUNCTIONS	Cette procédure permet d'ajouter de nouvelles fonctions au catalogue et de supprimer des fonctions qui ont été supprimées du catalogue.

Procédure CREATE_CATALOG

La procédure DBMS_CLOUD_FUNCTION.CREATE_CATALOG crée un catalogue dans la base de données. Un catalogue est un ensemble de fonctions qui crée l'infrastructure requise pour exécuter des sous-programmes. Cette procédure est surchargée.

Variante de syntaxe 1

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

Paramètres de la variante 1

Paramètre	Description
`credential_name`	Spécifie le nom des données d'identification pour l'authentification. Ce paramètre est obligatoire.
`service_provider`	Indique le type du fournisseur de services. Ce paramètre peut avoir `OCI` ou `AWS` comme valeur de paramètre. Ce paramètre est obligatoire.
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.
`cloud_params`	Fournit un paramètre à la fonction. Par exemple, OCID et régions du compartiment. Ce paramètre est obligatoire.

Exemples pour la 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;
/

Vous devez utiliser la procédure surchargée pour créer une bibliothèque avec des procédures externes. Cette procédure ne nécessite pas d'objet de données d'identification. Les paramètres nécessitent des spécifications de la machine virtuelle EXTPROC et de la bibliothèque partagée qui contient les procédures externes.

Variante de syntaxe 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
);

Paramètres de la variante 2

Paramètre	Description
`library_name`	Spécifie le nom fourni au catalogue/bibliothèque dans la base de données. Ce paramètre est obligatoire.
`library_listener_url`	Spécifie le nom de domaine complet de la machine virtuelle EXTPROC qui héberge la bibliothèque partagée contenant les procédures externes écrites dans un langage de troisième génération tel que C/C++ et le numéro de port auquel le module d'écoute SQL*Net s'exécutant dans le conteneur de la machine virtuelle EXTPROC accepte les demandes de connexion. Le paramètre est spécifié en tant que chaîne dans le format `host_name:port_number`. Par exemple : `'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'` Ce paramètre est obligatoire.
`library_wallet_dir_name`	Spécifie le nom du répertoire dans la base de données dans laquelle le portefeuille auto-signé a été importé et stocké.
`library_ssl_server_cert_dn`	Spécifie le nom distinctif (DN) du certificat de serveur obtenu à partir du portefeuille. Par exemple : `'CN=extproc-agent-170798'` Ce paramètre est obligatoire.
`library_remote_path`	Spécifie le chemin d'accès complet du répertoire dans la machine virtuelle EXTPROC, où la bibliothèque contenant les procédures externes est stockée. Par exemple : `'/u01/app/oracle/extproc_libs/helloCextproc.so'` Ce paramètre est obligatoire.

Exemples pour la 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;
/

Erreurs

Code d'erreur	Description
`ORA-20000`	Cette erreur est générée dans la condition suivante : - La valeur `cloud_params` est manquante ou des valeurs de paramètre incorrectes ont été transmises.
`ORA-20001`	Cette erreur est générée dans la condition suivante : - Les données d'identification référencées dans `credential_name` n'existent pas.
`ORA-20002`	Cette erreur est générée dans la condition suivante : - Cette erreur est générée lorsque le catalogue existe déjà.
`ORA-20009`	Cette erreur est générée lorsque le fournisseur de services n'existe pas.

Note d'utilisation

Pour créer un catalogue, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer des privilèges suivants :
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T
- DBMS_CLOUD
- Privilège de lecture sur USER_CLOUD_FUNCTION
- Privilège de lecture sur USER_CLOUD_FUNCTION_CATALOG

Procédure CREATE_FUNCTION

Vous pouvez créer manuellement une fonction SQL qui appelle la fonction en nuage correspondante dans votre catalogue. Tandis que SYNC_FUNCTIONS extrait et crée automatiquement des wrappers pour toutes les fonctions cloud d'un catalogue, CREATE_FUNCTION vous permet de créer des fonctions avec des types de retour et des gestionnaires de réponses personnalisés. La procédure CREATE_FUNCTION ne s'applique qu'aux fonctions en nuage.

Syntaxe

La procédure DBMS_CLOUD_FUNCTION.CREATE_FUNCTION n'est prise en charge que pour les fonctions en nuage.

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 doit être défini dans ce format :

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

La valeur de retour de response_handler est de 'Type défini par l'utilisateur' et response_json est un document JSON avec deux champs, dans le format suivant :

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

Paramètres

Paramètre	Description
`credential_name`	Spécifie le nom des données d'identification pour l'authentification. Ce paramètre est obligatoire.
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.
`function_name`	Indique le nom de la fonction PL/SQL. Ce paramètre est obligatoire.
`function_id`	La valeur du paramètre `function_id` fait référence à la fonction OCI ou à AWS Lambda. Ce paramètre est obligatoire.
`input_args`	Spécifie la paire clé-valeur JSON acceptant les arguments d'entrée et leurs types.
`return_type`	Définit le type de retour de la fonction. Le type de retour est de type de données `CLOB`.
`response_handler`	Indique le rappel défini par l'utilisateur pour traiter la réponse.

Erreurs

Code d'erreur	Description
`ORA-20001`	Cette erreur est générée lorsque les données d'identification référencées dans `credential_name` n'existent pas.
`ORA-20003`	Cette erreur est générée lorsque le catalogue spécifié n'existe pas.
`ORA-20004`	Cette erreur est générée lorsque la fonction spécifiée existe déjà.
`ORA-20005`	Cette erreur est générée lorsque l'ID fonction ou la fonction Noms de ressource Amazon (ARN) n'existe pas.
`ORA-20006`	Cette erreur est générée lorsque les arguments d'entrée ne sont pas valides.
`ORA-20007`	Cette erreur est générée lorsque le type de retour est manquant ou non valide.
`ORA-20008`	Cette erreur est générée lorsque le programme de traitement de réponses est manquant ou non valide.

Exemple

Le cas simple avec juste des paramètres d'entrée à la fonction :

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

Exemple avec le type de retour et le gestionnaire de réponses :

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

Ensuite, utilisez ce type et ce gestionnaire de réponses lors de la création manuelle de la fonction d'encapsuleur 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;
/

Une fois la fonction créée, vous pouvez la DÉCRIRE pour obtenir ses détails de retour.

DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30

Vous pouvez ensuite appeler la fonction, en fournissant des valeurs pour les paramètres d'entrée.

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

Cela appelle la fonction en nuage fintech_fun en appelant la référence de fonction oocid1.funfn.oci.phx.aaaaaa_example dans le catalogue OCI_DEMO_CATALOG.

Notes d'utilisation

Pour appeler des procédures externes, vous pouvez utiliser la même syntaxe que pour les fonctions définies par l'utilisateur. Par exemple, si vous avez créé une bibliothèque nommée EXTPROC_LIBRARY dans votre base de données à l'aide de la procédure CREATE_CATALOG pour les procédures externes, vous pouvez définir une fonction SQL comme illustré dans cet exemple et l'appeler à partir d'une instruction 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

Procédure DROP_CATALOG

La procédure DBMS_CLOUD_FUNCTION.DROP_CATALOG supprime le catalogue et les fonctions créés à l'aide du catalogue.

Syntaxe

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Paramètres

Paramètre Description

Paramètre	Description
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.

catalog_name

Spécifie le nom du catalogue.

Ce paramètre est obligatoire.

Erreurs

Code d'erreur	Description
`ORA-20003`	Cette erreur est générée lorsque le catalogue spécifié n'existe pas.

Exemple :

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

Procédure DROP_FUNCTION

La procédure DBMS_CLOUD_FUNCTION.DROP_FUNCTION supprime la fonction.

Syntaxe

La procédure DBMS_CLOUD_FUNCTION.DROP_FUNCTION n'est prise en charge que pour les fonctions en nuage.

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

Paramètres

Paramètre Description

Paramètre	Description
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.
`function_name`	Spécifie le nom de la fonction à supprimer. Ce paramètre est obligatoire.

catalog_name

Spécifie le nom du catalogue.

Ce paramètre est obligatoire.

function_name

Spécifie le nom de la fonction à supprimer.

Ce paramètre est obligatoire.

Erreurs

Code d'erreur	Description
`ORA-20003`	Cette erreur est générée lorsque la fonction spécifiée n'existe pas.

Exemples

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

Procédure LIST_FUNCTIONS

Cette procédure répertorie toutes les fonctions d'un catalogue.

Note : La procédure LIST_FUNCTIONS s'applique uniquement aux fonctions en nuage.

Syntaxe

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

Paramètres

Paramètre Description

credential_name

Spécifie le nom des données d'identification pour l'authentification.

Ce paramètre est obligatoire.

function_list

Retourne la liste des fonctions au format JSON.

Ce paramètre est obligatoire.

catalog_name

Spécifie le nom du catalogue.

Ce paramètre est obligatoire.

Erreurs

Code d'erreur	Description
`ORA-20000`	Cette erreur est générée lorsque des valeurs de paramètre incorrectes sont transmises.
`ORA-20001`	Cette erreur est générée lorsque les données d'identification référencées dans `credential_name` n'existent pas.
`ORA-20003`	Cette erreur est générée lorsque le catalogue spécifié n'existe pas.

Exemple :

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;

Procédure SYNC_FUNCTIONS

Cette procédure permet d'ajouter de nouvelles fonctions au catalogue et de supprimer des fonctions qui ont été supprimées du catalogue.

Note : La procédure SYNC_FUNCTIONS s'applique uniquement aux fonctions en nuage.

Syntaxe

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

Paramètres

Paramètre Description

Paramètre	Description
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.
`refresh_rate`	Spécifie le taux d'actualisation de la fonction. `refresh_rate` peut accepter les valeurs suivantes : `HOURLY` `DAILY` `WEEKLY` `MONTHLY` La valeur par défaut de ce paramètre est `DAILY`.

catalog_name

Spécifie le nom du catalogue.

Ce paramètre est obligatoire.

refresh_rate

Spécifie le taux d'actualisation de la fonction.

refresh_rate peut accepter les valeurs suivantes :

HOURLY
DAILY
WEEKLY
MONTHLY

La valeur par défaut de ce paramètre est DAILY.

Erreurs

Code d'erreur	Description
`ORA-20003`	Cette erreur est générée lorsque le catalogue spécifié n'existe pas.
`ORA-20004`	Cette erreur est générée lorsqu'une valeur non valide est transmise pour le paramètre `refresh_rate`.

Exemple :

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