Webservices aus autonomer KI-Datenbank aufrufen

Enthält Details zur Verwendung von UTL_HTTP zum Weiterleiten einer HTTP-Anforderung auf einem öffentlichen Host.

Beispiel: Um eine HTTP-Anforderung für einen öffentlichen Host www.example.com weiterzuleiten, erstellen Sie eine Access Control-Liste für den Host:

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'www.example.com',
         ace =>  xs$ace_type( privilege_list => xs$name_list('http'),
                              principal_name => 'ADMIN',
                              principal_type => xs_acl.ptype_db));
END;

Dann leiten Sie die HTTP-Anforderung weiter:

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Informationen zu Einschränkungen für UTL_HTTP für autonome KI-Datenbank finden Sie unter PL/SQL-Packagehinweise für autonome KI-Datenbank.

Beschreibt die Schritte zum Übermitteln einer HTTP-Anforderung mit UTL_HTTP auf einem privaten Host.

Um eine Anforderung an einen Zielhost auf einem privaten Endpunkt weiterzuleiten, muss der Zielhost über das Oracle Cloud Infrastructure-VCN der Quelldatenbank zugänglich sein. Beispiel: Sie können eine Verbindung zum Zielhost herstellen, wenn:

• Sowohl die Quelldatenbank als auch der Zielhost befinden sich in demselben Oracle Cloud Infrastructure-VCN.

• Die Quelldatenbank und der Zielhost befinden sich in verschiedenen Oracle Cloud Infrastructure-VCNs, die gepaart sind.

• Der Zielhost ist ein On-Premise-Netzwerk, das über FastConnect oder VPN mit dem Oracle Cloud Infrastructure-VCN der Quelldatenbank verbunden ist.

Sie können auch UTL_HTTP-Aufrufe mit einem vom Kunden verwalteten Wallet tätigen, wenn sich Ihre autonome KI-Datenbank auf einem privaten Endpunkt befindet. Weitere Informationen finden Sie unter Externe Anrufe mit einem vom Kunden verwalteten Wallet tätigen.

So erstellen Sie eine UTL_HTTP-Anforderung an ein Ziel auf einem privaten Endpunkt:

1. Erstellen Sie eine Access Control-Liste für den Host.

   Beispiel:

   BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
            host => 'www.example.com',
            ace => xs$ace_type( privilege_list => xs$name_list('http'),
                                principal_name => 'ADMIN',
                                principal_type => xs_acl.ptype_db),
                                private_target => TRUE);
   END;
   /

   Wie in diesem Beispiel dargestellt, geben Sie beim Erstellen einer Access Control-Liste für den Host den Parameter private_target mit dem Wert TRUE an.

   Hinweis
   
   Wenn Sie die Datenbankeigenschaft ROUTE_OUTBOUND_CONNECTIONS festlegen, ist das Festlegen des Parameters private_target auf TRUE in dieser API nicht erforderlich. Weitere Informationen finden Sie unter Erweiterte Sicherheit für ausgehende Verbindungen mit privaten Endpunkten.

2. HTTP-Anforderung weiterleiten:

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Informationen zu Einschränkungen für UTL_HTTP für autonome KI-Datenbank finden Sie unter PL/SQL-Packagehinweise für autonome KI-Datenbank.

Wenn sich Ihre autonome AI-Datenbankinstanz auf einem privaten Endpunkt befindet, können Sie einen Proxy verwenden, um HTTP-Anforderungen mit UTL_HTTP weiterzuleiten.

1. Legen Sie die ACL HTTP_PROXY auf dem Proxyserver fest.

   Beispiel:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   Wie in diesem Beispiel gezeigt, geben Sie beim Erstellen einer Access Control-Liste für den Proxyserver den Parameter private_target mit dem Wert TRUE an.

   Hinweis
   
   Wenn Sie die Datenbankeigenschaft ROUTE_OUTBOUND_CONNECTIONS festlegen, ist das Festlegen des Parameters private_target auf TRUE in dieser API nicht erforderlich. Weitere Informationen finden Sie unter Erweiterte Sicherheit für ausgehende Verbindungen mit privaten Endpunkten.
2. Stellen Sie die HTTP-ACL auf dem Remote-Webserver ein.

   Beispiel:

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

3. Legen Sie das Wallet und den Proxy für UTL_HTTP fest.

   Beispiel:

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. HTTP-Anforderung weiterleiten:

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

Beschreibt, wie Zugangsdatenobjekte an die Prozedur UTL_HTTP.SET_CREDENTIAL übergeben werden.

Die Prozedur UTL_HTTP.SET_CREDENTIAL legt HTTP-Authentifizierungsinformationen im HTTP-Anforderungsheader fest. Der Webserver benötigt diese Informationen, um die Anforderung zu autorisieren.

Mit der Prozedur UTL_HTTP.SET_CREDENTIAL können Sie Zugangsdatenobjekte übergeben, um die HTTP-Authentifizierung festzulegen. Zugangsdatenobjekte sind Schemaobjekte. Daher können nur berechtigte Benutzer auf sie zugreifen und Sie können Berechtigungen auf Schemaebene konfigurieren, um Zugriff auf die Zugangsdaten zu kontrollieren. Das Übergeben von Zugangsdatenobjekten ist eine geeignete und sichere Möglichkeit, Benutzername/Kennwort/Schlüssel für die Authentifizierung zu speichern und zu verwalten.

Die Prozedur UTL_HTTP.SET_CREDENTIAL ist eine sichere und bequeme Alternative zur Prozedur UTL_HTTP.SET_AUTHENTICATION.

Beispiel

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

Wie im obigen Beispiel gezeigt, müssen Sie beim Aufrufen der Prozedur SET_AUTHENTICATION den Benutzernamen/das Kennwort als Teil der formalen PL/SQL-Parameter in Klartext übergeben. Möglicherweise müssen Sie den Benutzernamen/das Kennwort in verschiedene PL/SQL-Automatisierungs- oder Cron-Skripte einbetten. Das Übergeben von Klartextpasswörtern ist ein Complianceproblem, das in der Prozedur UTL_HTTP.SET_CREDENTIAL behoben wird.

Weitere Informationen finden Sie unter Prozedur SET_AUTHENTICATION und Prozedur SET_AUTHENTICATION_FROM_WALLET.

UTL_HTTP.SET_CREDENTIAL-Syntax

UTL_HTTP.SET_CREDENTIAL (
    r          IN OUT NOCOPY req,
    credential IN VARCHAR2,
    scheme     IN VARCHAR2 DEFAULT 'Basic',
    for_proxy  IN BOOLEAN  DEFAULT FALSE);

Beispiel für die Übergabe eines Zugangsdatenobjekts in der Prozedur SET_CREDENTIAL:

• Zugangsdatenobjekt erstellen:

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  Dadurch wird ein Zugangsdatenobjekt erstellt, das ein gespeichertes Benutzername/Kennwort-Paar erstellt.

  Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  Weitere Informationen finden Sie unter Zugangsdaten für Scheduler-Jobs angeben.

• Rufen Sie die Prozedur UTL_HTTP.SET_CREDENTIAL auf:

  DECLARE
        l_http_request  UTL_HTTP.REQ;
      BEGIN 
        l_http_request := UTL_HTTP.BEGIN_REQUEST('https://www.example.com/v1/dwcsdev/NAME/dwcs_small_xt1.csv');
        UTL_HTTP.SET_CREDENTIAL (l_http_request, 'HTTP_CRED','BASIC');
        ...
  END;
  

  In diesem Beispiel wird zuerst eine Anforderung erstellt, indem die Prozedur BEGIN_REQUEST aufgerufen wird. Außerdem werden HTTP-Authentifizierungsinformationen im HTTP-Anforderungsheader festgelegt, indem die Prozedur SET_CREDENTIAL aufgerufen wird. Der Webserver benötigt diese Informationen, um die Anforderung zu autorisieren. Der Wert l_http_request ist die HTTP-Anforderung, HTTP_CRED der Zugangsdatenname und BASIC das HTTP-Authentifizierungsschema.

Weitere Informationen finden Sie unter UTL_HTTP.

Informationen zu Einschränkungen für UTL_HTTP für autonome KI-Datenbank finden Sie unter PL/SQL-Packagehinweise für autonome KI-Datenbank.

Wenn Sie mehrere sequenzielle SQL-Befehle mit Oracle APEX SQL Commands oder dem SQL-Arbeitsblatt von Database Actions ausführen, können die Befehle in verschiedenen Datenbanksessions ausgeführt werden, in denen der Status einer vorherigen Anweisung nicht gespeichert wird. Dieses Verhalten unterscheidet sich von Desktop-SQL-Clients wie SQL*Plus und SQL Developer, die eine dauerhafte Verbindung zur Datenbank aufrechterhalten.

Oracle APEX SQL Commands und Database Actions SQL-Arbeitsblattweiterleitungen an eine autonome KI-Datenbankinstanz sind zustandslos. Das bedeutet, dass die Ausführung einzelner SQL- und PL/SQL-Anweisungen den Status im Datenbankspeicher speichern kann. Beispiel: Wenn Sie einen Befehl zur Verwendung eines Wallets weiterleiten, wird der Status jedoch möglicherweise gelöscht, bevor Sie die nächste Anweisung ausführen.

In der folgenden Tabelle finden Sie die Schritte zum Beibehalten des Datenbankspeicherstatus zwischen Anweisungsausführungen für SQL-Befehle, die Sie an die autonome KI-Datenbank weiterleiten.

Beispiel: Verwenden Sie den folgenden Codeblock, um einen utl_http.request()-Befehl auszuführen, der ein vom Kunden verwaltetes Wallet verwendet:

SELECT utl_http.request(url => 'https://api.example.com/', wallet_path => 'file:path_to_wallet', wallet_password => 'password' ) FROM DUAL";

Vergleichen Sie dies mit zwei aufeinander folgenden Anweisungen, die möglicherweise nicht erfolgreich ausgeführt werden, wenn der Befehl utl_http.set_wallet() und die Anweisung utl_http.request() einzeln und nicht als einzelner Codeblock ausgeführt werden:

EXEC utl_http.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
SELECT utl_http.request('https://api.example.com/') FROM DUAL;

Sie können die autonome KI-Datenbank so konfigurieren, dass Informationen zur Datenbankidentität bei ausgehenden HTTP-Anforderungen als benutzerdefinierte HTTP-Header gesendet werden.

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"DATABASE_OCID"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"TENANT_OCID",
"DATABASE_OCID",
"COMPARTMENT_OCID",
"CLOUD_DOMAIN",
"CLIENT_IP_ADDRESS"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = '*';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'objectstorage.oraclecloud.com';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'oraclecloud.com, example.com';

X-ADB-Source-Database=
  {"databaseName":"MYDATABASENAME",
   "region":"region_identifier",
   "tenantOcid":"tenant_ocid",
   "databaseOcid":"database_ocid",
   "compartmentOcid":"compartment_ocid",
   "clientIpAddress":"client_ip_address"}