Utilisation de SODA pour REST avec Autonomous Database

Autonomous Database prend en charge Simple Oracle Document Access (SODA) pour REST.

Présentation de l'utilisation de SODA pour REST

SODA pour REST est un service REST prédéployé qui peut être utilisé pour stocker des documents JSON dans votre base de données.

SODA permet un développement d'applications flexible de type NoSQL sans avoir à utiliser SQL. Avec SODA, les documents JSON sont stockés dans des collections nommées et gérés à l'aide d'opérations CRUD simples (créer, lire, mettre à jour et supprimer). Et bien que SQL ne soit pas requis, le JSON stocké dans les collections SODA est toujours entièrement accessible à partir de SQL si nécessaire. Par exemple, une application opérationnelle peut être entièrement créée à l'aide de SODA (sans SQL), mais les données peuvent ensuite être analysées à l'aide de SQL provenant de l'extérieur de l'application. Autonomous Database SODA offre aux développeurs d'applications le meilleur des mondes NoSQL et SQL : un développement d'applications rapide, flexible et évolutif sans perdre la capacité à tirer parti du langage SQL pour les analyses et le reporting.

SODA pour REST est déployé dans ORDS sous le modèle d'URL suivant, où schema correspond à un schéma de base de données compatible REST.

/ords/schema/soda/latest/*

Les exemples suivants utilisent l'outil de ligne de commande cURL (http://curl.haxx.se/) pour soumettre des demandes REST à la base de données. Cependant, d'autres clients et bibliothèques REST 3e partie doivent également fonctionner. Les exemples utilisent le schéma de base de données ADMIN, qui est activé pour REST. Vous pouvez utiliser SODA pour REST avec des commandes cURL à partir d'Oracle Cloud Shell.

Cette commande crée une collection nommée "fruit" dans le schéma ADMIN :

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

Ces commandes insèrent trois documents JSON dans la collection de fruits :

> 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"...

Cet exemple extrait un document JSON stocké de la collection :

> 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
}

Cette requête SQL accède à la collection de fruits :

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

L'interrogation renvoie les trois lignes suivantes :

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

Si vous utilisez Autonomous Database Toujours gratuit avec Oracle Database 23ai, Oracle recommande les éléments suivants :

Pour les projets qui ont été démarrés à l'aide d'une version de base de données antérieure à Oracle Database 21c, indiquez explicitement les métadonnées de la collection par défaut, comme indiqué dans l'exemple de la section Pilotes SODA. Pour les projets qui commencent à utiliser la version Oracle Database 21c ou une version ultérieure, utilisez simplement les métadonnées par défaut. Pour plus d'informations, reportez-vous à Pilotes SODA.

Ces exemples illustrent un sous-ensemble des fonctionnalités SODA et SQL/JSON. Pour plus d'informations, reportez-vous à :

Chargement des données échantillon de commande à l'aide de SODA pour REST

Oracle fournit un ensemble substantiel de documents de commande d'achat JSON, dans le fichier en texte brut POList.json, en tant que tableau JSON d'objets, où chaque objet représente un document.

Les exemples suivants utilisent l'outil de ligne de commande cURL (http://curl.haxx.se/) pour soumettre des demandes REST à la base de données. Cependant, d'autres clients et bibliothèques REST 3e partie doivent également fonctionner. Les exemples utilisent le schéma de base de données ADMIN, qui est activé pour REST. Vous pouvez utiliser SODA pour REST avec des commandes cURL à partir d'Oracle Cloud Shell.

Vous pouvez charger cet exemple de jeu de données de commande d'achat dans une collection purchaseorder sur votre instance Autonomous Database avec SODA pour REST, à l'aide des commandes curl suivantes :

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"

Vous pouvez ensuite utiliser ces données de commande d'achat pour essayer des exemples dans le Guide du développeur Oracle Database JSON.

Par exemple, la requête suivante sélectionne à la fois la valeur id d'un document JSON et les valeurs de la collection de commandes d'achat JSON stockée dans la colonne json_document de la table purchaseorder. Les valeurs sélectionnées proviennent des champs PONumber, Reference et Requestor de la colonne JSON json_document, qui sont projetés à partir du document en tant que colonnes virtuelles (pour plus d'informations, reportez-vous à Clause SQL NESTED au lieu de JSON_TABLE).

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

Pour plus d'informations, reportez-vous à :

Utilisation de SODA pour REST avec les informations d'identification client OAuth

Vous pouvez accéder à SODA pour REST sur Autonomous Database en utilisant l'authentification OAuth. Selon votre application, l'accès à SODA pour REST avec l'authentification OAuth peut améliorer les performances et la sécurité.

Pour utiliser l'authentification OAuth afin de fournir un accès limité à SODA pour REST sur Autonomous Database, procédez comme suit :

  1. En tant qu'utilisateur ADMIN, accédez à Database Actions et créez un utilisateur disposant des privilèges requis.
    1. Accédez à Database Actions en tant qu'utilisateur ADMIN.
      Pour plus d'informations, reportez-vous à Accès à Database Actions en tant qu'administrateur.
    2. Dans Database Actions, cliquez sur icône de navigation pour afficher les actions disponibles.
    3. Dans Database Actions, sous Administration, sélectionnez Utilisateurs de base de données.
    4. Cliquez sur Créer un utilisateur.
    5. Dans la zone Créer un utilisateur, dans l'onglet Utilisateur, entrez Nom utilisateur et un mot de passe, puis confirmez le mot de passe.
    6. Sélectionnez Accès Web.
    7. Dans la zone Créer un utilisateur, sélectionnez l'onglet Rôles accordés et accordez DWROLE à l'utilisateur.
    8. Cliquez sur Créer un utilisateur.
  2. Utilisez une feuille de calcul SQL dans Database Actions pour accorder les privilèges utilisateur requis pour charger les données.
    1. Accédez à Database Actions en tant qu'utilisateur ADMIN.
      Pour plus d'informations, reportez-vous à Accès à Database Actions en tant qu'administrateur.
    2. Dans Database Actions, cliquez sur icône de navigation pour afficher les actions disponibles.
    3. Dans Database Actions, sous Développement, cliquez sur SQL pour ouvrir une feuille de calcul SQL.
    4. Accordez à l'utilisateur les privilèges requis pour charger des données à partir de l'étape 1.
      GRANT UNLIMITED TABLESPACE TO user_name;
  3. Déconnectez-vous en tant qu'utilisateur ADMIN.
  4. Connectez-vous à Database Actions en tant qu'utilisateur configuré pour utiliser l'authentification OAuth.
  5. Dans Database Actions, utilisez une feuille de calcul SQL pour inscrire le client OAuth.
    1. Enregistrez le client OAuth.
      Par exemple, entrez les commandes suivantes dans la feuille de calcul SQL, où vous fournissez les valeurs appropriées pour votre utilisateur et votre application 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. Dans la feuille de calcul SQL, cliquez sur Exécuter le script pour exécuter la commande.

    Pour plus d'informations, reportez-vous à Référence de package OAUTH PL/SQL.

    Un client nommé my_client est ainsi inscrit pour accéder au privilège my_priv à l'aide des informations d'identification du client OAuth.

  6. Obtenez les valeurs client_id et client_secret requises pour générer le jeton d'accès.
    Par exemple, dans la feuille de calcul SQL, exécutez la commande suivante :
    SELECT id, name, client_id, client_secret FROM user_ords_clients;
  7. Obtenez le jeton d'accès. Pour obtenir un jeton d'accès, vous envoyez une demande REST GET à database_ORDS_urluser_name/oauth/token.

    database_ORDS_url est disponible à partir de Database Actions, sous Services associés, sur la carte RESTful Services and Soda. Pour plus d'informations, reportez-vous à Accès aux services RESTful et au service SODA pour REST.

    Dans la commande suivante, utilisez les éléments client_id et client_secret obtenus à l'étape 6.

    L'exemple suivant utilise l'outil de ligne de commande cURL (http://curl.haxx.se/) pour soumettre des demandes REST à Autonomous Database. Cependant, d'autres clients et bibliothèques REST 3e partie doivent également fonctionner.

    Vous pouvez utiliser l'outil de ligne de commande cURL pour soumettre la demande REST GET. Par exemple :

    > 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}

    Pour indiquer à la fois client_id et client_secret avec l'argument de boucle --user, entrez le signe deux-points pour séparer client_id et client_secret. Si vous indiquez uniquement le nom utilisateur client_id, la boucle vous invite à saisir un mot de passe et vous pouvez saisir client_secret à l'invite.

  8. Utilisez le jeton d'accès pour accéder à la ressource protégée.

    Le jeton obtenu à l'étape précédente est transmis dans l'en-tête d'autorisation. Par exemple :

    > 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}

Pour plus d'informations sur l'accès sécurisé aux services RESTful, reportez-vous à Configuration de l'accès sécurisé aux services RESTful.