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.

Oracle Public Cloud o multicloud Exadata Cloud@Customer

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:

• Infrastruttura Oracle Cloud

  Per informazioni sulle API REST di Oracle Cloud Infrastructure, consulta la sezione Riferimento API ed endpoint.

• Azure Cloud

  Per informazioni sulle API REST di Azure, vedere Azure REST Reference.

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:

• Si esegue direttamente DBMS_CLOUD.SEND_REQUEST come istruzione di livello superiore e la chiamata a DBMS_CLOUD.SEND_REQUEST e i risultati dell'API REST vengono salvati con lo stesso nome utente. In questo caso si ha accesso a tutti i risultati con il valore predefinito 'PRIVATE', impostato per cache_scope.

• Si scrive la procedura dei diritti di un richiamatore wrapper e come utente corrente la chiamata con DBMS_CLOUD.SEND_REQUEST richiama la procedura e i risultati dell'API REST vengono salvati con lo stesso nome utente. In questo caso, è possibile accedere a tutti i risultati con il valore predefinito 'PRIVATE', impostato per cache_scope.

• Si scrive la procedura dei diritti di un definer wrapper e la procedura è di proprietà di un altro utente. Quando si chiama DBMS_CLOUD.SEND_REQUEST all'interno della procedura, i risultati vengono salvati con il nome utente del proprietario della procedura.

  In questo caso, un utente con diritti di definer diverso richiama DBMS_CLOUD.SEND_REQUEST e i risultati dell'API REST vengono salvati con il proprietario della procedura di definer. In questo caso, per impostazione predefinita, quando cache_scope è PRIVATE', la sessione del chiamante non può visualizzare i risultati.

  Se il proprietario della procedura del definer desidera rendere disponibili i risultati a qualsiasi utente della sessione di richiamo, deve impostare cache_scope su 'PUBLIC' in DBMS_CLOUD.SEND_REQUEST.

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

• Se si utilizza Oracle Cloud Infrastructure, è necessario utilizzare un valore di credenziale basato sulla chiave di firma per credential_name. Per ulteriori informazioni, vedere Procedura CREDENTIAL.

• I parametri facoltativi async_request_url, wait_for_states e timeout consentono di gestire le richieste con tempi di esecuzione lunghi. Utilizzando questo modulo asincrono di send_request, la funzione attende lo stato di completamento specificato in wait_for_states prima di tornare. Con questi parametri nella richiesta di invio, si passano gli stati di ritorno previsti nel parametro wait_for_states e si utilizza il parametro async_request_url per specificare una richiesta di lavoro associata, la richiesta non viene restituita immediatamente. La richiesta analizza invece async_request_url finché lo stato restituito non è uno degli stati previsti oppure viene superato il valore timeout (timeout è facoltativo). Se non viene specificato alcun valore timeout, la richiesta attende che si verifichi uno stato trovato in wait_for_states.

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

• Formati URI storage degli oggetti cloud

• Parametro formato