DBMS_CLOUD-REST-APIs

In diesem Abschnitt werden die REST-APIs DBMS_CLOUD behandelt, die mit der autonomen KI-Datenbank auf einer dedizierten Exadata-Infrastruktur bereitgestellt werden.

Voraussetzungen

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

Abhängig von der Bereitstellungsoption müssen die folgenden Voraussetzungen erfüllt sein, um die DBMS_CLOUD-Prozeduren mit Amazon S3-, Azure Blob Storage- und Google Cloud Storage-Serviceprovidern zu verwenden.

DBMS_CLOUD-REST-APIs - Übersicht

In diesem Abschnitt werden die REST-APIs DBMS_CLOUD behandelt, die mit der autonomen KI-Datenbank bereitgestellt werden.

REST-API Beschreibung
GET_RESPONSE_HEADERS (Funktion) Diese Funktion gibt die HTTP-Antwortheader als JSON-Daten in einem JSON-Objekt in der autonomen KI-Datenbank zurück.
Funktion GET_RESPONSE_TEXT Diese Funktion gibt die HTTP-Antwort im TEXT-Format (VARCHAR2 oder CLOB) in der autonomen KI-Datenbank zurück. Normalerweise 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.
SEND_REQUEST Funktion und Prozedur Diese Funktion startet eine HTTP-Anforderung, ruft die Antwort ab und beendet die Antwort in der autonomen KI-Datenbank. Diese Funktion bietet einen Workflow zum Senden einer Cloud-REST-API-Anforderung mit Argumenten sowie einem Antwortcode und einer Payload für die Rückgabe.
Prozedur SET_API_RESULT_CACHE_SIZE Diese Prozedur legt die maximale Cachegröße für die aktuelle Session fest.

Überblick über DBMS_CLOUD-REST-APIs

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

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

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 REST-API-Methode, die für eine HTTP-Anforderung verwendet werden soll, 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 DBMS_CLOUD speichern, wenn Sie den Parameter cache mit DBMS_CLOUD.SEND_REQUEST auf "true" setzen. Die Ansicht SESSION_CLOUD_API_RESULTS beschreibt die Spalten, die Sie verwenden können, wenn REST-API-Ergebnisse gespeichert werden.

Standardmäßig speichern REST-API-Aufrufe vom Typ DBMS_CLOUD keine Ergebnisse für Ihre Session. 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 Ergebnisse gespeichert, und Sie können vergangene Ergebnisse in der Ansicht SESSION_CLOUD_API_RESULTS anzeigen. Das Speichern und Abfragen historischer Ergebnisse von REST-API-Anforderungen für DBMS_CLOUD kann Ihnen helfen, wenn Sie mit Ihren vorherigen Ergebnissen in Ihren Anwendungen arbeiten müssen.

Beispiel: Um aktuelle REST-API-Ergebnisse der DBMS_CLOUD abzufragen, verwenden Sie die Ansicht SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Wenn Sie die REST-API-Ergebnisse DBMS_CLOUD 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 REST-API-Cachegröße DBMS_CLOUD anzeigen und festlegen sowie das Caching deaktivieren.

Parameter für DBMS_CLOUD-REST-API-Ergebnisse cache_scope

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

Standardmäßig ist cache_scope '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 die REST-API-Ergebnisse DBMS_CLOUD.SEND_REQUEST anzeigen kann, die von den Prozeduren generiert werden, die er mit den Rechten des Aufrufers aufruft. Wenn Sie DBMS_CLOUD.SEND_REQUEST in einer Session aufrufen, gibt es drei Möglichkeiten, die basierend auf dem Wert cache_scope bestimmen, ob der aktuelle Benutzer Ergebnisse im Cache anzeigen kann:

Ansicht - DBMS_CLOUD - REST-API SESSION_CLOUD_API_RESULTS

Sie können die REST-API-Ergebnisse DBMS_CLOUD speichern, wenn Sie den Parameter cache mit DBMS_CLOUD.SEND_REQUEST auf "true" setzen. Die Ansicht SESSION_CLOUD_API_RESULTS beschreibt die Spalten, die Sie verwenden können, wenn REST-API-Ergebnisse gespeichert werden.

Die Ansicht SESSION_CLOUD_API_RESULTS ist die Ansicht, die erstellt wird, 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 wird, werden die Daten in der SESSION_CLOUD_API_RESULTS gelöscht.

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

GET_RESPONSE_HEADERS (Funktion)

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 HTTP-Antworttyp von DBMS_CLOUD.SEND_REQUEST zurückgegeben.

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 Format TEXT (VARCHAR2 oder CLOB) zurück. Normalerweise 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 HTTP-Antworttyp von DBMS_CLOUD.SEND_REQUEST zurückgegeben.

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;

SEND_REQUEST Funktion und Prozedur

Diese Funktion und Prozedur startet eine HTTP-Anforderung, ruft die Antwort ab und beendet die Antwort. Diese Funktion bietet einen Workflow zum Senden einer Cloud-REST-API-Anforderung mit Argumenten. 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 Ansicht 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 für die Anforderung.
method

HTTP-Anforderungsmethode: GET, PUT, POST, HEAD, DELETE. Geben Sie die Methode mit der Packagekonstante DBMS_CLOUD an.

Weitere Informationen finden Sie unter REST-API-Konstanten für DBMS_CLOUD.

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

Eine asynchrone Anforderungs-URL.

Um die URL abzurufen, wählen Sie die Anforderungs-API aus der Liste der APIs aus (siehe https://docs.cloud.oracle.com/en-us/iaas/api/). Navigieren Sie dann im linken Fensterbereich, um die API für Ihre Anforderung zu suchen. Beispiel: Database Services-API -> Autonomous AI Database -> StopAutonomousDatabase. Auf dieser Seite wird das API-Home (und der Basisendpunkt) angezeigt. Hängen Sie dann den Basisendpunkt an den relativen Pfad an, der für den WorkRequest-Link Ihrer Arbeitsanforderung abgerufen wurde.

wait_for_states

"Auf Status warten" ist ein Status des Typs: DBMS_CLOUD_TYPES.wait_for_states_t. Folgende Werte sind für erwartete Statuswerte gültig: "ACTIVE", "CANCELED", "COMPLETED", "DELETED", "FAILED", "SUCCEEDED".

Für wait_for_states sind mehrere Status zulässig. Der Standardwert für wait_for_states besteht darin, auf einen der erwarteten Status zu warten: '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. Gibt an, dass ohne Timeout auf den Abschluss der Anforderung gewartet wird.

cache

Wenn TRUE angibt, dass die Anforderung im REST-Ergebnis-API-Cache gecacht werden soll.

Der Standardwert ist FALSE. Das bedeutet, dass REST-API-Anforderungen nicht gecacht werden.

cache_scope Gibt an, ob jeder 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 An DBMS_CLOUD.SEND_REQUEST übergebene Anforderungsmethode ist ungültig.
invalid_req_header ORA-20024 An DBMS_CLOUD.SEND_REQUEST übergebene Anforderungsheader haben kein gültiges JSON-Format.

Verwendungshinweise

Prozedur SET_API_RESULT_CACHE_SIZE

Diese Prozedur legt die maximale Cachegröße für die aktuelle Session fest. 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
cache_size

Legen Sie die maximale Cachegröße auf den angegebenen Wert cache_size fest. Wenn die neue maximale Cachegröße kleiner als die aktuelle Cachegröße ist, werden ältere Datensätze gelöscht, bis die Anzahl der Zeilen der angegebenen maximalen Cachegröße entspricht. Der Höchstwert ist 10000.

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

Die Standardcachegröße ist 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);

Verwandte Inhalte