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 Autonomous AI en tant que fonctions SQL.

Prérequis

Pour utiliser des sous-programmes dans le package DBMS_CLOUD_FUNCTION, vous devez être connecté en tant qu'utilisateur ADMIN et accorder les privilèges suivants :

GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_ T TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_FUNCTION TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD TO <user_or_role>;

Récapitulatif des sous-programmes DBMS_CLOUD_FUNCTION

Ce tableau récapitule les sous-programmes inclus dans le package DBMS_CLOUD_FUNCTION.

Sous-programme	Description
Procédure CREATE_CATALOG	Cette procédure crée un catalogue.
Procédure LIST_FUNCTIONS	Cette procédure répertorie toutes les fonctions d'un catalogue.
Procédure CREATE_FUNCTION	Cette procédure crée des fonctions dans un catalogue.
Procédure SYNC_FUNCTIONS	Cette procédure crée un wrapper PL/SQL pour l'ajout de nouvelles fonctions au catalogue et la suppression de wrappers pour les fonctions qui ont été supprimées du catalogue.
Procédure DROP_FUNCTION	Cette procédure supprime des fonctions d'un catalogue.
Procédure DROP_CATALOG	Cette procédure supprime un catalogue et les fonctions créées à l'aide du catalogue.

Procédure CREATE_CATALOG

Cette procédure crée un catalogue dans la base de données. La procédure DBMS_CLOUD_FUNCTION.CREATE_CATALOG crée un catalogue. 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
);

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	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`, `AWS`, `AZURE` ou `GCP`. 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, régions et Azure subscription_id. Ce paramètre est obligatoire.
`library_name`	Indique le nom de la bibliothèque lors de la création d'une bibliothèque distante. Ce paramètre est obligatoire.
`library_listener_url`	Spécifie l'emplacement distant de la bibliothèque. Le paramètre accepte une valeur de chaîne au format `host_name:port_number`. Par exemple : `EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000` Ce paramètre est obligatoire.
`library_remote_path`	Spécifie le chemin de bibliothèque distant. Vous devez fournir le chemin absolu complet de la bibliothèque distante. Par exemple :`/u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so` Ce paramètre est obligatoire.
`library_wallet_dir_name`	Indique le répertoire dans lequel le portefeuille auto-signé est stocké. Ce paramètre est obligatoire.
`library_ssl_server_cert_dn`	Spécifie le nom distinctif (DN) du certificat de serveur. Ce paramètre est obligatoire.

Erreurs

Code d'erreur	Description
`ORA-20000`	Cette erreur est générée dans l'une des conditions suivantes : - La valeur de `cloud_params` est manquante ou des valeurs de paramètre incorrectes ont été transmises. La valeur `library_name` n'est pas unique lors de la création d'une bibliothèque.
`ORA-20001`	Cette erreur est générée dans l'une des conditions suivantes : Les informations d'identification référencées dans le paramètre 'credential_name' n'existent pas. Le processus d'écoute spécifié dans le paramètre 'library_listener_url' n'est pas accessible lors de la création d'une bibliothèque.
`ORA-20002`	Cette erreur est générée dans l'une des conditions suivantes : Cette erreur est générée lorsque le catalogue existe déjà. Le répertoire de certificat de serveur spécifié est vide lors de la création d'une bibliothèque.
`ORA-20009`	Cette erreur est générée lorsque le prestataire 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;
/

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 (
        credential_name  => 'GCP$PA',
        catalog_name     => 'GCP_DEMO_CATALOG',
        service_provider => 'GCP',
        cloud_params     => '{"project_id":"example_XXXXXX"}'
 );
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;
/

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

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 LIST_FUNCTIONS

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 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 la valeur `cloud_params` est manquante ou que 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.

Exemple :

SET SERVEROUTPUT ON
SET LINESIZE 32767
SET LONG 1000000
SET LONGCHUNKSIZE 32767
SET TRIMSPOOL ON
SET WRAP OFF

DECLARE
  l_function_list CLOB;
  l_function_array JSON_ARRAY_T;
  l_object JSON_OBJECT_T;
BEGIN
 DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS(
                                     credential_name => 'DEFAULT_CREDENTIAL',
                                     catalog_name    => 'OCI_DEMO_CATALOG',
                                     function_list   => l_function_list);
  l_function_array := JSON_ARRAY_T.parse(l_function_list);
  FOR i IN 0 .. l_function_array.get_size - 1
  LOOP
     l_object := TREAT(l_function_array.get(i) AS json_object_t);
     dbms_output.put_line('Function ID   = ' || l_object.get_string('functionId'));
     dbms_output.put_line('Function Name = ' || l_object.get_string('functionName'));
     dbms_output.put_line('--------------------------');
  END LOOP;
END;
/

Procédure CREATE_FUNCTION

Cette procédure crée des fonctions dans un catalogue. Il existe deux procédures DBMS_CLOUD_FUNCTION.CREATE_FUNCTION surchargées.

Syntaxe

La procédure DBMS_CLOUD_FUNCTION.CREATE_FUNCTION est uniquement prise en charge 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
);

Signature du gestionnaire de réponses

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

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

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

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, AWS Lambda ou Azure. 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.

Exceptions

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

DECLARE
  function_args CLOB := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
BEGIN
  DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
        catalog_name    => 'OCI_DEMO_CATALOG',
        credential_name => 'DEFAULT_CREDENTIAL',
        function_name   => 'fintech_fun',
        function_id     => 'ocid1.fnfunc.oc1.phx.aaaaaaaazkrbjv6ntowwxlbbp5ct4otsj4o2hdw4ayosyosv4sthmya2lyza',
        input_args      => function_args);
END;
/

Type de syntaxe 2

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

Paramètres pour le type de syntaxe 2

Paramètre	Description
`library_name`	Indique le nom de la bibliothèque distante. 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 aux procédures externes (`extproc`). Si la valeur de `function_id` n'est pas fournie, la valeur de `function_name` est utilisée.
`plsql_params`	Indique la paire JSON de valeur de clé acceptant les paramètres du wrapper PL/SQL. Les valeurs doivent être fournies au format `"var_name":"modetype, datatype"`. `var_name` : nom de la variable. Ce paramètre est obligatoire. `modetype` : indique le mode de variable. Le mode variable peut être l'un des suivants : `IN` `OUT` `IN OUT` `datatype` : indique le type de données de la variable. Ce paramètre est obligatoire. La valeur par défaut pour `plsql_params` est `NULL`.
`external_params`	Indique les paramètres qui doivent être fournis à la fonction C externe. Si aucune valeur n'est fournie pour `external_params`, les paramètres PL/SQL sont utilisés.
`api_type`	Spécifie le type d'API (fonction ou procédure). La valeur par défaut pour `api_type` est `function`.
`with_context`	Indique qu'un pointeur de contexte est transmis à la procédure externe. Ce contexte est utilisé par la bibliothèque C externe pour la connexion à la base de données. La valeur par défaut pour `with_context` est `FALSE`.
`return_type`	Spécifie le type de retour de la fonction créée.

Procédure SYNC_FUNCTIONS

Cette procédure crée un wrapper PL/SQL pour l'ajout de nouvelles fonctions au catalogue et la suppression de wrappers pour les 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

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

Exemple :

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

Procédure DROP_FUNCTION

La procédure DBMS_CLOUD_FUNCTION.DROP_FUNCTION supprime la fonction. Cette procédure est surchargée.

Syntaxe

La procédure DBMS_CLOUD_FUNCTION.DROP_FUNCTION est uniquement prise en charge pour les fonctions cloud.

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

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.
`library_name`	Indique le nom de la bibliothèque. 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.

library_name

Indique le nom de la bibliothèque.

Ce paramètre est obligatoire.

Exemples

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

Procédure DROP_CATALOG

La procédure DBMS_CLOUD_FUNCTION.DROP_CATALOG supprime le catalogue et les fonctions créées à l'aide du catalogue. Cette procédure est surchargée.

Syntaxe

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_name      IN VARCHAR2
 );

Paramètres

Paramètre Description

Paramètre	Description
`catalog_name`	Spécifie le nom du catalogue. Ce paramètre est obligatoire.
`library_name`	Indique le nom de la bibliothèque. Ce paramètre est obligatoire.

catalog_name

Spécifie le nom du catalogue.

Ce paramètre est obligatoire.

library_name

Indique le nom de la bibliothèque.

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.

Exemples

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

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

Documentation Oracle Cloud Infrastructure

Package DBMS_CLOUD_FUNCTION

Prérequis

Récapitulatif des sous-programmes DBMS_CLOUD_FUNCTION

Procédure CREATE_CATALOG

Syntaxe

Paramètres

Erreurs

Exemples

Remarque sur l'utilisation

Procédure LIST_FUNCTIONS

Syntaxe

Paramètres

Erreurs

Exemple :

Procédure CREATE_FUNCTION

Syntaxe

Paramètres

Exceptions

Exemple

Type de syntaxe 2

Paramètres pour le type de syntaxe 2

Procédure SYNC_FUNCTIONS

Syntaxe

Paramètres

Erreurs

Exemple :

Procédure DROP_FUNCTION

Syntaxe

Paramètres

Exemples

Procédure DROP_CATALOG

Syntaxe

Paramètres

Erreurs

Exemples