Effettua chiamate esterne utilizzando un wallet gestito dal cliente

È possibile utilizzare il package UTL_HTTP quando Autonomous AI Database deve accedere AI dati su Internet tramite HTTP/HTTPS. Il pacchetto UTL_HTTP consente di effettuare callout HTTP direttamente da SQL e PL/SQL.

Se si chiama un endpoint HTTPS, è necessario configurare un endpoint Oracle Wallet. Autonomous AI Database richiede un wallet che contenga i certificati radice e intermedi sicuri per qualsiasi endpoint HTTPS a cui si connetterà il database. Il pacchetto UTL_HTTP utilizza questo wallet per stabilire una connessione SSL/TLS sicura. È possibile creare e gestire il wallet con la utility orapki.

Nota: le richieste HTTP (non HTTPS) non richiedono Oracle Wallet.

Le sezioni riportate di seguito spiegano come configurare e utilizzare un wallet gestito dal cliente per effettuare chiamate HTTPS in uscita con il package UTL_HTTP su Autonomous AI Database.

Prerequisiti per l'uso di un wallet gestito dal cliente con chiamate esterne

Prima di iniziare, assicurarsi di disporre degli elementi riportati di seguito.

Accedi ad Autonomous AI Database utilizzando un account in grado di eseguire PL/SQL e configurare UTL_HTTP.
Accesso all'endpoint HTTPS di destinazione e alla relativa catena di certificati completa (root + certificati intermedi).
Una workstation in cui è possibile eseguire orapki per creare e convalidare un Oracle Wallet. È necessario installare Oracle Database per ottenere la utility orapki. Per informazioni dettagliate, vedere Installazione di Oracle Database.

Prepara il wallet gestito dal cliente

In questo passo, creerai e convaliderai il wallet sulla tua workstation prima di caricarlo in Autonomous AI Database.

Ottenere o creare un wallet gestito dal cliente

Esempio con 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: ********

Convalida wallet

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

Dovresti vedere tutti i certificati importati elencati.

Carica il wallet

Una volta che il wallet gestito dal cliente è pronto (inclusi eventuali certificati autofirmati/root/intermediati necessari), caricare i file del wallet in una posizione nello storage degli oggetti Oracle Cloud Infrastructure (OCI).

Usa un wallet gestito dal cliente con UTL_HTTP

Questa sezione mostra come scaricare il wallet dallo storage degli oggetti, consentire l'accesso di rete all'endpoint HTTPS, quindi effettuare chiamate HTTPS utilizzando il package UTL_HTTP.

Creare una credenziale per l'accesso allo storage degli oggetti:
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
I valori forniti per username e password dipendono dal servizio di storage degli oggetti cloud in uso. In questo modo viene creata la credenziale utilizzata per accedere allo storage degli oggetti cloud in cui risiede il wallet gestito dal cliente.
Creare (o riutilizzare) un oggetto directory per il wallet:

Utilizzare una directory esistente o crearne una nuova per il file wallet. Ad esempio:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Per informazioni sulla creazione di directory, vedere Crea directory in Autonomous AI Database.
Recupera il percorso assoluto della directory:

È necessario il percorso assoluto della directory quando si chiama UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Scaricare il file wallet dallo storage degli oggetti nella directory:

Utilizzare DBMS_CLOUD.GET_OBJECT per copiare il file wallet nella directory. Ad esempio:
```
 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;
 /
```
In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

Consentire l'accesso di rete in uscita (ACL) all'endpoint HTTPS:

È necessario consentire all'utente/schema del database di raggiungere l'host di destinazione sulla rete.

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

Nelle distribuzioni Exadata Cloud@Customer, è inoltre necessario impostare il proxy come mostrato di seguito:

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

Effettuare chiamate HTTPS con UTL_HTTP:

Richiesta GET semplice:

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

Richiesta POST con payload 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;
  /

Risoluzione dei problemi relativi agli errori comuni:

Errori della catena di certificati

Errore: ORA-29024: Certificate validation failure

Potrebbero mancare i certificati radice e intermedi.
L'endpoint di destinazione potrebbe utilizzare una nuova CA: scaricare di nuovo la catena di certificati completa e ricreare il wallet.

Errori percorso wallet

ORA-28759: Failure to open file

Percorso wallet errato in SET_WALLET.
Prefisso file: mancante.
File wallet caricati non presenti nella directory.

Errori di handshake

ORA-24263 / ORA-29005

Mancata corrispondenza del protocollo TLS.
Certificati non validi o scaduti.
L'endpoint applica TLS > 1.2

Utilizzare un wallet gestito dal cliente per le notifiche e-mail dello scheduler (SMTP)

In questa sezione viene descritto come configurare le notifiche di posta elettronica dello scheduler per l'uso di un server SMTP su TLS (STARTTLS) con un wallet gestito dal cliente.

Prima di iniziare, assicurati di aver già preparato il wallet gestito dal cliente (creato localmente, convalidato e caricato nello storage degli oggetti). Per ulteriori informazioni, vedere Preparare il wallet gestito dal cliente.

Per utilizzare un wallet gestito dal cliente con il server di posta elettronica dello scheduler, effettuare le operazioni riportate di seguito.

Creare una credenziale per l'accesso allo storage degli oggetti:

È possibile utilizzare DBMS_CLOUD.CREATE_CREDENTIAL per creare una credenziale per accedere allo storage degli oggetti cloud.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
I valori forniti per username e password dipendono dal servizio di storage degli oggetti cloud in uso. In questo modo, viene creata la credenziale utilizzata per accedere allo storage degli oggetti cloud in cui risiede il wallet gestito dal cliente.
Creare (o riutilizzare) un oggetto directory per il wallet:

Utilizzare una directory esistente o crearne una nuova per il file wallet. Ad esempio:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Per informazioni sulla creazione di directory, vedere Crea directory in Autonomous AI Database.
Recupera il percorso assoluto della directory:

È necessario il percorso assoluto della directory quando si chiama UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Scaricare il file wallet dallo storage degli oggetti nella directory:

Utilizzare DBMS_CLOUD.GET_OBJECT per copiare il file wallet nella directory. Ad esempio:
```
 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;
 /
```
In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

Configurare l'e-mail dello scheduler (SMTP + STARTTLS):

Eseguire i comandi per impostare lo scheduler per inviare e-mail SMTP per le notifiche del job scheduler:

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

I comandi sono i seguenti:

Imposta l'endpoint SMTP Scheduler (EMAIL_SERVER)
Memorizza i dettagli di login SMTP in EMAIL_CRED e punta lo scheduler ad esso
Abilita la cifratura TLS utilizzando STARTTLS

Per ulteriori informazioni, vedere Procedura SET_SCHEDULER_ATTRIBUTE.

Creare una credenziale per la password del wallet:

Creare una credenziale per memorizzare la password per il wallet gestito dal cliente.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
In questo modo, viene creata la credenziale utilizzata nel passo successivo per fornire la password per il wallet gestito dal cliente.

Indica allo scheduler dove si trova il wallet e come sbloccarlo:

Impostare la directory del wallet dello scheduler e la credenziale del wallet.

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

Verificare la configurazione e-mail dello scheduler:

Eseguire una query sulla vista DBA_SCHEDULER_GLOBAL_ATTRIBUTE per verificare i valori impostati nei passi precedenti.

 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"

Di riferimento

Comandi orapki utili:

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

Struttura di directory del wallet di esempio:

cmw_wallet/
- ewallet.p12
- cwallet.sso