Externe Anrufe mit einem vom Kunden verwalteten Wallet tätigen

Sie können das Package UTL_HTTP verwenden, wenn Ihre autonome KI-Datenbank über HTTP/HTTPS auf Daten im Internet zugreifen muss. Mit dem Package UTL_HTTP können Sie HTTP-Callouts direkt aus SQL und PL/SQL erstellen.

Wenn Sie einen HTTPS-Endpunkt aufrufen, müssen Sie ein Oracle Wallet konfigurieren. Autonome AI-Datenbank erfordert ein Wallet, das die vertrauenswürdigen Root- und Zwischenzertifikate für jeden HTTPS-Endpunkt enthält, mit dem sich Ihre Datenbank verbindet. Das UTL_HTTP-Package verwendet dieses Wallet, um eine sichere SSL-/TLS-Verbindung herzustellen. Sie können das Wallet mit dem Utility orapki erstellen und verwalten.

Hinweis: Nur HTTP-(Nicht-HTTPS-)Anforderungen erfordern kein Oracle Wallet.

In den folgenden Abschnitten wird erläutert, wie Sie ein vom Kunden verwaltetes Wallet konfigurieren und verwenden, um ausgehende HTTPS-Aufrufe mit dem Package UTL_HTTP in der autonomen KI-Datenbank vorzunehmen.

Voraussetzungen für die Verwendung eines vom Kunden verwalteten Wallets mit externen Aufrufen

Stellen Sie zunächst sicher, dass Folgendes vorhanden ist:

Zugriff auf die autonome KI-Datenbank mit einem Account, der PL/SQL ausführen und UTL_HTTP konfigurieren kann.
Zugriff auf den HTTPS-Zielendpunkt und seine vollständige Zertifikatskette (Root + Zwischenzertifikate).
Eine Workstation, auf der Sie orapki ausführen können, um ein Oracle Wallet zu erstellen und zu validieren. Sie müssen Oracle Database installieren, um das Utility orapki abzurufen. Weitere Informationen finden Sie unter Oracle Database installieren.

Vom Kunden verwaltetes Wallet vorbereiten

In diesem Schritt erstellen und validieren Sie das Wallet auf Ihrer Workstation, bevor Sie es in die autonome KI-Datenbank hochladen.

Vom Kunden verwaltetes Wallet abrufen oder erstellen

Beispiel mit 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: ********

Wallet validieren

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

Alle importierten Zertifikate werden aufgelistet.

Wallet hochladen

Sobald das vom Kunden verwaltete Wallet bereit ist (einschließlich aller erforderlichen selbstsignierten/Root-/Zwischenzertifikate), laden Sie die Wallet-Dateien an einen Speicherort in Oracle Cloud Infrastructure (OCI) Object Storage hoch.

Vom Kunden verwaltetes Wallet mit UTL_HTTP verwenden

In diesem Abschnitt wird gezeigt, wie Sie Ihr Wallet aus Object Storage herunterladen, den Netzwerkzugriff auf den HTTPS-Endpunkt zulassen und dann HTTPS-Aufrufe mit dem Package UTL_HTTP ausführen.

Erstellen Sie Zugangsdaten für Object Storage-Zugriff:
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
Die Werte, die Sie für username und password angeben, hängen vom verwendeten Cloud-Objektspeicherservice ab. Dadurch werden die Zugangsdaten erstellt, mit denen Sie auf den Cloud Object Storage zugreifen, in dem sich das vom Kunden verwaltete Wallet befindet.
Directory-Objekt für das Wallet erstellen (oder wiederverwenden):

Verwenden Sie ein vorhandenes Verzeichnis, oder erstellen Sie ein neues Verzeichnis für die Wallet-Datei. Beispiel:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Informationen zum Erstellen von Verzeichnissen finden Sie unter Verzeichnis in autonomer KI-Datenbank erstellen.
Absoluten Verzeichnispfad abrufen:

Sie benötigen den absoluten Verzeichnispfad, wenn Sie UTL_HTTP.SET_WALLET aufrufen.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Laden Sie die Wallet-Datei aus Object Storage in das Verzeichnis herunter:

Kopieren Sie die Wallet-Datei mit DBMS_CLOUD.GET_OBJECT in Ihr Verzeichnis. Beispiel:
```
 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 diesem Beispiel ist namespace-string der Oracle Cloud Infrastructure-Objektspeicher-Namespace und bucketname der Bucket-Name. Weitere Informationen finden Sie unter Object Storage-Namespaces.

Ausgehenden Netzwerkzugriff (ACL) auf den HTTPS-Endpunkt zulassen:

Sie müssen zulassen, dass der Datenbankbenutzer/das Datenbankschema den Zielhost über das Netzwerk erreicht.

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

Bei Exadata Cloud@Customer-Deployments müssen Sie auch den Proxy wie unten dargestellt einrichten:

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

HTTPS-Aufrufe mit UTL_HTTP:

Einfache GET-Anforderung:

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

POST-Anforderung mit JSON-Payload:

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

Fehlerbehebung bei häufigen Fehlern:

Zertifikatskettenfehler

Fehler: ORA-29024: Certificate validation failure

Root- und Zwischenzertifikate fehlen möglicherweise.
Der Zielendpunkt verwendet möglicherweise eine neue CA - laden Sie die vollständige Zertifikatskette erneut herunter, und erstellen Sie das Wallet neu.

Wallet-Pfadfehler

ORA-28759: Failure to open file

Falscher Wallet-Pfad in SET_WALLET.
Fehlendes Präfix file:.
Hochgeladene Wallet-Dateien sind nicht im Verzeichnis vorhanden.

Handshake-Fehler

ORA-24263 / ORA-29005

TLS-Protokoll stimmt nicht überein.
Ungültige oder abgelaufene Zertifikate.
Endpunkt erzwingt TLS > 1.2

Vom Kunden verwaltetes Wallet für Scheduler Email Notifications (SMTP) verwenden

In diesem Abschnitt wird gezeigt, wie Sie Scheduler-E-Mail-Benachrichtigungen so konfigurieren, dass ein SMTP-Server über TLS (STARTTLS) mit einem vom Kunden verwalteten Wallet verwendet wird.

Stellen Sie vor dem Start sicher, dass Sie das vom Kunden verwaltete Wallet bereits vorbereitet haben (lokal erstellt, validiert und in Object Storage hochgeladen). Weitere Informationen finden Sie unter Vorbereiten des vom Kunden verwalteten Wallets.

So verwenden Sie ein vom Kunden verwaltetes Wallet mit dem Scheduler-E-Mail-Server:

Zugangsdaten für Object Storage-Zugriff erstellen:

Sie können DBMS_CLOUD.CREATE_CREDENTIAL verwenden, um Zugangsdaten für den Zugriff auf Cloud Object Storage zu erstellen.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
Die Werte, die Sie für username und password angeben, hängen vom verwendeten Cloud-Objektspeicherservice ab. Dadurch werden die Zugangsdaten erstellt, mit denen Sie auf den Cloud Object Storage zugreifen, in dem sich das vom Kunden verwaltete Wallet befindet.
Directory-Objekt für das Wallet erstellen (oder wiederverwenden):

Verwenden Sie ein vorhandenes Verzeichnis, oder erstellen Sie ein neues Verzeichnis für die Wallet-Datei. Beispiel:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Informationen zum Erstellen von Verzeichnissen finden Sie unter Verzeichnis in autonomer KI-Datenbank erstellen.
Absoluten Verzeichnispfad abrufen:

Sie benötigen den absoluten Verzeichnispfad, wenn Sie UTL_HTTP.SET_WALLET aufrufen.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Laden Sie die Wallet-Datei aus Object Storage in das Verzeichnis herunter:

Kopieren Sie die Wallet-Datei mit DBMS_CLOUD.GET_OBJECT in Ihr Verzeichnis. Beispiel:
```
 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 diesem Beispiel ist namespace-string der Oracle Cloud Infrastructure-Objektspeicher-Namespace und bucketname der Bucket-Name. Weitere Informationen finden Sie unter Object Storage-Namespaces.

Scheduler-E-Mail konfigurieren (SMTP + STARTTLS):

Führen Sie die Befehle aus, um den Scheduler so einzurichten, dass SMTP-E-Mails für Scheduler-Jobbenachrichtigungen gesendet werden:

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

Die Befehle führen folgende Aktionen aus:

Legt den Scheduler SMTP-Endpunkt fest (EMAIL_SERVER)
Speichert SMTP-Anmeldedetails in EMAIL_CRED und weist Scheduler darauf hin
Aktiviert die TLS-Verschlüsselung mit STARTTLS

Weitere Informationen finden Sie unter Prozedur SET_SCHEDULER_ATTRIBUTE.

Erstellen Sie Zugangsdaten für das Wallet-Kennwort:

Erstellen Sie Zugangsdaten, um das Kennwort für das vom Kunden verwaltete Wallet zu speichern.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
Dadurch werden die Zugangsdaten erstellt, die Sie im nächsten Schritt zur Angabe des Kennworts für das vom Kunden verwaltete Wallet verwenden.

Teilen Sie Scheduler mit, wo sich das Wallet befindet und wie es entsperrt wird:

Legen Sie das Wallet-Verzeichnis des Schedulers und die Wallet-Zugangsdaten fest.

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

Prüfen Sie die Scheduler-E-Mail-Konfiguration:

Fragen Sie die Ansicht DBA_SCHEDULER_GLOBAL_ATTRIBUTE ab, um die Werte zu prüfen, die Sie in den vorherigen Schritten festgelegt haben.

 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"

Referenz

Nützliche orapki-Befehle:

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

Beispiel-Wallet-Verzeichnisstruktur:

cmw_wallet/
- ewallet.p12
- cwallet.sso