# Transformer une base Oracle en OpenData avec Oracle REST Data Services > Mettez en place Oracle REST Data Services (ORDS) dans Docker pour transformer votre base Oracle en OpenData avec une API REST puissante. Filtrage et pagination inclus. ---  **TL;DR** Ce tutoriel montre comment transformer votre base de données Oracle en une API RESTful puissante grâce à Oracle REST Data Services (ORDS) dans Docker. En partant d'un container Oracle DB déjà mis en place précédemment, ce guide vous accompagne dans le déploiement du container ORDS, sa liaison avec votre base de données et la configuration des schémas pour l'accès REST. Vous apprendrez à activer REST sur des tables ou des vues précises avec Oracle SQL Developer, puis à accéder à vos données via des endpoints OpenAPI générés automatiquement. L'article explique aussi comment utiliser les paramètres d'URL pour des requêtes avancées : filtrage, tri et pagination. Dans un article précédent ([Running Oracle Database Server as a Docker container](/blog/docker-oracle-database-server)), nous avons créé un container Docker appelé `oracle-db` dans lequel tourne une base de données Human Resources. Dans cet article, nous allons exposer partiellement la base de données sur le web avec OpenAPI. En résumé, nous allons permettre à des personnes autorisées d'accéder par exemple à `http://oursite/api/employees` pour obtenir la liste de tous les employés. *Ce schéma OpenAPI généré peut d'ailleurs être linté ; voyez [Validate your OpenAPI schema against the Belgif REST standards](/blog/belgif-api-linter).* Exactement comme nous l'avons fait avec PostgREST (voir mon article [Don't query your PostgreSQL db anymore, prefer PostgREST](/blog/docker-postgrest)) mais, cette fois, avec une base de données Oracle. Et la magie viendra de **[Oracle REST Data Services](https://www.oracle.com/database/technologies/appdev/rest.html)**, aussi appelé **ords**. Voici où nous allons : la même table Oracle, désormais accessible en simple JSON via HTTP.  Dans l'article précédent ([Running Oracle Database Server as a Docker container](/blog/docker-oracle-database-server)), nous avons créé un container Docker appelé `oracle-db` dans lequel tourne une base de données Human Resources. Lisez cet article et suivez les étapes pour disposer, avant de continuer ici, d'un container Docker fonctionnel comme décrit ci-dessous. ## Quelques prérequis {#some-prerequisites} **Avant de commencer, assurez-vous que...** 1. Vous avez un container Docker appelé `oracle-db` en cours d'exécution 2. Le container tourne donc sur votre `localhost` 3. Le numéro de port pour accéder à votre base est `1521` 4. Les identifiants à utiliser sont `SYS` (ou `SYSTEM`) et `admin` comme mot de passe 5. Le container contient une base appelée `ORCLPDB1` (aussi appelée nom de service) qui est l'exemple Human Resources d'Oracle (voyez l'article mentionné) et 6. Notre base `oracle-db` tourne sur un réseau appelé `oracle` ## Télécharger une image Docker pour Oracle REST Data Services {#download-a-docker-image-for-oracle-rest-data-services} Contrairement à l'image Docker Oracle Database Server, aucun identifiant n'est nécessaire pour télécharger l'image officielle [Oracle ORDS](https://container-registry.oracle.com/ords/ocr/ba/database/ords-developer). Lancez simplement `docker pull container-registry.oracle.com/database/ords-developer:latest` pour la récupérer. C'est une image de 2,2 Go. ```bash $ docker pull container-registry.oracle.com/database/ords-developer:latest ``` ## Créer un container Oracle ORDS {#create-an-oracle-ords-container} Nous allons procéder étape par étape. ### Créer un volume pour la configuration ORDS {#create-a-volume-for-the-ords-configuration} ORDS a besoin de deux dossiers : un pour ce qu'il appelle **ses secrets** et un pour **ses fichiers de configuration**. Utilisons un volume Docker auto-géré pour les fichiers de configuration ; lancez donc `docker volume create ords_config` dans votre console. ### Configurer la chaîne de connexion {#configure-the-connection-string} Pour pouvoir démarrer ORDS, la doc officielle indique qu'il faut créer un fichier appelé `conn_string.txt` avec notre chaîne de connexion. Dans notre cas, voici le fichier à créer : ```bash $ mkdir -p ords_secrets $ chmod 777 ords_secrets $ echo 'CONN_STRING=SYS/admin@oracle-db:1521/ORCLPDB1' > ords_secrets/conn_string.txt ``` > **Information:** > > Si vous avez un doute sur la valeur à utiliser comme `service_name` : démarrez une console sqlplus (`docker exec -it ` oracle-db ` sqlplus sys/admin@` ORCLPDB1 ` as sysdba`) et lancez `SELECT global_name FROM global_name;` dans SQL\*Plus. > >  L'image Docker officielle ORDS est livrée avec APEX (l'abréviation d'*Oracle Application Express*). D'après la documentation, *Oracle Application Express (APEX) est une plateforme de développement low-code qui vous permet de construire des applications d'entreprise évolutives et sécurisées, dotées de fonctionnalités de premier plan, déployables n'importe où. Voir pour plus d'informations.* Pour nos besoins, nous voulons juste ORDS ; APEX ne nous sert à rien. Pour cela, nous allons initialiser la variable d'environnement `IGNORE_APEX` à `TRUE`. ### Créer le container {#create-the-container} Pour créer notre container ORDS (sans APEX), lancez : ```bash $ docker run -d --rm \ --name oracle-ords \ --network oracle \ -p 8181:8181 \ -e IGNORE_APEX=TRUE \ -v ./ords_secrets/:/opt/oracle/variables \ -v ords_config:/etc/ords/config/ \ container-registry.oracle.com/database/ords-developer:latest ``` > **Le `docker run` expliqué:** > > * `-d`: ORDS tournera comme service daemon, > * `--rm`: une fois le service terminé, le container Docker sera supprimé, > * `--network`: nous devons faire tourner ORDS sur le même réseau que notre base de données, c'est-à-dire `oracle` > * `-p > 8181 > :8181`: nous devons mapper le port interne `8181` utilisé par ORDS sur notre host et, par simplicité, nous exposerons aussi le port 8181, > * `-e IGNORE_APEX=TRUE`: comme dit, nous voulons ORDS, pas APEX ; on dit donc à Docker de ne pas installer APEX, > * `-v ./ords_secrets/:/opt/oracle/variables`: comme indiqué dans la documentation, nous devons fournir un fichier appelé `conn_string.txt` et mapper ce fichier dans `/opt/oracle/variables` à l'intérieur du container et, enfin, > * `-v ords_config:/etc/ords/config/`: nous utiliserons un volume Docker auto-géré pour conserver les fichiers de configuration d'ORDS. Cette commande va ajouter le layer ORDS dans votre base de données (sur base de la chaîne de connexion, soit ORCLPDB1 chez nous).  > **Aux lancements suivants, il ne faut plus fournir la chaîne de connexion.:** > > Une fois ORDS installé comme ci-dessus, si vous devez relancer le container ORDS, il ne faut plus fournir le secret : il faut donc retirer le flag `-v ./ords_secrets/:/opt/oracle/variables`. > > Si vous devez relancer le container, voici la ligne de commande : > > ```bash > $ docker run -d --rm \ > --name oracle-ords \ > --network oracle \ > -p 8181:8181 \ > -v ords_config:/etc/ords/config/ \ > container-registry.oracle.com/database/ords-developer:latest > ``` ### Nous devons créer notre utilisateur dans la base de données {#we-need-to-create-our-user-in-our-database} Avant de pouvoir utiliser ORDS et accéder à des objets via une requête HTTP, nous devons créer un nouvel utilisateur dans notre base et lui donner quelques droits. Lancez `docker exec -it ` oracle-db ` sqlplus sys/admin@` ORCLPDB1 ` as sysdba` pour démarrer une console SQL\*Plus et vous connecter à la base PDB. Nous devons créer un utilisateur pour ORDS ; disons l'utilisateur `hr`. Lancez cette instruction : `CREATE USER hr IDENTIFIED BY admin;` Puis accordez les permissions : `GRANT CONNECT, RESOURCE, UNLIMITED TABLESPACE TO hr;`  Une fois créé, nous devons quitter la console (démarrée avec l'utilisateur `sys`) et nous reconnecter avec notre utilisateur. Tapez donc `exit` pour quitter la console sqlplus et lancez `docker exec -it ` oracle-db ` sqlplus hr/admin@` ORCLPDB1. De retour dans la console sqlplus (connecté en tant qu'utilisateur `hr`), lancez : `EXECUTE ORDS.ENABLE_SCHEMA;`.  *(lisez [ORDS 101: Enabling Oracle Schemas for HTTPS/REST](https://www.thatjeffsmith.com/archive/2023/09/ords-101-enabling-oracle-schemas-for-https-rest/) si vous voulez plus de détails)* > **Caution:** > > Si vous obtenez une erreur à ce stade, cela signifie qu'ORDS n'a pas été installé dans votre base de données. Relisez le chapitre **Créer le container**. #### Démarrer l'interface web d'ORDS {#start-ords-web-interface} À ce stade, nous avons installé ORDS, configuré notre base pour l'utiliser et créé un utilisateur appelé `hr`. Nous pouvons nous rendre sur `http://localhost:` 8181`/ords` et nous connecter au dashboard ORDS : > Screenshot — http\://localhost:8181/ords/\_/landing > > Page d'accueil d'ORDS > **Note:** > > APEX n'a pas été installé et est donc désactivé Utilisez `hr` et `admin`, notre utilisateur personnalisé, sur la page de login : > Screenshot — http\://localhost:8181/ords/\_/landing > > Page de login d'ORDS Dès à présent, nous pouvons demander à ORDS la liste des objets déjà accessibles ; rendez-vous simplement sur `http://localhost:` 8181`/ords/hr/open-api-catalog/` pour obtenir... une liste vide. C'est normal puisque nous devons indiquer quel objet (une table, une vue, une procédure stockée) est accessible ou non. Mais oui, en accédant à `http://localhost:` 8181`/ords/hr/open-api-catalog/` et en obtenant une réponse JSON, nous pouvons confirmer qu'ORDS tourne correctement. La page `http://localhost:` 8181`/ords/hr/open-api-catalog/` s'appelle le **Schema Metadata** ([documentation](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.4/aelig/developing-REST-applications.html#GUID-55736274-502E-4511-B232-829924334FA2)). #### Activer REST sur les objets de la base {#rest-enable-database-objects} Nous devons donc activer chaque objet un par un. Le plus simple est d'utiliser [Oracle SQL Developer](https://www.oracle.com/be/database/sqldeveloper). Si vous ne l'avez pas, téléchargez-le gratuitement.  Créez une nouvelle connexion avec ces paramètres : | Label | Value | | ----------------- | ------------------------ | | Nom | `Human Resources - ORDS` | | Nom d'utilisateur | `hr` | | Rôle | `default` | | Mot de passe | `admin` | | Nom d'hôte | `127.0.0.1` | | Port | `1521` | | Nom de service | `orclpdb1` |  Cliquez sur le bouton `Save` puis sur `Connect`. Juste après le login, en cliquant sur la liste des tables ou des vues, il n'y a rien. C'est normal : nous venons de créer notre utilisateur `hr` et le schéma `hr` associé, et il n'y a aucun objet dans ce schéma.  ##### Ajouter une vue employee dans notre schéma hr {#adding-an-employee-view-in-our-hr-schema} Connectons-nous à notre base et affichons la liste des employés : lancez `docker exec -it ` oracle-db ` sqlplus sys/admin@` ORCLPDB1 ` as sysdba`, puis `SELECT EMPLOYEE_ID, FIRST_NAME, LAST_NAME, EMAIL FROM SYSTEM.EMPLOYEES;`.  Maintenant que nous sommes sûrs d'avoir accès à la table, créons une vue dans notre schéma `hr` pour afficher le contenu de la table : * lancez `GRANT SELECT ON SYSTEM.EMPLOYEES TO hr;` et * créez la vue en lançant `CREATE VIEW HR.EMPLOYEES AS SELECT EMPLOYEE_ID, FIRST_NAME, LAST_NAME, EMAIL, PHONE_NUMBER, HIRE_DATE, JOB_ID, SALARY, COMMISSION_PCT, MANAGER_ID, DEPARTMENT_ID FROM SYSTEM.EMPLOYEES;`. Si nous voulons vérifier notre vue : * Tapez `exit` dans la console sqlplus puisque vous êtes connecté en tant que `sys`, * Dans la console Linux, lancez `docker exec -it ` oracle-db ` sqlplus hr/admin@` ORCLPDB1 pour vous connecter en tant que `hr`, puis * lancez `SELECT * FROM HR.EMPLOYEES;`. Comme vous le voyez, vous obtenez la liste des employés. À ce stade, nous avons donc ajouté une vue appelée `employees` dans notre schéma `hr` et elle fonctionne. > **N'utilisez pas SELECT \* FROM:** > > C'est une très mauvaise pratique d'utiliser `SELECT * FROM ...`, veillez toujours à sélectionner uniquement les champs nécessaires. Retournez dans l'interface Oracle SQL Developer, faites un clic droit sur le nœud `Views` et choisissez `Refresh`. Vous verrez la vue ajoutée :  Clic droit sur la vue `EMPLOYEES` puis cliquez sur `Enable REST Service...`.  Veillez à cocher la case `Enable object`, donnez un nom à votre objet et, pour ce petit tutoriel, décochez la case `Authorization required`.  Cliquez sur le bouton `Next` et prêtez attention à l'onglet `SQL` :  Vous obtiendrez le DDL à exécuter dans une console si vous souhaitez activer REST sur la table par le code, plutôt qu'avec l'interface graphique. La dernière étape est de passer sur le site ORDS (`http://localhost:` 8181`/ords/hr/_sdw/?nav=rest-workshop`). Rafraîchissez la page et vous verrez maintenant que vous avez un objet dans la zone `AUTOREST` : > Screenshot — http\://localhost:8181/ords/hr/\_sdw/?nav=rest-workshop > > Il y a un objet dans la zone AUTOREST Cliquez sur cette zone et vous verrez l'objet (qui est une vue) sur lequel nous avons activé REST précédemment : > Screenshot — http\://localhost:8181/ords/hr/\_sdw/?nav=rest-workshop > > REST est activé sur Employees via AUTOREST Regardez l'icône *Open in a new tab* sur l'image ci-dessus. Cliquez sur ce bouton et vous obtiendrez vos enregistrements en réponse JSON : > Screenshot — http\://localhost:8181/ords/hr/employees/ > > Récupérer la liste des employés en réponse REST JSON L'URL `http://localhost:` 8181`/ords/hr/employees/` s'appelle l'**Object Data** ([documentation](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.4/aelig/developing-REST-applications.html#GUID-0B17836D-E5B5-4B45-A9DA-0ABF62426EDF)) Comme ce n'est rien de plus qu'une URL, vous pouvez l'utiliser avec n'importe quel outil, par exemple `curl`. La commande à lancer est `curl http://localhost : 8181 /ords/hr/employees/ | jq` — la même sortie que celle montrée en début d'article. ###### Et qu'en est-il du catalogue OpenAPI {#and-what-about-the-openapi-catalog} Retournez dans votre navigateur et accédez à nouveau à `http://localhost:` 8181`/ords/hr/open-api-catalog/`. Cette fois, vous verrez que vous avez un élément appelé `EMPLOYEES`. Si vous voulez obtenir la description de cette *ressource*, la page `http://localhost:` 8181`/ords/hr/open-api-catalog/employees/` peut être visitée pour obtenir par exemple la liste des champs exposés. Cette page s'appelle l'**Object Metadata** ([documentation](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.4/aelig/developing-REST-applications.html#GUID-B870CF7E-4A19-4646-ACB4-84CC9FD5967E)) Créons une nouvelle vue pour le plaisir : * Lancez `docker exec -it ` oracle-db ` sqlplus sys/admin@` ORCLPDB1 ` as sysdba` puis * Dans la console SQL, lancez `GRANT SELECT ON SYSTEM.DEPARTMENTS TO HR;` suivi de * `CREATE VIEW HR.DEPARTMENTS AS SELECT DEPARTMENT_ID, DEPARTMENT_NAME, MANAGER_ID, LOCATION_ID FROM SYSTEM.DEPARTMENTS;` et * Passez dans l'interface Oracle SQL Developer, rafraîchissez la liste des vues, faites un clic droit sur la nouvelle vue `departments` Maintenant, en rafraîchissant à nouveau `http://localhost:` 8181`/ords/hr/open-api-catalog/`, vous verrez que vous avez désormais un deuxième élément appelé `DEPARTMENTS`. > Screenshot — http\://localhost:8181/ords/hr/open-api-catalog/ > > Accès au metadata-catalog ##### Travailler avec REST {#working-with-rest} Rendez-vous sur `http://localhost:` 8181`/ords/hr/_sdw/?nav=rest-workshop` ou, depuis le menu hamburger, cliquez sur l'élément `REST`. > Screenshot — http\://localhost:8181/ords/hr/\_sdw/?nav=rest-workshop > > Dashboard REST ### Utiliser les options de pagination, de filtrage et de tri dans la querystring (facultatif — passez si l'endpoint par défaut suffit) {#using-paging-filtering-and-ordering-options-on-the-querystring-optional--skip-if-the-default-endpoint-is-enough} Lors de l'accès à un endpoint (comme `http://localhost:` 8181`/ords/hr/employees/`), nous pouvons manipuler l'URL pour ajouter des paramètres de pagination, de filtrage ou de tri. On parle de **JSON QBE**, pour JSON query-by-example. Voyez la documentation officielle : #### Pagination {#pagination} > [Doc](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.4/aelig/developing-REST-applications.html#GUID-6B5B51E6-0F35-4FB6-B271-FCC31E835347) Sauf configuration spécifique, ORDS utilise la pagination, c'est-à-dire qu'il limite la liste des enregistrements à 25 rows. Donc, si vous avez plus de 25 employés, l'endpoint `http://localhost:` 8181`/ords/hr/employees/` n'en retournera que les 25 premiers. En accédant à une page « complète » comme `http://localhost:` 8181`/ords/hr/employees/`, nous ne recevrons en fait qu'un nombre précis d'enregistrements (selon la configuration d'ORDS). À la fin de la réponse JSON, il y aura des liens de navigation : > Screenshot — http\://localhost:8181/ords/hr/employees/ > > Pagination Comme vous le voyez sur l'image, la réponse JSON fournit une liste d'enregistrements (dans un tableau nommé `items`) puis quelques propriétés comme `hasMore` (true/false), `limit` c'est-à-dire le nombre de rows à chaque appel, `offset` qui est la « page » (à 0 les 25 premières rows sont affichées, à 1 les rows 26 à 50, ...), `count` qui est le nombre de rows dans la réponse. Donc, tant que `hasMore` vaut `true`, il reste des enregistrements à récupérer avec une requête suivante. Il y a deux paramètres pour contrôler la pagination des résultats : `offset` et `limit`. Nous pouvons donc lancer plusieurs requêtes comme `http://localhost:` 8181`/ords/hr/employees/?offset=25`, `http://localhost:` 8181`/ords/hr/employees/?offset=50` et ainsi de suite. Nous pouvons définir le nombre d'enregistrements par page avec le paramètre `limit` de la querystring : `http://localhost:` 8181`/ords/hr/employees/?limit=100`. > **Note:** > > La documentation officielle déconseille fortement de supprimer la limite (et donc de demander tous les enregistrements d'un coup). C'est pourquoi il n'existe aucun moyen de la supprimer. Si vous voulez vraiment obtenir la liste complète, essayez avec un nombre très élevé comme `limit=1000000` (un million). #### Filtrage {#filtering} La syntaxe générale est `/?q={"column":{"$eq":"value"}}`. ##### Supérieur à {#greater-than} Par exemple, qui gagne plus de 20 000 € de salaire ? `http://localhost:` 8181`/ords/hr/employees/?q={"salary":{"$gt":20000}}` appliquera un filtre sur `salary > 20000`. > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"salary":{"$gt":20000}} > > Qui gagne plus de 20k ##### Égal {#equal} Pour trouver tous les employés appelés `Steven` : `http://localhost:` 8181`/ords/hr/employees/?q={"first_name":{"$eq":"Steven"}}` > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"first\_name":{"$eq":"Steven"}} > > Steven ##### Instring / contains / like {#instring--contains--like} Les employés ayant le motif `alex` dans leur prénom : `http://localhost:` 8181`/ords/hr/employees/?q={"first_name":{"$instr":"alex"}}` (correspondra par exemple à `Alexander` ou `Alexis`). > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"first\_name":{"$instr":"alex"}} > > Contient Alex Qui travaille dans l'ICT ? Ici, c'est l'opérateur like qu'il faut utiliser : `http://localhost:` 8181`/ords/hr/employees/?q={"job_id":{"$like":"IT_%"}}` (`IT_%` signifie *commence par*) > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"job\_id":{"$like":"IT\_%"}} > > Qui travaille pour l'IT ##### Filtrage complexe {#complex-filtering} Nous pouvons aussi utiliser AND comme dans cet exemple : `http://localhost:` 8181`/ords/hr/employees/?q={"first_name":{"$instr":"alex"},"salary":{"$gt":5000}}`, c'est-à-dire récupérer toutes les personnes ayant `alex` dans leur prénom et gagnant plus de 5 000 € > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"first\_name":{"$instr":"alex"},"salary":{"$gt":5000}} > > Contient Alex et gagne plus de 5 000 > **Utiliser le filtrage complexe:** > > L'URL suivante `http://localhost:` 8181`/ords/hr/employees/?q={"job_id":{"$like":"%CLERK"},"salary":{"$gt":2899},"hire_date":{"$gt":{"$date":"2016-12-31T12:59:59Z"}}}` retournera tous les employés qui : > > * travaillent comme clerk (`job_id` se terminant par le mot `CLERK`), > * ont un salaire supérieur à 2 899 € et > * ont été engagés à partir du 1er janvier 2017. > > > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"job\_id":{"$like":"%CLERK"},"salary":{"$gt":2899},"hire\_date":{"$gt":{"$date":"2016-12-31T12:59:59Z"}}} > > > > Utiliser une combinaison de filtres #### Tri {#sorting} La syntaxe générale est `/?q={"$orderby":{"fieldname1":"asc","fieldname2":"desc"}}`. Pour trier sur le prénom en desc puis sur le salaire (le plus élevé en premier) : `http://localhost:` 8181`/ords/hr/employees/?q={"$orderby":{"first_name":"desc","salary":"desc"}}`. > Screenshot — http\://localhost:8181/ords/hr/employees/?q={"$orderby":{"first\_name":"desc","salary":"desc"}} > > Tri sur le prénom et le salaire DESC ### Swagger {#swagger} ORDS peut générer un fichier `openapi.json` à utiliser avec Swagger. Pour en savoir plus : [Manage & Monitor Oracle Database with REST APIs](https://www.thatjeffsmith.com/archive/2022/08/manage-monitor-your-oracle-database-with-rest-apis/) ## Pour aller plus loin {#further-reading} * [ORDS best practices topics (www.oracle.com)](https://www.oracle.com/database/technologies/appdev/rest/best-practices/) * [Installation, Configuration, and Development Guide (docs.oracle.com)](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.4/aelig/toc.htm#GUID-A1CD111F-724B-4E91-8202-FA899EE521F1) * [Blog de Jeff Smith - Articles sur ORDS](https://www.thatjeffsmith.com/archive/tag/ords/) * [Adding HTTP(S) Access Logs for ORDS Standalone](https://www.thatjeffsmith.com/archive/2022/09/adding-https-access-logs-to-ords-standalone/)