Package DBMS_CLOUD

Package DBMS_CLOUD_FUNCTION

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

Remarques :

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.

Récapitulatif des sous-programmes DBMS_CLOUD_FUNCTION

Ce tableau récapitule les sous-programmes inclus dans le package 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 des 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 des 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-routines. Cette procédure est surchargée.

Syntaxe

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

Paramètres

Paramètre	Description
`credential_name`	Spécifie le nom des informations d'identification pour l'authentification. Ce paramètre est obligatoire.
`service_provider`	Indique le type du fournisseur de services. Ce paramètre peut avoir pour valeur de paramètre `OCI` ou `AWS`. 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 de compartiment et régions. Ce paramètre est obligatoire.

Exemples

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 d'informations d'identification. Les paramètres nécessitent les spécifications de la machine virtuelle EXTPROC et de la bibliothèque partagée qui contient les procédures externes. Reportez-vous à Présentation des procédures externes.

Syntaxe

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

Paramètre	Descriptions
`library_name`	Spécifie le nom fourni au catalogue/à la bibliothèque dans la base de données. Ce paramètre est obligatoire.
`library_listener_url`	Spécifie le nom de domaine qualifié complet (FQDN) 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 processus d'écoute SQL*Net exécuté dans le conteneur de machine virtuelle EXTPROC accepte les demandes de connexion. Le paramètre est spécifié sous forme de chaîne au format `host_name:port_number`. Exemple : `'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'` Ce paramètre est obligatoire.
`library_wallet_dir_name`	Indique le nom de l'annuaire dans la base de données dans laquelle le portefeuille auto-signé a été importé et stocké.
`library_ssl_server_cert_dn`	Indique le nom distinctif (DN) du certificat de serveur obtenu à partir du portefeuille. 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. Exemple : `'/u01/app/oracle/extproc_libs/helloCextproc.so'` Ce paramètre est obligatoire.

Exemples

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 sont transmises.
`ORA-20001`	Cette erreur est générée dans la condition suivante : Les informations 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 prestataire de services n'existe pas.

Remarque sur l'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 cloud correspondante dans votre catalogue. Alors 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 est applicable uniquement aux fonctions cloud.

Syntaxe

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

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 au format suivant :

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

La valeur renvoyée par response_handler est <Type défini par l'utilisateur> et response_json est un document JSON avec deux champs, au format suivant :

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

Paramètres

Paramètre	Description
`credential_name`	Spécifie le nom des informations 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 JSON de valeur de clé acceptant les arguments d'entrée et leurs types.
`return_type`	Définit le type d'effet renvoyé par la fonction. Le type de retour est de type `CLOB`.
`response_handler`	Spécifie le callback défini par l'utilisateur pour gérer la réponse.

Erreurs

Code d'erreur	Description
`ORA-20001`	Cette erreur est générée lorsque les informations 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 de fonction ou la fonction Amazon Resource Names (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 gestionnaire de réponses est manquant ou non valide.

Exemple

Le cas simple avec seulement 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 de wrapper 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 DESCRIBER 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;
/

La fonction cloud fintech_fun est appelée en appelant la référence de fonction oocid1.funfn.oci.phx.aaaaaa_example dans le catalogue OCI_DEMO_CATALOG.

Remarques sur l'utilisation

Pour appeler des procédures externes, vous pouvez utiliser la même syntaxe que celle utilisée 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 indiqué 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 indiqué n'existe pas.

Par 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 cloud.

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.

Remarques :

La procédure LIST_FUNCTIONS est applicable uniquement aux fonctions cloud.

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 informations d'identification pour l'authentification.

Ce paramètre est obligatoire.

function_list

Renvoie 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 informations 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.

Par 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 des fonctions au catalogue et de supprimer des fonctions qui ont été supprimées du catalogue.

Remarques :

La procédure SYNC_FUNCTIONS est applicable uniquement aux fonctions cloud.

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`	Indique la fréquence 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

Indique la fréquence 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`.

Par exemple :


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

Informations relatives au titre et au copyright

Oracle et/ou ses affiliés.