API REST DBMS_CLOUD

Questa sezione descrive le API REST DBMS_CLOUD fornite con Autonomous AI Database on Dedicated Exadata Infrastructure.

Prerequisiti

Come sviluppatore, puoi utilizzare le procedure DBMS_CLOUD con i database AI autonomi distribuiti su Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

A seconda della scelta di distribuzione, è necessario soddisfare i seguenti prerequisiti per utilizzare le procedure DBMS_CLOUD con i provider di servizi Amazon S3, Azure Blob Storage e Google Cloud Storage.

Una connettività in uscita deve essere stata configurata utilizzando un gateway NAT dall'amministratore della flotta, come descritto di seguito.

  • Creare un gateway NAT nella rete cloud virtuale (VCN) in cui risiedono le risorse di Autonomous AI Database seguendo le istruzioni riportate in Crea un gateway NAT nella documentazione di Oracle Cloud Infrastructure.

  • Dopo aver creato il gateway NAT, aggiungere una regola di instradamento e una regola di sicurezza in uscita a ogni subnet (nella VCN) in cui risiedono le risorse di Autonomous AI Database in modo che queste risorse possano utilizzare il gateway per ottenere una chiave pubblica dall'istanza di Azure AD:

    1. Andare alla pagina Dettagli subnet per la subnet.

    2. Nella scheda Informazioni subnet fare clic sul nome della tabella di instradamento della subnet per visualizzare la relativa pagina Dettagli tabella di instradamento.

    3. Nella tabella delle regole di instradamento esistenti, verificare se esiste già una regola con le seguenti caratteristiche:

      • Destinazione: 0.0.0.0/0

      • Tipo di destinazione: gateway NAT

      • Destinazione: il nome del gateway NAT appena creato nella VCN

      Se tale regola non esiste, fare clic su Aggiungi regole di instradamento e aggiungere una regola di instradamento con queste caratteristiche.

    4. Tornare alla pagina Dettagli subnet per la subnet.

    5. Nella tabella Elenchi sicurezza della subnet fare clic sul nome della lista di sicurezza della subnet per visualizzare la relativa pagina Dettagli elenco di sicurezza.

    6. Nel menu laterale, in Risorse, fare clic su Regole di uscita.

    7. Nella tabella delle regole di uscita esistenti, verificare se esiste già una regola con le seguenti caratteristiche:

      • Tipo di destinazione:CIDR

      • Destinazione:0.0.0.0/0

      • Protocollo IP:TCP

      • Intervallo porte di origine:443

      • Intervallo porte di destinazione:Tutti

      Se una regola di questo tipo non esiste, fare clic su Aggiungi regole di uscita e aggiungere una regola di uscita con queste caratteristiche.

Le impostazioni del proxy HTTP nell'ambiente devono consentire al database di accedere al provider di servizi cloud.

Queste impostazioni vengono definite dall'amministratore della flotta durante la creazione dell'infrastruttura Exadata Cloud@Customer, come descritto in Uso della console per eseguire il provisioning di Exadata Database Service su Cloud@Customer.

Nota: la configurazione di rete, incluso il proxy HTTP, può essere modificata solo fino a quando l'infrastruttura Exadata non è in stato Richiede attivazione. Una volta attivato, non è possibile modificare tali impostazioni.

L'impostazione di un proxy HTTP per un'infrastruttura Exadata già di cui è stato eseguito il provisioning richiede una richiesta di servizio (SR) in My Oracle Support. Per informazioni dettagliate, vedere Crea una richiesta di servizio in My Oracle Support.

Sintetico API REST DBMS_CLOUD

Questa sezione descrive le API REST DBMS_CLOUD fornite con Autonomous AI Database.

API REST Descrizione
Funzione GET_RESPONSE_HEADERS Questa funzione restituisce le intestazioni di risposta HTTP come dati JSON in un oggetto JSON in Autonomous AI Database.
Funzione GET_RESPONSE_TEXT Questa funzione restituisce la risposta HTTP in formato TEXT (VARCHAR2 o CLOB) in Autonomous AI Database. In genere, la maggior parte delle API REST cloud restituisce una risposta JSON in formato testo. Questa funzione è utile se si prevede che la risposta HTTP sia in formato testo.
Funzione GET_API_RESULT_CACHE_SIZE Questa funzione restituisce la dimensione della cache dei risultati configurata.
Funzione e procedura SEND_REQUEST Questa funzione avvia una richiesta HTTP, ottiene la risposta e termina la risposta in Autonomous AI Database. Questa funzione fornisce un workflow per l'invio di una richiesta API REST cloud con argomenti e un codice di risposta di restituzione e payload.
Procedura SET_API_RESULT_CACHE_SIZE Questa procedura imposta la dimensione massima della cache per la sessione corrente.

Panoramica sull'API REST DBMS_CLOUD

Quando utilizzi PL/SQL nell'applicazione e devi chiamare le API REST cloud, puoi utilizzare DBMS_CLOUD.SEND_REQUEST per inviare le richieste API REST.

Le funzioni API REST DBMS_CLOUD consentono di effettuare richieste HTTP utilizzando DBMS_CLOUD.SEND_REQUEST e ottenere e salvare i risultati. Queste funzioni forniscono un'API generica che consente di chiamare qualsiasi API REST con i seguenti servizi cloud supportati:

Costanti API REST DBMS_CLOUD

Descrive le costanti DBMS_CLOUD per la creazione di richieste HTTP utilizzando DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD supporta i metodi HTTP GET, PUT, POST, HEAD e DELETE. Il metodo API REST da utilizzare per una richiesta HTTP è in genere documentato nella documentazione relativa all'API REST cloud.

Nome Type Valore
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'

Cache risultati API REST DBMS_CLOUD

È possibile salvare i risultati dell'API REST DBMS_CLOUD quando si imposta il parametro cache su true con DBMS_CLOUD.SEND_REQUEST. La vista SESSION_CLOUD_API_RESULTS descrive le colonne che è possibile utilizzare quando vengono salvati i risultati dell'API REST.

Per impostazione predefinita, le chiamate API REST DBMS_CLOUD non salvano i risultati per la sessione. In questo caso si utilizza la funzione DBMS_CLOUD.SEND_REQUEST per restituire i risultati.

Quando si utilizza DBMS_CLOUD.SEND_REQUEST e si imposta il parametro cache su TRUE, i risultati vengono salvati ed è possibile visualizzare i risultati passati nella vista SESSION_CLOUD_API_RESULTS. Il salvataggio e l'esecuzione di query sui risultati cronologici delle richieste API REST DBMS_CLOUD possono essere utili quando è necessario utilizzare i risultati precedenti nelle applicazioni.

Ad esempio, per eseguire una query sui risultati recenti dell'API REST DBMS_CLOUD, utilizzare la vista SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Quando si salvano i risultati dell'API REST DBMS_CLOUD con DBMS_CLOUD.SEND_REQUEST, i dati salvati sono disponibili solo all'interno della stessa sessione (connessione). Al termine della sessione, i dati salvati non saranno più disponibili.

Utilizzare DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE e DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE per visualizzare e impostare la dimensione della cache dell'API REST DBMS_CLOUD e per disabilitare l'inserimento nella cache.

Parametro cache_scope risultati API REST DBMS_CLOUD

Quando si salvano i risultati dell'API REST DBMS_CLOUD con DBMS_CLOUD.SEND_REQUEST, l'accesso ai risultati in SESSION_CLOUD_API_RESULTS viene fornito in base al valore di cache_scope.

Per impostazione predefinita, cache_scope è 'PRIVATE' e solo l'utente corrente della sessione può accedere ai risultati. Se si imposta cache_scope su 'PUBLIC', tutti gli utenti della sessione potranno accedere ai risultati. Il valore predefinito per cache_scope specifica che ogni utente può visualizzare solo i risultati dell'API REST DBMS_CLOUD.SEND_REQUEST generati dalle procedure richiamate con i diritti del chiamante. Quando si richiama DBMS_CLOUD.SEND_REQUEST in una sessione, ci sono tre possibilità che determinano se l'utente corrente può visualizzare i risultati nella cache, in base al valore cache_scope:

Vista API REST DBMS_CLOUD SESSION_CLOUD_API_RESULTS

È possibile salvare i risultati dell'API REST DBMS_CLOUD quando si imposta il parametro cache su true con DBMS_CLOUD.SEND_REQUEST. La vista SESSION_CLOUD_API_RESULTS descrive le colonne che è possibile utilizzare quando vengono salvati i risultati dell'API REST.

La vista SESSION_CLOUD_API_RESULTS è la vista creata se si inseriscono nella cache i risultati con DBMS_CLOUD.SEND_REQUEST. È possibile eseguire query sui risultati cronologici che appartengono alla sessione utente. Al termine della sessione, i dati nel file SESSION_CLOUD_API_RESULTS vengono rimossi.

A colonne Descrizione
URI URL richiesta API REST DBMS_CLOUD
TIMESTAMP Indicatore orario risposta API REST DBMS_CLOUD
CLOUD_TYPE Tipo di cloud API REST DBMS_CLOUD, ad esempio Oracle Cloud Infrastructure e AZURE_BLOB
REQUEST_METHOD Il metodo di richiesta dell'API REST DBMS_CLOUD, ad esempio GET, PUT, HEAD
REQUEST_HEADERS Intestazioni richiesta API REST DBMS_CLOUD
REQUEST_BODY_TEXT Il corpo della richiesta API REST DBMS_CLOUD in CLOB
RESPONSE_STATUS_CODE Codice dello stato della risposta dell'API REST DBMS_CLOUD, ad esempio 200(OK), 404(Not Found)
RESPONSE_HEADERS Intestazioni risposta API REST DBMS_CLOUD
RESPONSE_BODY_TEXT Corpo della risposta dell'API REST DBMS_CLOUD in CLOB
SCOPE cache_scope impostato da DBMS_CLOUD.SEND_REQUEST. I valori validi sono PUBLIC o PRIVATE.

Funzione GET_RESPONSE_HEADERS

Questa funzione restituisce le intestazioni di risposta HTTP come dati JSON in un oggetto JSON.

Sintassi

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

Parametri

Parametro Descrizione
resp Tipo di risposta HTTP restituito da DBMS_CLOUD.SEND_REQUEST.

Eccezioni

Eccezione Errore Descrizione
invalid_response ORA-20025 Oggetto del tipo di risposta non valido passato a DBMS_CLOUD.GET_RESPONSE_HEADERS.

Funzione GET_RESPONSE_TEXT

Questa funzione restituisce la risposta HTTP in formato TEXT (VARCHAR2 o CLOB). In genere, la maggior parte delle API REST cloud restituisce una risposta JSON in formato testo. Questa funzione è utile se si prevede che la risposta HTTP sia in formato testo.

Sintassi

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

Parametri

Parametro Descrizione
resp Tipo di risposta HTTP restituito da DBMS_CLOUD.SEND_REQUEST.

Eccezioni

Eccezione Errore Descrizione
invalid_response ORA-20025 Oggetto del tipo di risposta non valido passato a DBMS_CLOUD.GET_RESPONSE_TEXT.

Funzione GET_API_RESULT_CACHE_SIZE

Questa funzione restituisce la dimensione della cache dei risultati configurata. Il valore della dimensione della cache si applica solo alla sessione corrente.

Sintassi

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Funzione e procedura SEND_REQUEST

Questa funzione e procedura avvia una richiesta HTTP, ottiene la risposta e termina la risposta. Questa funzione fornisce un workflow per l'invio di una richiesta API REST cloud con argomenti e la funzione restituisce un codice di risposta e un payload. Se si utilizza la procedura, è possibile visualizzare i risultati e i dettagli delle risposte dai risultati salvati con la vista SESSION_CLOUD_API_RESULTS.

Sintassi

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

Parametri

Parametro Descrizione
credential_name Nome della credenziale per l'autenticazione con l'API cloud nativa corrispondente.
uri URI HTTP per effettuare la richiesta.
method

Metodo di richiesta HTTP: GET, PUT, POST, HEAD, DELETE. Utilizzare la costante del pacchetto DBMS_CLOUD per specificare il metodo.

Per ulteriori informazioni, vedere Constanti API REST DBMS_CLOUD.

headers Intestazioni di richiesta HTTP per l'API cloud nativa corrispondente in formato JSON. Le intestazioni di autenticazione vengono impostate automaticamente e passano solo intestazioni personalizzate.
async_request_url

URL di richiesta asincrona.

Per ottenere l'URL, selezionare l'API di richiesta dall'elenco delle API (vedere https://docs.cloud.oracle.com/en-us/iaas/api/). Quindi, andare a trovare l'API per la richiesta nel riquadro sinistro. Ad esempio, API Database Services -> Autonomous AI Database -> StopAutonomousDatabase. Questa pagina mostra la home API (e mostra l'endpoint di base). Aggiungere quindi l'endpoint di base al percorso relativo ottenuto per il collegamento WorkRequest della richiesta di lavoro.

wait_for_states

L'attesa degli stati è di tipo DBMS_CLOUD_TYPES.wait_for_states_t. I valori riportati di seguito sono validi per gli stati previsti: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

Per wait_for_states sono consentiti più stati. Il valore predefinito per wait_for_states deve attendere uno qualsiasi degli stati previsti: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

timeout

Specifica il timeout, in secondi, delle richieste asincrone con i parametri async_request_url e wait_for_states.

Il valore predefinito è 0. Indica di attendere il completamento della richiesta senza timeout.

cache

Se TRUE specifica che la richiesta deve essere inserita nella cache nella cache API dei risultati REST.

Il valore predefinito è FALSE, ovvero le richieste API REST non vengono inserite nella cache.

cache_scope Specifica se tutti possono avere accesso a questa cache dei risultati della richiesta. Valori validi: "PRIVATE" e "PUBLIC". Il valore predefinito è "PRIVATE".
body Corpo della richiesta HTTP per le richieste PUT e POST.

Eccezioni

Eccezione Errore Descrizione
invalid_req_method ORA-20023 Il metodo di richiesta passato a DBMS_CLOUD.SEND_REQUEST non è valido.
invalid_req_header ORA-20024 Le intestazioni delle richieste passate a DBMS_CLOUD.SEND_REQUEST non sono in un formato JSON valido.

Note sull'uso

Procedura SET_API_RESULT_CACHE_SIZE

Questa procedura imposta la dimensione massima della cache per la sessione corrente. Il valore della dimensione della cache si applica solo alla sessione corrente.

Sintassi

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parametri

Parametro Descrizione
cache_size

Impostare la dimensione massima della cache sul valore specificato cache_size. Se la nuova dimensione massima della cache è inferiore alla dimensione corrente, i record meno recenti verranno eliminati finché il numero di righe non sarà uguale alla dimensione massima della cache specificata. Il valore massimo è 10000.

Se la dimensione della cache è impostata su 0, l'inserimento nella cache viene disabilitato nella sessione.

La dimensione predefinita della cache è 10.

Eccezioni

Eccezione Errore Descrizione
invalid API result cache size ORA-20032 Il valore minimo è 0 e il valore massimo è 10000. Questa eccezione viene visualizzata quando il valore di input è minore di 0 o maggiore di 10000.

Esempio

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

Contenuto correlato