DBMS_CLOUD-REST-APIs

Voraussetzungen

Als Entwickler können Sie DBMS_CLOUD-Prozeduren mit Autonomous Databases verwenden, die in Oracle Public Cloud, Multicloud oder Exadata Cloud@Customer bereitgestellt sind.

Je nach Deployment-Auswahl müssen die folgenden Voraussetzungen erfüllt sein, um die REST-APIs DBMS_CLOUD mit den Serviceprovidern Amazon S3, Azure Blob Storage und Google Cloud Storage zu verwenden.

Oracle Public Cloud oder Multicloud
Exadata Cloud@Customer

Eine ausgehende Konnektivität muss von Ihrem Flottenadministrator mit einem NAT-Gateway konfiguriert worden sein, wie unten beschrieben:

Erstellen Sie ein NAT-Gateway im virtuellen Cloud-Netzwerk (VCN), in dem sich Ihre Autonomous Database-Ressourcen befinden, indem Sie die Anweisungen unter NAT-Gateway erstellen in der Oracle Cloud Infrastructure-Dokumentation befolgen.
Nachdem Sie das NAT-Gateway erstellt haben, fügen Sie eine Routingregel und eine Egress-Sicherheitsregel zu jedem Subnetz (im VCN) hinzu, in dem sich Autonomous Database-Ressourcen befinden. So können diese Ressourcen mit dem Gateway einen Public Key aus Ihrer Azure AD-Instanz abrufen:
1. Gehen Sie zur Seite Subnetzdetails für das Subnetz.
2. Klicken Sie auf der Registerkarte Informationen zum Subnetz auf den Namen der Routentabelle des Subnetzes, um die Seite Routentabellendetails anzuzeigen.
3. Prüfen Sie in der Tabelle der vorhandenen Routingregeln, ob bereits eine Regel mit den folgenden Eigenschaften vorhanden ist:
  - Zielort: 0.0.0.0/0
  - Zieltyp: NAT-Gateway
  - Ziel: Der Name des NAT-Gateway, das Sie gerade im VCN erstellt haben
  Wenn keine solche Regel vorhanden ist, klicken Sie auf Routenregeln hinzufügen, und fügen Sie eine Routingregel mit diesen Eigenschaften hinzu.
4. Zurück zur Seite Subnetzdetails für das Subnetz.
5. Klicken Sie in der Tabelle Sicherheitslisten des Subnetzes auf den Namen der Sicherheitsliste des Subnetzes, um die Seite Sicherheitslistendetails anzuzeigen.
6. Klicken Sie im Seitenmenü unter Ressourcen auf Egress-Regeln.
7. Prüfen Sie in der Tabelle der vorhandenen Ausgangsregeln, ob bereits eine Regel mit den folgenden Eigenschaften vorhanden ist:
  - Zieltyp: CIDR
  - Zielort: 0.0.0.0/0
  - IP-Protokoll: TCP
  - Quellportbereich: 443
  - Ziel-Portbereich: Alle
  Wenn keine derartige Regel vorhanden ist, klicken Sie auf Egress-Regeln hinzufügen, und fügen Sie eine Egress-Regel mit diesen Eigenschaften hinzu.

Die HTTP-Proxyeinstellungen in Ihrer Umgebung müssen es der Datenbank ermöglichen, auf den Cloud-Serviceprovider zuzugreifen.

Diese Einstellungen werden vom Flottenadministrator beim Erstellen der Exadata Cloud@Customer-Infrastruktur definiert, wie unter Exadata Database Service on Cloud@Customer mit der Konsole bereitstellen beschrieben.

Hinweis:

Die Netzwerkkonfiguration einschließlich des HTTP-Proxys kann nur bearbeitet werden, bis sich die Exadata-Infrastruktur im Status Aktivierung erforderlich befindet. Sobald sie aktiviert ist, können Sie diese Einstellungen nicht mehr bearbeiten.

Für die Einrichtung eines HTTP-Proxys für eine bereits bereitgestellte Exadata-Infrastruktur ist eine Serviceanfrage (SR) in My Oracle Support erforderlich. Weitere Informationen finden Sie unter Serviceanfrage in My Oracle Support erstellen.

DBMS_CLOUD-REST-APIs

In diesem Abschnitt werden die DBMS_CLOUD--REST-APIs beschrieben, die mit Autonomous Database bereitgestellt werden.

REST-API	Beschreibung
Funktion GET_RESPONSE_HEADERS	Diese Funktion gibt die HTTP-Antwortheader als JSON-Daten in einem JSON-Objekt in Autonomous Database zurück.
Funktion GET_RESPONSE_TEXT	Diese Funktion gibt die HTTP-Antwort im TEXT-Format (`VARCHAR2` oder `CLOB`) in Autonomous Database zurück. In der Regel geben die meisten Cloud-REST-APIs eine JSON-Antwort im Textformat zurück. Diese Funktion ist nützlich, wenn Sie erwarten, dass die HTTP-Antwort im Textformat vorliegt.
Funktion GET_API_RESULT_CACHE_SIZE	Diese Funktion gibt die konfigurierte Ergebniscachegröße zurück.
Funktion und Prozedur SEND_REQUEST	Diese Funktion beginnt eine HTTP-Anforderung, ruft die Antwort ab und beendet die Antwort in Autonomous Database. Diese Funktion stellt einen Workflow zum Senden einer Cloud-REST-API-Anforderung mit Argumenten und einem Antwortcode und einer Payload bereit.
Prozedur SET_API_RESULT_CACHE_SIZE	Mit dieser Prozedur wird die maximale Cachegröße für die aktuelle Session festgelegt.

DBMS_CLOUD REST-API - Überblick

Wenn Sie PL/SQL in Ihrer Anwendung verwenden und Cloud-REST-APIs aufrufen müssen, können Sie die REST-API-Anforderungen mit DBMS_CLOUD.SEND_REQUEST senden.

Mit den DBMS_CLOUD-REST-API-Funktionen können Sie HTTP-Anforderungen mit DBMS_CLOUD.SEND_REQUEST erstellen und Ergebnisse abrufen und speichern. Diese Funktionen stellen eine generische API bereit, mit der Sie eine beliebige REST-API mit den folgenden unterstützten Cloud-Services aufrufen können:

Oracle Cloud Infrastructure
Informationen zu Oracle Cloud Infrastructure-REST-APIs finden Sie unter API-Referenz und -Endpunkte.
Azure Cloud ^{Fußnote 1}
Informationen zu Azure-REST-APIs siehe Azure-REST-API-Referenz.

DBMS_CLOUD-REST-API - Konstanten

Beschreibt die DBMS_CLOUD-Konstanten zum Erstellen von HTTP-Anforderungen mit DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD unterstützt die HTTP-Methoden GET, PUT, POST, HEAD und DELETE. Die für eine HTTP-Anforderung zu verwendende REST-API-Methode ist in der Regel in der Cloud-REST-API-Dokumentation dokumentiert.

Name	Typ	Datum
`METHOD_DELETE`	`VARCHAR2(6)`	`'DELETE'`
`METHOD_GET`	`VARCHAR2(3)`	`'GET'`
`METHOD_HEAD`	`VARCHAR2(4)`	`'HEAD'`
`METHOD_POST`	`VARCHAR2(4)`	`'POST'`
`METHOD_PUT`	`VARCHAR2(3)`	`'PUT'`

DBMS_CLOUD-REST-API - Ergebniscache

Sie können die REST-API-Ergebnisse für DBMS_CLOUD speichern, wenn Sie den Parameter cache mit DBMS_CLOUD.SEND_REQUEST auf "true" setzen. In der View SESSION_CLOUD_API_RESULTS werden die Spalten beschrieben, die Sie beim Speichern von REST-API-Ergebnissen verwenden können.

Standardmäßig werden in DBMS_CLOUD-REST-API-Aufrufen keine Ergebnisse für Ihre Session gespeichert. In diesem Fall verwenden Sie die Funktion DBMS_CLOUD.SEND_REQUEST, um Ergebnisse zurückzugeben.

Wenn Sie DBMS_CLOUD.SEND_REQUEST verwenden und den Parameter cache auf TRUE setzen, werden die Ergebnisse gespeichert, und Sie können vergangene Ergebnisse in der Ansicht SESSION_CLOUD_API_RESULTS anzeigen. Das Speichern und Abfragen historischer Ergebnisse von DBMS_CLOUD-REST-API-Anforderungen kann nützlich sein, wenn Sie mit vorangegangenen Ergebnissen in Ihren Anwendungen arbeiten müssen.

Beispiel: Um die letzten REST-API-Ergebnisse von DBMS_CLOUD abzufragen, verwenden Sie die View SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Wenn Sie die DBMS_CLOUD-REST-API-Ergebnisse mit DBMS_CLOUD.SEND_REQUEST speichern, sind die gespeicherten Daten nur innerhalb derselben Session (Verbindung) verfügbar. Nach dem Beenden der Session sind die gespeicherten Daten nicht mehr verfügbar.

Mit DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE und DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE können Sie die DBMS_CLOUD-REST-API-Cachegröße anzeigen und festlegen sowie das Caching deaktivieren.

DBMS_CLOUD REST-API-Ergebnisse cache_scope-Parameter

Wenn Sie DBMS_CLOUD-REST-API-Ergebnisse mit DBMS_CLOUD.SEND_REQUEST speichern, wird der Zugriff auf die Ergebnisse in SESSION_CLOUD_API_RESULTS basierend auf dem Wert von cache_scope gewährt.

Standardmäßig hat cache_scope den Wert 'PRIVATE', und nur der aktuelle Benutzer der Session kann auf die Ergebnisse zugreifen. Wenn Sie cache_scope auf 'PUBLIC' setzen, können alle Sessionbenutzer auf die Ergebnisse zugreifen. Der Standardwert für cache_scope gibt an, dass jeder Benutzer nur DBMS_CLOUD.SEND_REQUEST-REST-API-Ergebnisse anzeigen kann, die von den Prozeduren generiert wurden, die er mit den Rechten des Aufrufers aufrufen. Wenn Sie DBMS_CLOUD.SEND_REQUEST in einer Session aufrufen, gibt es drei Möglichkeiten, anhand des Wertes von cache_scope zu bestimmen, ob der aktuelle Benutzer Ergebnisse im Cache sehen kann:

Sie führen DBMS_CLOUD.SEND_REQUEST direkt als Anweisung der obersten Ebene aus, und der Aufruf von DBMS_CLOUD.SEND_REQUEST und die Ergebnisse der REST-API werden mit demselben Benutzernamen gespeichert. In diesem Fall haben Sie Zugriff auf alle Ergebnisse mit dem Standardwert 'PRIVATE', der für cache_scope festgelegt ist.
Sie schreiben eine Prozedur mit Wrapper-Invoker-Rechten, und als aktueller Benutzer ruft Ihr Aufruf mit DBMS_CLOUD.SEND_REQUEST die Prozedur auf, und die REST-API-Ergebnisse werden mit demselben Benutzernamen gespeichert. In diesem Fall haben Sie Zugriff auf alle Ergebnisse mit dem Standardwert 'PRIVATE', der für cache_scope festgelegt ist.
Sie schreiben eine Prozedur mit Wrapper-Definer-Rechten, und die Prozedur gehört einem anderen Benutzer. Wenn Sie DBMS_CLOUD.SEND_REQUEST innerhalb der Prozedur aufrufen, werden die Ergebnisse mit dem Benutzernamen des Prozedureigentümers gespeichert.

In diesem Fall ruft ein anderer Benutzer mit Definer-Rechten DBMS_CLOUD.SEND_REQUEST auf, und die REST-API-Ergebnisse werden mit dem Eigentümer der Prozedur dieses Erstellers gespeichert. In diesem Fall kann die Session des ausführenden Benutzers die Ergebnisse standardmäßig nicht anzeigen, wenn cache_scope den Wert 'PRIVATE' hat.

Wenn der Prozedureigentümer des Erstellers die Ergebnisse jedem aufrufenden Sessionbenutzer zur Verfügung stellen möchte, muss er cache_scope in DBMS_CLOUD.SEND_REQUEST auf 'PUBLIC' setzen.

DBMS_CLOUD REST-API-View SESSION_CLOUD_API_RESULTS

Sie können die REST-API-Ergebnisse für DBMS_CLOUD speichern, wenn Sie den Parameter cache mit DBMS_CLOUD.SEND_REQUEST auf "true" setzen. In der View SESSION_CLOUD_API_RESULTS werden die Spalten beschrieben, die Sie beim Speichern von REST-API-Ergebnissen verwenden können.

Die View SESSION_CLOUD_API_RESULTS wird erstellt, wenn Sie Ergebnisse mit DBMS_CLOUD.SEND_REQUEST cachen. Sie können historische Ergebnisse abfragen, die zu Ihrer Benutzersession gehören. Wenn die Session beendet ist, werden die Daten in SESSION_CLOUD_API_RESULTS gelöscht.

Spalte	Beschreibung
`URI`	Die Anforderungs-URL der `DBMS_CLOUD`-REST-API
`TIMESTAMP`	Zeitstempel der `DBMS_CLOUD`-REST-API-Antwort
`CLOUD_TYPE`	Der `DBMS_CLOUD`-REST-API-Cloud-Typ, wie Oracle Cloud Infrastructure und AZURE_BLOB
`REQUEST_METHOD`	Die -Anforderungsmethode der `DBMS_CLOUD`-REST-API, wie `GET`, `PUT`, `HEAD`
`REQUEST_HEADERS`	Die `DBMS_CLOUD`-REST-API-Anforderungsheader
`REQUEST_BODY_TEXT`	Der `DBMS_CLOUD`-REST-API-Anforderungsbody in `CLOB`
`RESPONSE_STATUS_CODE`	Der `DBMS_CLOUD`-REST-API-Antwortstatuscode, wie `200(OK)`, `404(Not Found)`
`RESPONSE_HEADERS`	Die REST-API-Antwortheader `DBMS_CLOUD`
`RESPONSE_BODY_TEXT`	Der `DBMS_CLOUD`-REST-API-Antwortbody in `CLOB`
`SCOPE`	Der von `DBMS_CLOUD.SEND_REQUEST` festgelegte `cache_scope`. Gültige Werte sind `PUBLIC` oder `PRIVATE`.

Funktion GET_RESPONSE_HEADERS

Diese Funktion gibt die HTTP-Antwortheader als JSON-Daten in einem JSON-Objekt zurück.

Syntax

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Parameter

Parameter	Beschreibung
`resp`	Von `DBMS_CLOUD.SEND_REQUEST` zurückgegebener HTTP-Antworttyp.

Exceptions

Ausnahme	Fehler	Beschreibung
`invalid_response`	`ORA-20025`	Ungültiges Antworttypobjekt an `DBMS_CLOUD.GET_RESPONSE_HEADERS` übergeben.

Funktion GET_RESPONSE_TEXT

Diese Funktion gibt die HTTP-Antwort im TEXT-Format zurück (VARCHAR2 oder CLOB). In der Regel geben die meisten Cloud-REST-APIs eine JSON-Antwort im Textformat zurück. Diese Funktion ist nützlich, wenn Sie erwarten, dass die HTTP-Antwort im Textformat vorliegt.

Syntax

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Parameter

Parameter	Beschreibung
`resp`	Von `DBMS_CLOUD.SEND_REQUEST` zurückgegebener HTTP-Antworttyp.

Exceptions

Ausnahme	Fehler	Beschreibung
`invalid_response`	`ORA-20025`	Ungültiges Antworttypobjekt an `DBMS_CLOUD.GET_RESPONSE_TEXT` übergeben.

Funktion GET_API_RESULT_CACHE_SIZE

Diese Funktion gibt die konfigurierte Ergebniscachegröße zurück. Der Wert für die Cachegröße gilt nur für die aktuelle Session.

Syntax

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Funktion und Prozedur SEND_REQUEST

Diese Funktion und Prozedur starten eine HTTP-Anforderung, rufen die Antwort ab und beenden die Antwort. Diese Funktion stellt einen Workflow zum Senden einer Cloud-REST-API-Anforderung mit Argumenten bereit, und die Funktion gibt einen Antwortcode und eine Payload zurück. Wenn Sie die Prozedur verwenden, können Sie Ergebnisse und Antwortdetails aus den gespeicherten Ergebnissen mit der View SESSION_CLOUD_API_RESULTS anzeigen.

Syntax

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Parameter

Parameter	Beschreibung
`credential_name`	Der Name der Zugangsdaten für die Authentifizierung mit der entsprechenden Cloud-nativen API.
`uri`	HTTP-URI zum Erstellen der Anforderung.
`method`	HTTP-Anforderungsmethode: `GET`, `PUT`, `POST`, `HEAD`, `DELETE`. Geben Sie die Methode mit der `DBMS_CLOUD`-Konstante an. Weitere Informationen finden Sie unter DBMS_CLOUD-REST-API - Konstanten.
`headers`	HTTP-Anforderungsheader für die entsprechende Cloud-native API im JSON-Format. Die Authentifizierungsheader werden automatisch festgelegt. Übergeben Sie nur benutzerdefinierte Header.
`async_request_url`	URL für eine asynchrone Anforderung. Sie können die URL aus der API-Liste abrufen (siehe https://docs.cloud.oracle.com/en-us/iaas/api/). Navigieren Sie dann im linken Fensterbereich zur API für Ihre Anforderung. Beispiel: Database Services-API → Autonomous Database → StopAutonomousDatabase. Auf dieser Seite wird das API-Home (und der Basisendpunkt) angezeigt. Hängen Sie dann den Basisendpunkt mit dem relativen Pfad an, der für den WorkRequest-Link der Arbeitsanforderung abgerufen wurde.
`wait_for_states`	"Auf Status warten" ist ein Status vom Typ `DBMS_CLOUD_TYPES.wait_for_states_t`. Gültige Werte für den erwarteten Status: "`ACTIVE`", "`CANCELED`", "`COMPLETED`", "`DELETED`", "`FAILED`", "`SUCCEEDED`". Mehrere Status sind für `wait_for_states` zulässig. Der Standardwert für `wait_for_states` ist das Warten auf einen der erwarteten Status: "`ACTIVE`", "`CANCELED`", "`COMPLETED`", "`DELETED`", "`FAILED`", "`SUCCEEDED`".
`timeout`	Gibt den Timeout (in Sekunden) für asynchrone Anforderungen mit den Parametern `async_request_url` und `wait_for_states` an. Der Standardwert ist `0`. Damit wird angegeben, dass ohne Timeout auf den Abschluss der Anforderung gewartet wird.
`cache`	Wenn `TRUE`, muss die Anforderung im REST-Ergebnis-API-Cache gecacht werden. Der Standardwert ist `FALSE`. Das bedeutet, dass REST-API-Anforderungen nicht gecacht werden.
`cache_scope`	Gibt an, ob jeder Benutzer Zugriff auf diesen Anforderungsergebniscache haben kann. Gültige Werte: `"PRIVATE"` und `"PUBLIC"`. Der Standardwert ist `"PRIVATE"`.
`body`	HTTP-Anforderungsbody für `PUT`- und `POST`-Anforderungen.

Exceptions

Ausnahme	Fehler	Beschreibung
`invalid_req_method`	`ORA-20023`	Die an `DBMS_CLOUD.SEND_REQUEST` übergebene Anforderungsmethode ist ungültig.
`invalid_req_header`	`ORA-20024`	An `DBMS_CLOUD.SEND_REQUEST` übergebene Anforderungsheader weisen kein gültiges JSON-Format auf.

Verwendungshinweise

Wenn Sie Oracle Cloud Infrastructure verwenden, müssen Sie einen signaturschlüsselbasierten Zugangsdatenwert für credential_name verwenden. Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.
Mit den optionalen Parametern async_request_url, wait_for_states und timeout können Sie Anforderungen mit langer Ausführungszeit bearbeiten. Mit dieser asynchronen Form von send_request wartet die Funktion auf den in wait_for_states angegebenen Abschlussstatus, bevor sie zurückgegeben wird. Wenn Sie diese Parameter in der Sendeanforderung übergeben, übergeben Sie die erwarteten Rückgabestatus im Parameter wait_for_states. Mit dem Parameter async_request_url können Sie eine verknüpfte Arbeitsanforderung angeben. Die Anforderung gibt nicht sofort einen Wert zurück. Stattdessen prüft die Anforderung die async_request_url, bis der Rückgabestatus einer der erwarteten Status ist oder der timeout überschritten wird (timeout ist optional). Wenn kein timeout angegeben ist, wartet die Anforderung, bis ein in wait_for_states gefundener Status auftritt.

Prozedur SET_API_RESULT_CACHE_SIZE

Mit dieser Prozedur wird die maximale Cachegröße für die aktuelle Session festgelegt. Der Wert für die Cachegröße gilt nur für die aktuelle Session.

Syntax

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parameter

Parameter Beschreibung

Parameter	Beschreibung
`cache_size`	Setzt die maximale Cachegröße auf den angegebenen Wert `cache_size`. Wenn die neue maximale Cachegröße kleiner als die aktuelle Cachegröße ist, werden ältere Datensätze gelöscht, bis die Zeilenanzahl der angegebenen maximalen Cachegröße entspricht. Der Höchstwert beträgt `10000`. Wenn die Cachegröße auf `0` gesetzt ist, ist das Caching in der Session deaktiviert. Die Standardcachegröße beträgt `10`.

cache_size

Setzt die maximale Cachegröße auf den angegebenen Wert cache_size. Wenn die neue maximale Cachegröße kleiner als die aktuelle Cachegröße ist, werden ältere Datensätze gelöscht, bis die Zeilenanzahl der angegebenen maximalen Cachegröße entspricht. Der Höchstwert beträgt 10000.

Wenn die Cachegröße auf 0 gesetzt ist, ist das Caching in der Session deaktiviert.

Die Standardcachegröße beträgt 10.

Exceptions

Ausnahme	Fehler	Beschreibung
`invalid API result cache size`	`ORA-20032`	Der Mindestwert ist 0 und der Höchstwert ist 10000. Diese Ausnahme wird angezeigt, wenn der Eingabewert kleiner als 0 oder größer als 10000 ist.

Beispiel

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);