Documentation Oracle Cloud Infrastructure

Appel de scripts génériques sur une instance Autonomous Database

Vous pouvez appeler des scripts génériques, de type BASH, C ou Python sur votre instance Autonomous Database.

Rubrique parent : Appel de fonctions définies par l'utilisateur

A propos de l'exécution de scripts génériques sur Autonomous Database

Vous pouvez appeler des scripts génériques, y compris des scripts écrits en Bash, C ou Python, à partir d'une instance Autonomous Database.

Vous ne pouvez pas exécuter un script générique directement sur une instance Autonomous Database. Le script est hébergé à distance sur une image de conteneur Oracle Autonomous Database Extproc exécutée sur un réseau cloud virtuel Oracle Cloud Infrastructure (VCN). Vous appelez des scripts génériques à partir de votre instance Autonomous Database à l'aide des travaux Oracle Scheduler. Le travail Oracle Scheduler que vous créez doit être un travail exécutable. Les travaux exécutables peuvent exécuter des scripts shell ou d'autres exécutables.

Remarque

Cette fonctionnalité est uniquement prise en charge pour la version 19c de la base de données Oracle.

Les scripts génériques de votre instance Autonomous Database ne sont pris en charge que lorsque votre base de données se trouve sur une adresse privée. Pour exécuter des scripts génériques, vous devez obtenir, installer et configurer l'image de conteneur Oracle Autonomous Database avec l'agent EXTPROC installé. L'image de conteneur Autonomous Database EXTPROC vous permet d'appeler des procédures et des scripts externes écrits en BASH, C ou Python à partir de votre instance Autonomous Database. L'instance d'agent EXTPROC est hébergée sur un sous-réseau privé et Autonomous Database accède à l'agent EXTPROC via une adresse de connexion inverse (RCE).

Les scripts génériques sont déployés à l'aide des éléments suivants :

  • Une image de conteneur Autonomous Database fournie par Oracle avec l'agent EXTPROC installé. Oracle fournit l'image de conteneur sur les packages GitHub.

    Reportez-vous au fichier GitHub README pour obtenir des instructions sur l'obtention et la configuration de l'image de conteneur EXTPROC :

    L'instance d'agent EXTPROC est hébergée à distance sur une image de conteneur exécutée dans un réseau cloud virtuel Oracle Cloud Infrastructure (VCN). La communication sécurisée entre votre instance Autonomous Database et l'instance d'agent EXTPROC est sécurisée en définissant des règles de groupe de sécurité réseau de sorte que le trafic soit autorisé entre l'instance Autonomous Database exécutée sur une adresse privée et l'instance d'agent EXTPROC. L'image de l'agent EXTPROC est préconfigurée pour héberger et exécuter des procédures externes sur le port 16000.

  • Procédures PL/SQL permettant d'inscrire des environnements d'adresse et de gérer les privilèges sur les adresses inscrites. Pour plus d'informations, reportez-vous à la section DBMS_CLOUD_FUNCTION_ADMIN Package.

  • Procédures PL/SQL permettant de créer et de gérer des travaux et des programmes du planificateur pour appeler des scripts génériques.

    Pour plus d'informations, reportez-vous à DBMS_SCHEDULER.

Pour exécuter un script générique à partir d'une instance Autonomous Database, procédez comme suit :

Télécharger le portefeuille pour créer une connexion sécurisée à l'instance d'agent EXTPROC

Un portefeuille auto-signé est créé dans le cadre de la création de l'application d'agent EXTPROC. Ce portefeuille vous permet d'accéder à l'instance d'agent EXTPROC à partir d'une instance Autonomous Database.

Pour exécuter des scripts génériques sur l'instance d'agent EXTPROC, l'instance Autonomous Database et l'agent EXTPROC se connectent à l'aide de Mutual Transport Layer Security (mTLS). Lorsque vous connectez à l'agent EXTPROC avec mTLS, vous utilisez une connexion de base de données TCPS (Secure TCP) à l'aide du protocole TLS 1.2 standard avec un certificat d'autorité de certification (CA) client sécurisé. Pour plus d'informations, reportez-vous à A propos de la connexion à une instance Autonomous Database.

Remarque

Vous pouvez également obtenir et utiliser un certificat public émis par une autorité de certification.

Vous devez au préalable exporter le portefeuille vers Object Storage à partir du répertoire /u01/app/oracle/wallets/extproc_wallet/ sur la machine virtuelle où EXTPROC est exécuté. Autonomous Database peut ainsi utiliser le portefeuille pour accéder en toute sécurité à EXTPROC.

Téléchargez le portefeuille EXTPROC vers l'instance Autonomous Database :

  1. Importez le portefeuille cwallet.sso contenant les certificats de l'instance d'agent EXTPROC à partir d'Object Storage dans votre instance Autonomous Database. Pour le fichier de portefeuille, tenez compte des points suivants :

    • Le fichier de portefeuille, ainsi que l'ID utilisateur et le mot de passe de base de données, permettent d'accéder à l'instance d'agent EXTPROC. Stockez les fichiers de portefeuille dans un emplacement sécurisé et partagez-les uniquement avec les utilisateurs autorisés.

    • Ne renommez pas le fichier de portefeuille. Le fichier de portefeuille dans Object Storage doit être nommé cwallet.sso.

  2. Créez des informations d'identification pour accéder à Object Storage dans lequel stocker le fichier de portefeuille cwallet.sso. Pour plus d'informations sur les paramètres de nom utilisateur et de mot de passe des différents services Object Storage, reportez-vous à Procédure CREATE_CREDENTIAL.
    La création d'informations d'identification pour accéder à la banque d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les informations d'identification de principal de ressource. Pour plus d'informations, reportez-vous à A propos de l'utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.
  3. Créez un répertoire sur Autonomous Database pour le fichier de portefeuille cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Pour plus d'informations sur la création de répertoires, reportez-vous à Création d'un répertoire dans Autonomous Database.

  4. Utilisez DBMS_CLOUD.GET_OBJECT pour télécharger le portefeuille à partir d'Object Storage. Par exemple :
    BEGIN
  DBMS_CLOUD.GET_OBJECT (
    credential_name     => 'DEF_CRED_NAME',
    object_uri          => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
    directory_name      => 'WALLET_DIR'
);
END;
/

    Dans cet exemple, namespace-string est l'espace de noms d'objet Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Espaces de nom Object Storage.

    Le portefeuille est copié dans le répertoire créé à l'étape précédente, WALLET_DIR. Le portefeuille qui vous permet de vous connecter à l'instance d'agent EXTPROC est désormais disponible sur votre instance Autonomous Database.

Etapes d'appel de scripts génériques

Affiche les étapes permettant d'appeler des scripts génériques sur une instance Autonomous Database.

Une fois que vous avez configuré l'instance d'agent EXTPROC pour exécuter des scripts génériques, vous inscrivez une adresse distante et créez des travaux de planificateur pour appeler des scripts génériques.

Les prérequis suivants permettent d'appeler des scripts génériques avec Autonomous Database :

  • Les scripts génériques doivent être copiés dans l'instance d'agent EXTPROC. Pour plus d'informations, reportez-vous à GitHub README.

  • Pour créer et gérer des travaux du planificateur afin d'appeler des scripts génériques avec un utilisateur autre qu'ADMIN, vous devez disposer des privilèges suivants :

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilège sur l'adresse distante inscrite

Sujets

Rubrique parent : Appel de scripts génériques sur une instance Autonomous Database

Inscription et gestion d'une adresse distante sur Autonomous Database

En tant qu'utilisateur ADMIN, procédez comme suit pour inscrire et gérer des adresses distantes dans votre instance Autonomous Database.

Inscription d'une adresse distante

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV pour inscrire une adresse distante.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV (
        remote_endpoint_name => 'rem_executable',
        remote_endpoint_url  => 'remote_extproc_hostname:16000',
        wallet_dir           => 'WALLET_DIR',
        remote_cert_dn       => 'CN=MACHINENAME'
);
END;
/

Cet exemple crée la bibliothèque rem_executable et inscrit l'instance d'agent EXTPROC indiquée dans le paramètre remote_url dans votre instance Autonomous Database. L'instance d'agent EXTPROC est préconfigurée pour héberger des scripts génériques sur le port 16000.

Pour plus d'informations, reportez-vous à Procédure REGISTER_REMOTE_EXECUTION_ENV.

Gestion des privilèges sur une adresse inscrite

Cette étape est facultative et n'est requise que lorsqu'un utilisateur autre que l'administrateur doit appeler des scripts génériques à partir d'Autonomous Database.

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV pour accorder le privilège sur l'adresse inscrite à un utilisateur autre que l'administrateur.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Cet exemple accorde le privilège sur REM_EXECUTABLE à l'utilisateur indiqué. Pour plus d'informations, reportez-vous à Procédure GRANT_REMOTE_EXECUTION_ENV.

Une fois que vous avez accordé le privilège sur l'adresse inscrite, vous pouvez utiliser DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV pour révoquer le privilège sur l'adresse inscrite en tant qu'utilisateur.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Cet exemple révoque le privilège sur REM_EXECUTABLE de l'utilisateur indiqué. Pour plus d'informations, reportez-vous à Procédure REVOKE_REMOTE_EXECUTION_ENV.

Vous pouvez interroger DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT pour répertorier les droits d'accès accordés à toutes les adresses distantes. Pour plus d'informations, reportez-vous à DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT View.

Suppression d'une adresse inscrite

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV pour enlever une adresse distante inscrite.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE');
END;
/

Cette opération enlève l'adresse distante rem_executable de votre instance Autonomous Database. Pour plus d'informations, reportez-vous à Procédure DEREGISTER_REMOTE_EXECUTION_ENV.

Créer et gérer des travaux du planificateur pour appeler des scripts génériques

Affiche les étapes permettant de créer et de gérer des travaux de planificateur pour appeler des scripts génériques à partir d'Autonomous Database.

Pour exécuter les étapes suivantes en tant qu'utilisateur autre que l'administrateur, vous devez disposer des privilèges requis. Pour plus d'informations, reportez-vous à Etapes d'appel de scripts génériques.
  1. Utilisez DBMS_SCHEDULER.CREATE_JOB pour créer un travail de planificateur avec le type de travail executable.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.CREATE_JOB (
    job_name             => 'rem_exec_job',
    job_type             => 'executable',
    job_action           => 'script_location_in_remote_docker_image/name',
    number_of_arguments  => 1,
    enabled              => false,
    auto_drop            => true);
 END;
/

    Cet exemple crée le travail de planificateur rem_exec_job de type exécutable.

    Le paramètre job_name spécifie le nom du travail.

    Le paramètre job_type indique le type d'action de travail. Vous devez indiquer job_type en tant qu'exécutable pour appeler des scripts génériques sur votre instance Autonomous Database.

    Le paramètre job_action indique l'action en ligne du travail. Il s'agit de l'emplacement du script sur l'adresse distante que vous devez appeler.

    Le paramètre number_of_arguments indique le nombre d'arguments de travail.

    Le paramètre enabled indique si le travail doit être activé immédiatement après sa création.

    Le paramètre auto_drop indique si le travail doit être supprimé une fois terminé.

  2. Utilisez DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE pour définir la valeur de l'argument de travail.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE (
    job_name          => 'rem_exec_job',
    argument_position => 1,
    argument_value    => 'param1');
 END;
/
  3. Utilisez DBMS_SCHEDULER.CREATE_JOB pour modifier l'attribut destination du travail rem_exec_job.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.SET_ATTRIBUTE (
      name       => 'rem_exec_job',
      attribute  => 'destination',
      value      => 'REMOTE_EXTPROC:remote_endpoint_name');
 END;
/

    Cet exemple modifie l'attribut destination du travail rem_exec_job pour spécifier le chemin de bibliothèque distante.

    Le paramètre job_name spécifie le nom du travail.

    Le paramètre attribute indique l'attribut à modifier.

    Le paramètre value modifie l'attribut destination pour indiquer la destination d'adresse distante.

    Le paramètre accepte une valeur de chaîne au format REMOTE_EXTPROC:remote_endpoint_name, où remote_endpoint_name est le nom de l'adresse distante enregistrée.

    Une erreur est détectée si vous ne disposez pas de privilèges sur l'adresse indiquée.

    Pour plus d'informations, reportez-vous à sous-programmes DBMS_SCHEDULER.

  4. Exécutez DBMS_SCHEDULER.ENABLE le travail de planificateur.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.ENABLE (
    name => 'rem_exec_job');
 END; 
/

    Cet exemple active le travail rem_exec_job. Pour plus d'informations, reportez-vous à DBMS_SCHEDULER.

    Une fois le travail activé, le planificateur commence à l'exécuter.

    Interrogez les vues USER_CLOUD_FUNCTION_RUN_DETAILS et DBA_CLOUD_FUNCTION_RUN_DETAILS pour visualiser le statut des travaux du planificateur.