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 Autonomous AI Database 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.

Tableau - Sous-programmes DBMS_CLOUD_FUNCTION

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

CREATE_CATALOG Procédure

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.

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

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.

Exemples

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

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

CREATE_FUNCTION Procédure

Cette procédure crée des fonctions dans un catalogue.

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

Signature du programme de traitement des réponses

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

Le type de retour correspond au type défini par l'utilisateur ou au type PL/SQL. function_response est en JSON avec des champs. 

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

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

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

DROP_CATALOG Procédure

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

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

DROP_FUNCTION Procédure

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

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

LIST_FUNCTIONS Procédure

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

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;

SYNC_FUNCTIONS Procédure

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

Syntaxe

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

Paramètres

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