Effectuer des appels externes à l'aide d'un portefeuille géré par le client

Vous pouvez utiliser le package UTL_HTTP lorsque votre base de données Autonomous AI doit accéder aux données sur Internet via HTTP/HTTPS. Le package UTL_HTTP vous permet d'effectuer des appels HTTP directement à partir de SQL et PL/SQL.

Si vous appelez une adresse HTTPS, vous devez configurer un Oracle Wallet. La base de données Autonomous AI nécessite un portefeuille contenant les certificats racine et intermédiaires sécurisés pour toute adresse HTTPS à laquelle votre base de données se connectera. Le package UTL_HTTP utilise ce portefeuille pour établir une connexion SSL/TLS sécurisée. Vous pouvez créer et gérer le portefeuille à l'aide de l'utilitaire orapki.

Remarque : les demandes HTTP simples (non HTTPS) ne nécessitent pas d'Oracle Wallet.

Les sections ci-dessous expliquent comment configurer et utiliser un portefeuille géré par le client pour effectuer des appels HTTPS sortants avec le package UTL_HTTP sur la base de données Autonomous AI.

Prérequis pour l'utilisation d'un portefeuille géré par le client avec des appels externes

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

Accès à la base de données Autonomous AI à l'aide d'un compte qui peut exécuter PL/SQL et configurer UTL_HTTP.
Accès à l'adresse HTTPS cible et à sa chaîne de certificats complète (certificats racine + intermédiaire).
Poste de travail dans lequel vous pouvez exécuter orapki pour créer et valider un portefeuille Oracle Wallet. Vous devez installer Oracle Database pour obtenir l'utilitaire orapki. Pour plus d'informations, reportez-vous à Installation d'Oracle Database.

Préparer le portefeuille géré par le client

Cette étape consiste à créer et à valider le portefeuille sur votre station de travail avant de le télécharger vers la base de données Autonomous AI.

Obtenir ou créer un portefeuille géré par le client

Exemple d'utilisation de orapki :

-- Create an SSL Wallet and load the Root CERTs using orapki utility
$ORACLE_HOME/bin/orapki wallet create -wallet /u01/web/wallet -pwd ********
$ORACLE_HOME/bin/orapki wallet add -wallet /u01/web/wallet -trusted_cert -cert MyWebServer.cer -pwd ********
-- Store the credentials in the SSL Wallet using mkstore utility
$ORACLE_HOME/bin/mkstore -wrl /u01/web/wallet -createCredential secret-from-the-wallet 'example@oracle.com'
********Enter wallet password: ********

Valider le portefeuille

$ORACLE_HOME/bin/orapki wallet display -wallet /u01/web/wallet

Tous les certificats importés doivent être répertoriés.

Télécharger le portefeuille vers le serveur

Une fois le portefeuille géré par le client prêt (y compris tous les certificats auto-signés/root/intermédiaires requis), téléchargez les fichiers de portefeuille vers un emplacement dans Oracle Cloud Infrastructure (OCI) Object Storage.

Utiliser un portefeuille géré par le client avec UTL_HTTP

Cette section indique comment télécharger votre portefeuille à partir d'Object Storage, autoriser l'accès réseau à l'adresse HTTPS, puis effectuer des appels HTTPS à l'aide du package UTL_HTTP.

Créez des informations d'identification pour l'accès à Object Storage :
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
Les valeurs fournies pour username et password dépendent du service Cloud Object Storage que vous utilisez . Vous créez ainsi les informations d'identification que vous utilisez pour accéder au stockage d'objet cloud où réside le portefeuille géré par le client.
Créez (ou réutilisez) un objet répertoire pour le portefeuille :

Utilisez un répertoire existant ou créez un répertoire pour le fichier de portefeuille. Exemple :
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Pour plus d'informations sur la création de répertoires, reportez-vous à Création d'un répertoire dans la base de données Autonomous AI.
Obtenez le chemin absolu du répertoire :

Vous aurez besoin du chemin de répertoire absolu lors de l'appel de UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Téléchargez le fichier de portefeuille à partir d'Object Storage dans le répertoire :

Utilisez DBMS_CLOUD.GET_OBJECT pour copier le fichier de portefeuille dans votre répertoire. 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 Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

Autoriser l'accès réseau sortant (ACL) à l'adresse HTTPS :

Vous devez autoriser l'utilisateur/le schéma de base de données à atteindre l'hôte cible sur le réseau.

  BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
       host => 'api.example.com',
       ace  => xs$ace_type(
       privilege_list => xs$name_list('CONNECT','HTTP','RESOLVE'),
       principal_name => 'ADMIN',
       principal_type => xs_acl.ptype_db
   )
 );
 END;
 /

Sur les déploiements Exadata Cloud@Customer, vous devez également configurer un proxy comme indiqué ci-dessous :

 BEGIN
   UTL_HTTP.SET_PROXY('www-proxy.us.oracle.com:80', 'oracle.com');
 END;
 /

Passez des appels HTTPS avec UTL_HTTP :

Demande GET simple :

 DECLARE
 l_http_req UTL_HTTP.req;
 l_http_resp UTL_HTTP.resp;
 l_response VARCHAR2(32767);

 BEGIN
    utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
    l_http_req := UTL_HTTP.BEGIN_REQUEST('https://api.example.com/status');
    l_http_resp := UTL_HTTP.GET_RESPONSE(l_http_req);
    LOOP UTL_HTTP.READ_LINE(l_http_resp, l_response, TRUE);
        DBMS_OUTPUT.PUT_LINE(l_response);
    END LOOP;
    UTL_HTTP.END_RESPONSE(l_http_resp);
 END;
 /

Demande POST avec charge utile JSON :

 DECLARE
   l_req UTL_HTTP.req;
   l_resp UTL_HTTP.resp;
   l_line VARCHAR2(32767);
 BEGIN
   utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
   l_req := UTL_HTTP.BEGIN_REQUEST( url => 'https://api.example.com/data', method => 'POST' );
   UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
   UTL_HTTP.WRITE_TEXT(l_req, '{"key":"value"}');
   l_resp := UTL_HTTP.GET_RESPONSE(l_req);
   LOOP UTL_HTTP.READ_LINE(l_resp, l_line, TRUE);
     DBMS_OUTPUT.PUT_LINE(l_line);
   END LOOP;
   UTL_HTTP.END_RESPONSE(l_resp);
  END;
  /

Dépannage des erreurs courantes :

Erreurs de chaîne de certificat

Erreur : ORA-29024: Certificate validation failure

Les certificats racine et intermédiaires sont peut-être manquants.
L'adresse cible peut utiliser une nouvelle autorité de certification : téléchargez à nouveau la chaîne de certificat complète et recréez le portefeuille.

Erreurs de chemin de portefeuille

ORA-28759: Failure to open file

Chemin de portefeuille incorrect dans SET_WALLET.
Préfixe file: manquant.
Les fichiers de portefeuille téléchargés sont absents du répertoire.

Echecs d'établissement de la liaison

ORA-24263 / ORA-29005

Non-concordance du protocole TLS.
Certificats incorrects ou expirés.
L'adresse applique TLS > 1,2

Utiliser un portefeuille géré par le client pour les notifications par e-mail du planificateur (SMTP)

Cette section explique comment configurer les notifications par e-mail du planificateur pour utiliser un serveur SMTP via TLS (STARTTLS) avec un portefeuille géré par le client.

Avant de commencer, assurez-vous que vous avez déjà préparé le portefeuille géré par le client (créé localement, validé et téléchargé vers Object Storage). Pour plus d'informations, reportez-vous à Préparer le portefeuille géré par le client.

Pour utiliser un portefeuille géré par le client avec le serveur de messagerie du planificateur, procédez comme suit :

Créez des informations d'identification pour l'accès à Object Storage :

Vous pouvez utiliser DBMS_CLOUD.CREATE_CREDENTIAL pour créer des informations d'identification afin d'accéder à Cloud Object Storage.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
Les valeurs fournies pour username et password dépendent du service Cloud Object Storage que vous utilisez . Vous créez ainsi les informations d'identification que vous utilisez pour accéder au stockage d'objet cloud où réside le portefeuille géré par le client.
Créez (ou réutilisez) un objet répertoire pour le portefeuille :

Utilisez un répertoire existant ou créez un répertoire pour le fichier de portefeuille. Exemple :
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Pour plus d'informations sur la création de répertoires, reportez-vous à Création d'un répertoire dans la base de données Autonomous AI.
Obtenez le chemin absolu du répertoire :

Vous aurez besoin du chemin de répertoire absolu lors de l'appel de UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Téléchargez le fichier de portefeuille à partir d'Object Storage dans le répertoire :

Utilisez DBMS_CLOUD.GET_OBJECT pour copier le fichier de portefeuille dans votre répertoire. 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 Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

Configurer l'adresse électronique du planificateur (SMTP + STARTTLS) :

Exécutez les commandes pour configurer le planificateur afin qu'il envoie un courriel SMTP pour les notifications de travail du planificateur :

 EXEC DBMS_CLOUD.CREATE_CREDENTIAL('EMAIL_CRED', '<user_ocid>', '<password>');
 GRANT EXECUTE ON admin.EMAIL_CRED TO sys;
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
       'EMAIL_SERVER',
       'smtp.email.us-ashburn-1.oci.oraclecloud.com:587'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_CREDENTIAL',
         'EMAIL_CRED'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_ENCRYPTION',
         'STARTTLS'
 );

Les commandes effectuent les opérations suivantes :

Définit l'adresse SMTP du planificateur (EMAIL_SERVER)
Stocke les détails de connexion SMTP dans EMAIL_CRED et pointe le planificateur vers celui-ci
Active le cryptage TLS à l'aide de STARTTLS

Pour plus d'informations, voir Procédure SET_SCHEDULER_ATTRIBUTE.

Créez des informations d'identification pour le mot de passe de portefeuille :

Créez des informations d'identification pour stocker le mot de passe du portefeuille géré par le client.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
Les informations d'identification que vous utilisez à l'étape suivante sont ainsi créées pour fournir le mot de passe du portefeuille géré par le client.

Indiquez au planificateur où se trouve le portefeuille et comment le déverrouiller :

Définissez le répertoire du portefeuille du planificateur et les informations d'identification du portefeuille.

 BEGIN
   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_DIRECTORY',
     'WALLET_DIR'
   );

   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_CREDENTIAL',
     'ADMIN.WALLET_CRED'
   );
 END;
 /

Vérifiez la configuration des courriels du planificateur :

Interrogez la vue DBA_SCHEDULER_GLOBAL_ATTRIBUTE pour vérifier les valeurs que vous avez définies dans les étapes précédentes.

 SELECT attribute_name, value
 FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE
 WHERE attribute_name LIKE 'EMAIL_SERVER%' ORDER BY 1, 2;

 ATTRIBUTE_NAME                 VALUE

 ------------------------------ -----------------------------------------------
 EMAIL_SERVER                   smtp.email.us-ashburn-1.oci.oraclecloud.com:587
 EMAIL_SERVER_CREDENTIAL        "ADMIN"."EMAIL_CRED"
 EMAIL_SERVER_ENCRYPTION        STARTTLS
 EMAIL_SERVER_WALLET_CREDENTIAL "ADMIN"."WALLET_CRED"
 EMAIL_SERVER_WALLET_DIRECTORY  "WALLET_DIR"

Référence

Commandes orapki utiles :

orapki wallet display -wallet <path> orapki wallet add -wallet <path>
-trusted_cert -cert <cert-file> orapki wallet create -wallet <path> -auto_login

Exemple de structure de répertoires de portefeuille :

cmw_wallet/
- ewallet.p12
- cwallet.sso