Usa SODA per REST con Autonomous Database

Autonomous Database supporta il SOA (Simple Oracle Document Access) per REST.

Panoramica sull'uso di SODA per REST

SODA per REST è un servizio REST predistribuito che può essere utilizzato per memorizzare i documenti JSON nel database.

SODA consente lo sviluppo flessibile di applicazioni in stile NoSQL senza dover utilizzare SQL. Con SODA, i documenti JSON vengono memorizzati in raccolte denominate e gestiti utilizzando semplici operazioni CRUD (creazione, lettura, aggiornamento ed eliminazione). Inoltre, sebbene SQL non sia necessario, il JSON memorizzato nelle raccolte SODA è ancora completamente accessibile da SQL quando necessario. Ad esempio, un'applicazione operativa può essere completamente creata utilizzando SODA (senza SQL), ma i dati possono essere successivamente analizzati utilizzando SQL dall'esterno dell'applicazione. Autonomous Database SODA offre agli sviluppatori di applicazioni il meglio del mondo NoSQL e SQL: sviluppo di applicazioni rapido, flessibile e scalabile senza perdere la possibilità di sfruttare SQL per gli analytics e il reporting.

SODA per REST viene distribuito in ORDS nel seguente pattern di URL, dove schema corrisponde a uno schema di database abilitato per REST.

/ords/schema/soda/latest/*

Gli esempi riportati di seguito utilizzano lo strumento della riga di comando cURL (http://curl.haxx.se/) per sottomettere richieste REST al database. Tuttavia, dovrebbero funzionare anche altri client e librerie REST 3rd party. Gli esempi utilizzano lo schema di database ADMIN, abilitato per REST. È possibile eseguire SODA per REST con i comandi cURL da Oracle Cloud Shell.

Questo comando crea una nuova raccolta denominata "fruit" nello schema ADMIN:

> curl -X PUT -u 'ADMIN:<password>' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

Questi comandi inseriscono tre documenti JSON nella raccolta di frutta:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange", "count":42}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"6F7E5C60197E4C8A83AC7D7654F2E375"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"pear", "count":5}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"83714B1E2BBA41F7BA4FA93B109E1E85"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" \
 --data '{"name":"apple", "count":12, "color":"red"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"BAD7EFA9A2AB49359B8F5251F0B28549"...

Questo esempio recupera un documento JSON memorizzato dalla raccolta:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit?action=query"

{
  "items": [
    {
      "id":"6F7E5C60197E4C8A83AC7D7654F2E375",
      "etag":"57215643953D7C858A7CB28E14BB48549178BE307D1247860AFAB2A958400E16",
      "lastModified":"2019-07-12T19:00:28.199666Z",
      "created":"2019-07-12T19:00:28.199666Z",
      "value":{"name":"orange", "count":42}
    }
  ],
  "hasMore":false,
  "count":1
}

Questa query SQL accede alla raccolta di frutta:

SELECT 
     f.json_document.name,
     f.json_document.count,
     f.json_document.color
FROM fruit f;

La query restituisce le tre righe seguenti:

name      count     color
--------- --------- -------
orange    42        null
pear      5         null
apple     12        red
Nota

Se si utilizza Autonomous Database Sempre gratis con Oracle Database 23ai, Oracle consiglia quanto segue:

Per i progetti che sono stati avviati utilizzando una release di database precedente a Oracle Database 21c, specificare in modo esplicito i metadati per la raccolta predefinita come specificato nell'esempio nella sezione Driver SODA. Per i progetti che hanno iniziato a utilizzare la release 21c o successiva di Oracle Database, utilizzare solo i metadati predefiniti. Per ulteriori informazioni, vedere Driver SOA.

Questi esempi mostrano un subset delle funzioni SODA e SQL/JSON. Per ulteriori informazioni, vedere gli argomenti riportati di seguito.

Carica dati campione ordine di acquisto mediante SODA per REST

Oracle fornisce un set sostanziale di documenti di ordine di acquisto JSON, nel file di testo normale POList.json, come un array JSON di oggetti, in cui ciascun oggetto rappresenta un documento.

Gli esempi riportati di seguito utilizzano lo strumento della riga di comando cURL (http://curl.haxx.se/) per sottomettere richieste REST al database. Tuttavia, dovrebbero funzionare anche altri client e librerie REST 3rd party. Gli esempi utilizzano lo schema di database ADMIN, abilitato per REST. È possibile utilizzare SODA per REST con i comandi cURL da Oracle Cloud Shell.

È possibile caricare questo set di dati dell'ordine di acquisto di esempio in una raccolta purchaseorder in Autonomous Database con SODA per REST, utilizzando i comandi curl riportati di seguito.

curl -X GET "https://raw.githubusercontent.com/oracle/db-sample-schemas/master/order_entry/POList.json" -o POList.json

curl -X PUT -u 'ADMIN:password' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder"

curl -X POST -H -u 'ADMIN:password' 'Content-type: application/json' -d @POList.json \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder?action=insert"

È quindi possibile utilizzare questi dati degli ordini di acquisto per provare esempi in Oracle Database JSON Developer's Guide.

Ad esempio, la query seguente seleziona sia il valore id di un documento JSON che i valori dalla raccolta di ordini di acquisto JSON memorizzata nella colonna json_document della tabella purchaseorder. I valori selezionati provengono dai campi PONumber, Reference e Requestor della colonna JSON json_document, che vengono proiettati dal documento come colonne virtuali (per ulteriori informazioni, vedere Clausola SQL NESTED anziché JSON_TABLE).

SELECT id, t.*
  FROM purchaseorder
    NESTED json_document COLUMNS(PONumber, Reference, Requestor) t;

Per ulteriori informazioni, vedere gli argomenti riportati di seguito.

Usa SODA per REST con credenziali client OAuth

Puoi accedere a SODA per REST su Autonomous Database utilizzando l'autenticazione OAuth. A seconda dell'applicazione, l'accesso a SODA per REST con l'autenticazione OAuth può migliorare le prestazioni e la sicurezza.

Eseguire i passi riportati di seguito per utilizzare l'autenticazione OAuth per fornire accesso limitato a SODA per REST su Autonomous Database.

  1. L'utente ADMIN può accedere a Database Actions e creare un utente con i privilegi richiesti.
    1. Accedere a Database Actions come ADMIN.
      Per ulteriori informazioni, vedere Accedere alle azioni del database come ADMIN.
    2. In Database Actions fare clic su icona di navigazione per visualizzare le azioni disponibili.
    3. In Azioni database, in Amministrazione selezionare Utenti database.
    4. Fare clic su Crea utente.
    5. Nell'area Crea utente, nella scheda Utente, immettere Nome utente e una Password e confermare la password.
    6. Selezionare Accesso Web.
    7. Nell'area Crea utente, selezionare la scheda Ruoli concessi e concedere DWROLE all'utente.
    8. Fare clic su Crea utente.
  2. Utilizzare un foglio di lavoro SQL in Database Actions per concedere i privilegi utente necessari per caricare i dati.
    1. Accedere a Database Actions come ADMIN.
      Per ulteriori informazioni, vedere Accedere alle azioni del database come ADMIN.
    2. In Database Actions fare clic su icona di navigazione per visualizzare le azioni disponibili.
    3. In Azioni database, in Sviluppo fare clic su SQL per aprire un foglio di lavoro SQL.
    4. Concedere i privilegi utente necessari per caricare i dati all'utente dal passo 1.
      GRANT UNLIMITED TABLESPACE TO user_name;
  3. Eseguire la disconnessione come utente ADMIN.
  4. Accedere a Database Actions come utente che si sta impostando per utilizzare l'autenticazione OAuth.
  5. In Database Actions utilizzare un foglio di lavoro SQL per registrare il client OAuth.
    1. Registrare il client OAuth.
      Ad esempio, immettere i seguenti comandi nel foglio di lavoro SQL, in cui fornire i valori appropriati per l'utente e l'applicazione client.
      BEGIN
        OAUTH.create_client(
          p_name            => 'my_client',
          p_grant_type      => 'client_credentials',
          p_owner           => 'Example Company',
          p_description     => 'A client for my SODA REST resources',
          p_support_email   => 'user_name@example.com',
          p_privilege_names => 'my_priv'
        );
       
        OAUTH.grant_client_role(
          p_client_name => 'my_client',
          p_role_name   => 'SQL Developer'
        );
       
        OAUTH.grant_client_role(
          p_client_name => 'my_client',
          p_role_name   => 'SODA Developer'
        );
        COMMIT;
      END;
      /
    2. Nel foglio di lavoro SQL, fare clic su Esegui script per eseguire il comando.

    Per ulteriori informazioni, vedere Riferimento al package PL/SQL OAUTH.

    Registra un client denominato my_client per accedere al privilegio my_priv utilizzando le credenziali del client OAuth.

  6. Ottenere i valori client_id e client_secret necessari per generare il token di accesso.
    Ad esempio, nel foglio di lavoro SQL eseguire il comando seguente:
    SELECT id, name, client_id, client_secret FROM user_ords_clients;
  7. Ottenere il token di accesso. Per ottenere un token di accesso, inviare una richiesta REST GET a database_ORDS_urluser_name/oauth/token.

    database_ORDS_url è disponibile in Database Actions, in Servizi correlati, nella scheda RESTful Services and Soda. Per ulteriori informazioni, vedere Accedi ai servizi RESTful e a SODA per REST.

    Nel comando seguente, utilizzare client_id e client_secret ottenuti al passo 6.

    Nell'esempio riportato di seguito viene utilizzato lo strumento della riga di comando cURL (http://curl.haxx.se/) per sottomettere richieste REST ad Autonomous Database. Tuttavia, dovrebbero funzionare anche altri client e librerie REST 3rd party.

    È possibile utilizzare lo strumento della riga di comando cURL per inviare la richiesta REST GET. Ad esempio:

    > curl -i -k --user SBA-iO9Xe12cdZHYfryBGQ..:vvUQ1AagTqAqdA2oN7afSg.. --data "grant_type=client_credentials"https://mqssyowmqvgac1y-doc.adb.region.oraclecloudapps.com/ords/user_name/oauth/token
    HTTP/1.1 200 OK
    Date: Mon, 22 Jun 2020 15:17:11 GMT
    Content-Type: application/jsonTransfer-Encoding: chunked
    Connection: keep-alive
    X-Frame-Options: SAMEORIGIN  
    
    {"access_token":"JbOKtAuDgEh2DXx0QhvPGg","token_type":"bearer","expires_in":3600}

    Per specificare sia il valore client_id che il valore client_secret con l'argomento curl --user, immettere i due punti per separare client_id e client_secret. Se si specifica solo il nome utente, client_id, curl richiede una password ed è possibile immettere il valore client_secret al prompt.

  8. Utilizzare il token di accesso per accedere alla risorsa protetta.

    Il token ottenuto nel passo precedente viene passato nell'intestazione di autorizzazione. Ad esempio:

    > curl -i -H "Authorization: Bearer JbOKtAuDgEh2DXx0QhvPGg" -X GET https://database_id.adb.region.oraclecloudapps.com/ords/user_name/soda/latest
    HTTP/1.1 200 OK
    Date: Mon, 22 Jun 2020 15:20:58 GMT
    Content-Type: application/json
    Content-Length: 28
    Connection: keep-alive
    X-Frame-Options: SAMEORIGIN
    Cache-Control: private,must-revalidate,max-age=0
    
    
    {"items":[],"hasMore":false}

Per informazioni complete sull'accesso sicuro ai servizi RESTful, vedere Configuring Secure Access to RESTful Services.