DBMS_CLOUD API REST

Prerequisiti

Come sviluppatore, puoi utilizzare le procedure DBMS_CLOUD con Autonomous Database distribuite su Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

A seconda della scelta di distribuzione, è necessario soddisfare i seguenti prerequisiti per utilizzare le API REST 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 mediante un gateway NAT dall'amministratore della flotta, come descritto di seguito.

Crea un gateway NAT nella rete cloud virtuale (VCN) in cui risiedono le tue risorse di Autonomous 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 di uscita a ogni subnet (nella VCN) in cui risiedono le risorse di Autonomous 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:
  - Data: 0.0.0.0/0
  - Tipo di destinazione: gateway NAT
  - Destinazione: il nome del gateway NAT appena creato nella VCN
  Se la 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 di sicurezza della subnet, fare clic sul nome della lista di sicurezza della subnet per visualizzare la relativa pagina Dettagli lista 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
  - Data: 0.0.0.0/0
  - Protocollo IP: TCP
  - Intervallo porte di origine: 443
  - Intervallo di porte di destinazione: tutte
  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 lo stato dell'infrastruttura Exadata non è Richiede attivazione. Una volta attivato, non è possibile modificare tali impostazioni.

L'impostazione di un proxy HTTP per un'infrastruttura Exadata già fornita richiede una richiesta di servizio (SR) in My Oracle Support. Per informazioni dettagliate, vedere Create a Service Request in My Oracle Support.

DBMS_CLOUD API REST

In questa sezione vengono descritte le API REST DBMS_CLOUD fornite con Autonomous 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 Database.
Funzione GET_RESPONSE_TEXT	Questa funzione restituisce la risposta HTTP in formato TEXT (`VARCHAR2` o `CLOB`) in Autonomous 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.
SEND_REQUEST Funzione e procedura	Questa funzione avvia una richiesta HTTP, ottiene la risposta e termina la risposta in Autonomous 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 un payload.
SET_API_RESULT_CACHE_SIZE Procedura	Questa procedura imposta la dimensione massima della cache per la sessione corrente.

DBMS_CLOUD Panoramica delle API REST

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

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

Infrastruttura Oracle Cloud
Per informazioni sulle API REST di Oracle Cloud Infrastructure, vedere Riferimento e endpoint delle API.
Azure Cloud ^{Foot 1}
Per informazioni sulle API REST di Azure, vedere Riferimento alle API REST di Azure.

DBMS_CLOUD Costanti API REST

Descrive le costanti DBMS_CLOUD per effettuare richieste HTTP utilizzando DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD supporta i metodi GET, PUT, POST, HEAD e DELETE HTTP. Il metodo API REST da utilizzare per una richiesta HTTP è in genere documentato nella documentazione dell'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'`

DBMS_CLOUD Cache dei risultati dell'API REST

È possibile salvare i risultati dell'interfaccia 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 all'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'interfaccia 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 sono 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.

DBMS_CLOUD Parametro risultati API REST cache_scope

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'interfaccia 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, esistono tre possibilità che determinano se l'utente corrente può visualizzare i risultati nella cache, in base al valore cache_scope:

È possibile eseguire 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 è possibile accedere a tutti i risultati con il valore predefinito 'PRIVATE', impostato per cache_scope.
Si scrive la procedura dei diritti di un chiamante wrapper e come utente corrente la chiamata con DBMS_CLOUD.SEND_REQUEST chiama la procedura e i risultati dell'API REST vengono salvati con lo stesso nome utente. In questo caso, si dispone dell'accesso a tutti i risultati con il valore predefinito 'PRIVATE', impostato per cache_scope.
Si scrive la procedura dei diritti di un definitore 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, l'utente con diritti di un altro definitore richiama DBMS_CLOUD.SEND_REQUEST e i risultati dell'API REST vengono salvati con il proprietario della procedura di definizione. Per impostazione predefinita, se cache_scope è PRIVATE', la sessione del chiamante non può visualizzare i risultati.

Se il proprietario della procedura del definitore desidera rendere disponibili i risultati per qualsiasi utente della sessione chiamante, è necessario impostare cache_scope su 'PUBLIC' in DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD Vista SESSION_CLOUD_API_RESULTS API REST

È possibile salvare i risultati dell'interfaccia 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 appartenenti alla sessione utente. Al termine della sessione, i dati nel file SESSION_CLOUD_API_RESULTS vengono rimossi.

A colonne	Descrizione
`URI`	URL della richiesta dell'API REST `DBMS_CLOUD`
`TIMESTAMP`	Indicatore orario risposta API `DBMS_CLOUD` REST
`CLOUD_TYPE`	Il tipo cloud dell'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 delle richieste dell'API REST `DBMS_CLOUD`
`REQUEST_BODY_TEXT`	Corpo della richiesta dell'API REST `DBMS_CLOUD` in `CLOB`
`RESPONSE_STATUS_CODE`	Il codice di stato della risposta dell'API REST `DBMS_CLOUD`, ad esempio `200(OK)`, `404(Not Found)`
`RESPONSE_HEADERS`	Intestazioni di risposta dell'API REST `DBMS_CLOUD`
`RESPONSE_BODY_TEXT`	Corpo della risposta dell'API REST `DBMS_CLOUD` in `CLOB`
`SCOPE`	Il valore `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;

SEND_REQUEST Funzione e procedura

Questa funzione e questa procedura iniziano una richiesta HTTP, ottengono la risposta e terminano 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`. Usare la costante del pacchetto `DBMS_CLOUD` per specificare il metodo. Per ulteriori informazioni, vedere DBMS_CLOUD Costanti API REST.
`headers`	Intestazioni delle richieste HTTP per l'API cloud nativa corrispondente in formato JSON. Le intestazioni di autenticazione vengono impostate automaticamente, passando solo le intestazioni personalizzate.
`async_request_url`	URL di richiesta asincrona. Per ottenere l'URL, selezionare l'interfaccia API di richiesta dall'elenco delle interfacce API (vedere https://docs.cloud.oracle.com/en-us/iaas/api/). Quindi, individuare l'API per la richiesta nel riquadro sinistro. Ad esempio, Database Services API → Autonomous Database → StopAutonomousDatabase. Questa pagina mostra la home API (e mostra l'endpoint di base). Aggiungere quindi l'endpoint di base con il percorso relativo ottenuto per il collegamento WorkRequest della richiesta di lavoro.
`wait_for_states`	Lo stato di attesa degli stati è di tipo `DBMS_CLOUD_TYPES.wait_for_states_t`. Di seguito sono riportati i valori 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` consiste nell'attesa di uno qualsiasi degli stati previsti: '`ACTIVE`', '`CANCELED`', '`COMPLETED`', '`DELETED`', '`FAILED`', '`SUCCEEDED`'.
`timeout`	Specifica il timeout, in secondi, per le richieste asincrone con i parametri `async_request_url` e `wait_for_states`. Il valore predefinito è `0`. Ciò indica di attendere il completamento della richiesta senza alcun timeout.
`cache`	Se `TRUE` specifica che la richiesta deve essere inserita nella cache dell'API dei risultati REST. Il valore predefinito è `FALSE`, ovvero le richieste API REST non vengono inserite nella cache.
`cache_scope`	Specifica se tutti possono accedere a questa cache dei risultati delle richieste. 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 di richiesta passate a `DBMS_CLOUD.SEND_REQUEST` non sono in formato JSON valido.

Note sull'uso

Se si utilizza Oracle Cloud Infrastructure, è necessario utilizzare un valore di credenziale basato su chiave di firma per credential_name. Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedura.
I parametri facoltativi async_request_url, wait_for_states e timeout consentono di gestire le richieste con tempi di esecuzione lunghi. Utilizzando questo formato 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 superano gli stati di restituzione 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. Invece, la richiesta esamina async_request_url fino a quando lo stato restituito non è uno degli stati previsti o viene superato timeout (timeout è facoltativo). Se non viene specificato alcun valore timeout, la richiesta attende che si verifichi uno stato trovato in wait_for_states.

SET_API_RESULT_CACHE_SIZE Procedura

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

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 della cache, i record precedenti vengono eliminati fino a quando il numero di righe non è uguale alla dimensione massima della cache specificata. Il valore massimo è `10000`. Se la dimensione della cache è impostata su `0`, l'inserimento nella cache è disabilitato nella sessione. La dimensione predefinita della cache è `10`.

cache_size

Impostare la dimensione massima della cache sul valore specificato cache_size. Se la nuova dimensione massima della cache è inferiore alla dimensione corrente della cache, i record precedenti vengono eliminati fino a quando il numero di righe non è uguale alla dimensione massima della cache specificata. Il valore massimo è 10000.

Se la dimensione della cache è impostata su 0, l'inserimento nella cache è 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);