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

Vous pouvez utiliser l'ensemble UTL_HTTP lorsque votre base de données d'intelligence artificielle autonome doit accéder aux données sur Internet par HTTP/HTTPS. L'ensemble UTL_HTTP vous permet d'effectuer des appels de programmes externes HTTP directement à partir de SQL et de PL/SQL.

Si vous appelez un point d'extrémité HTTPS, vous devez configurer un Oracle Wallet. Autonomous AI Database nécessite un portefeuille qui contient les certificats racine et intermédiaire approuvés pour tout point d'extrémité HTTPS auquel votre base de données se connectera. L'ensemble 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.

Note : Les demandes HTTP simples (non HTTPS) ne nécessitent pas 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 l'ensemble UTL_HTTP sur Autonomous AI Database.

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

Avant de commencer, assurez-vous d'avoir :

Accédez à la base de données d'IA autonome à l'aide d'un compte qui peut exécuter PL/SQL et configurer UTL_HTTP.
Accès au point d'extrémité HTTPS cible et à sa chaîne de certificats complète (racine + certificats intermédiaires).
Poste de travail où 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 de détails, voir Installation d'Oracle Database.

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

Au cours de cette étape, vous allez créer et valider le portefeuille sur votre poste de travail avant de le charger dans Autonomous AI Database.

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

Exemple avec 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 s'afficher.

Charger le portefeuille

Une fois le portefeuille géré par le client prêt (y compris les certificats auto-signés, racine ou intermédiaire requis), chargez les fichiers de portefeuille dans un emplacement du service de stockage d'objets pour Oracle Cloud Infrastructure (OCI).

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

Cette section explique comment télécharger votre portefeuille à partir du service de stockage d'objets, autoriser l'accès réseau au point d'extrémité HTTPS, puis effectuer des appels HTTPS à l'aide du paquetage UTL_HTTP.

Créez des données d'identification pour l'accès au stockage d'objets :
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
Les valeurs que vous indiquez pour username et password dépendent du service de stockage d'objets en nuage que vous utilisez . Les données d'identification que vous utilisez pour accéder au service de stockage d'objets en nuage où réside le portefeuille géré par le client.
Créez (ou réutilisez) un objet répertoire pour le "wallet" :

Utilisez un répertoire existant ou créez un nouveau répertoire pour le fichier de portefeuille. Par exemple :
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Voir Créer un répertoire dans Autonomous AI Database pour plus d'informations sur la création de répertoires.
Obtenir le chemin absolu du répertoire :

Vous aurez besoin du chemin d'accès absolu au répertoire 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 du stockage d'objets dans le répertoire :

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

Autoriser l'accès réseau sortant au point d'extrémité 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;
 /

Dans les déploiements Exadata Cloud@Customer, vous devez également configurer le mandataire comme indiqué ci-dessous :

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

Effectuez 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 données utiles 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 certificats

Erreur : ORA-29024: Certificate validation failure

Les certificats racine et intermédiaire sont peut-être manquants.
Le point d'extrémité cible utilise peut-être une nouvelle autorité de certification - rechargez la chaîne de certification complète et recréez le portefeuille.

Erreurs de chemin d'accès au portefeuille

ORA-28759: Failure to open file

Chemin d'accès au portefeuille incorrect dans SET_WALLET.
Préfixe file: manquant.
Les fichiers de portefeuille chargés ne sont pas présents dans le répertoire.

Échecs de poignée de main

ORA-24263 / ORA-29005

Non-concordance du protocole TLS.
Certificats incorrects ou expirés.
Le point d'extrémité applique TLS > 1.2

Utiliser un portefeuille géré par le client pour les avis par courriel du programmateur (SMTP)

Cette section explique comment configurer les avis par courriel du programmateur pour qu'il utilise un serveur SMTP sur TLS (STARTTLS) avec un portefeuille géré par le client.

Avant de commencer, assurez-vous d'avoir déjà préparé le portefeuille géré par le client (il a été créé localement, validé et chargé dans le service de stockage d'objets). Voir Préparer le portefeuille géré par le client pour plus de détails.

Pour utiliser un portefeuille géré par le client avec le serveur de courriel du programmateur :

Créez des données d'identification pour l'accès au service de stockage d'objets :

Vous pouvez utiliser DBMS_CLOUD.CREATE_CREDENTIAL pour créer des données d'identification pour accéder au service de stockage d'objets en nuage.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
Les valeurs que vous indiquez pour username et password dépendent du service de stockage d'objets en nuage que vous utilisez . Les données d'identification que vous utilisez pour accéder au service de stockage d'objets en nuage où réside le portefeuille géré par le client.
Créez (ou réutilisez) un objet répertoire pour le "wallet" :

Utilisez un répertoire existant ou créez un nouveau répertoire pour le fichier de portefeuille. Par exemple :
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Voir Créer un répertoire dans Autonomous AI Database pour plus d'informations sur la création de répertoires.
Obtenir le chemin absolu du répertoire :

Vous aurez besoin du chemin d'accès absolu au répertoire 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 du stockage d'objets dans le répertoire :

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

Configurer le courriel du programmateur (SMTP + STARTTLS) :

Exécutez les commandes pour configurer le programmateur afin d'envoyer un courriel SMTP pour les avis de tâche du programmateur :

 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 le point d'extrémité SMTP du programmateur (EMAIL_SERVER)
Stocke les détails de connexion SMTP dans EMAIL_CRED et y pointe le programmateur
Active le chiffrement TLS à l'aide de STARTTLS

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

Créez des données d'identification pour le mot de passe du portefeuille :

Créez des données 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;
 /
```
Cela crée les données d'identification que vous utilisez à l'étape suivante pour fournir le mot de passe du portefeuille géré par le client.

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

Définissez le répertoire du portefeuille du programmateur et les données 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 du courriel du programmateur :

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"

Informations de 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épertoire de portefeuille :

cmw_wallet/
- ewallet.p12
- cwallet.sso