Documentation Oracle Cloud Infrastructure

Package DBMS_CLOUD_FUNCTION

Le package DBMS_CLOUD_FUNCTION vous permet d'appeler des fonctions distantes OCI et AWS Lambda dans votre instance Autonomous Database en tant que fonctions SQL.

Rubrique parent : Référence de package fourni avec Autonomous Database

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

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 crée un wrapper PL/SQL pour ajouter de nouvelles fonctions au catalogue et supprimer des wrappers pour les fonctions qui ont été supprimées 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-programmes. Cette procédure est surchargée.
  • 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.
  • Procédure DROP_CATALOG
    La procédure DBMS_CLOUD_FUNCTION.DROP_CATALOG supprime le catalogue et les fonctions créés à l'aide du catalogue. Cette procédure est surchargée.
  • Procédure DROP_FUNCTION
    La procédure DBMS_CLOUD_FUNCTION.DROP_FUNCTION supprime la fonction. Cette procédure est surchargée.
  • Procédure LIST_FUNCTIONS
    Cette procédure répertorie toutes les fonctions d'un catalogue.
  • Procédure SYNC_FUNCTIONS
    Cette procédure crée un wrapper PL/SQL pour ajouter de nouvelles fonctions au catalogue et enlever des wrappers pour les fonctions qui ont été supprimées du catalogue.

Rubrique parent : Package DBMS_CLOUD_FUNCTION

CREATE_CATALOG Procédure

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-programmes. 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 comme valeur de paramètre OCI, AWS, AZURE ou GCP.

Ce paramètre est obligatoire.

catalog_name

Indique 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

Spécifie 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 la bibliothèque distante.

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 autosigné 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 cloud_params est manquante ou des valeurs de paramètre incorrectes sont 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 credential_name n'existent pas.

  • Le processus d'écoute spécifié dans 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 fournisseur de service 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 (   
    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;
/

Remarque sur l'utilisation

  • Pour créer un catalogue, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer de privilèges sur les éléments 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. Il existe deux procédures DBMS_CLOUD_FUNCTION.CREATE_FUNCTION surchargées.

Syntaxe CREATE_FUNCTION

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;

Il s'agit d'un type défini par l'utilisateur ou d'un type PL/SQL. function_response est au format JSON avec des champs. 

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

Paramètres CREATE_FUNCTION

CREATE_FUNCTION Exceptions

Paramètre Description

credential_name

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

Ce paramètre est obligatoire.

catalog_name

Indique 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 leur type.

return_type

Définit le type de retour de la fonction.

Le type de retour est CLOB.

response_handler

Spécifie le rappel défini par l'utilisateur pour gérer la réponse.
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 CREATE_FUNCTION 

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

Syntaxe CREATE_FUNCTION 

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 CREATE_FUNCTION

Paramètre Description

library_name

Spécifie 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. Voici les modes de variable suivants :

    • IN

    • OUT

    • IN OUT

  • datatype : spécifie le type de données variable. Ce paramètre est obligatoire.

La valeur par défaut de plsql_params est NULL.

external_params

Spécifie les paramètres à fournir à 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.

Valeur par défaut pour with_context : FALSE.

return_type

Spécifie le type de retour de la fonction créée.

Exemple CREATE_FUNCTION 

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

DROP_CATALOG Procédure

La procédure DBMS_CLOUD_FUNCTION.DROP_CATALOG supprime le catalogue et les fonctions créés à 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

catalog_name

Indique le nom du catalogue.

Ce paramètre est obligatoire.
library_name

Spécifie 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 spécifié n'existe pas.

Exemple : 

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

Exemple : 

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

DROP_FUNCTION Procédure

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

catalog_name

Indique le nom du catalogue.

Ce paramètre est obligatoire.

function_name

Nom de la fonction à supprimer.

Ce paramètre est obligatoire.

library_name

Spécifie 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;
/

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

Indique 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 : 

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 crée un wrapper PL/SQL pour ajouter de nouvelles fonctions au catalogue et supprimer des 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

catalog_name

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