Commit 13396154 authored by Bertrand Gauthier's avatar Bertrand Gauthier
Browse files

Amélioration/correction de la doc

parent 7d116f13
Pipeline #12944 passed with stage
in 13 seconds
Installation du web service `sygal-import-ws`
=============================================
Applicatif
----------
......@@ -49,7 +48,6 @@ créés par le script `Dockerfile.sh` :
NB: Vérifiez dans le script `Dockerfile.sh` que vous venez de lancer mais normalement
`APACHE_CONF_DIR=/etc/apache2` et `PHP_CONF_DIR=/etc/php/7.0`.
### Installation d'une version précise du WS
Normalement, vous ne devez installer que les versions officielles du WS, c'est à dire les versions taguées, du genre `2.0.0`
......@@ -67,7 +65,6 @@ sur votre serveur :
git checkout --force 2.0.0 && bash install.sh
```
### Fichier "users.htpasswd"
Ce fichier contient les utilisateurs/mot de passe autorisés à interroger le WS au regard de l'authentification HTTP Basic.
......@@ -127,27 +124,53 @@ composer development-disable
```
Base de données
---------------
Le WS interroge des tables que vous allez devoir créer dans la base de données de votre logiciel de scolarité (Apogée ou Physalis),
ou autre part si c'est possible, à vous de voir.
### Création des tables et vues sources
Le WS puise dans des tables `SYGAL_*` mises à jour périodiquement à partir de vues `V_SYGAL_*`. Vous devez créer
ces tables et vues dans la base de données de votre logiciel de scolarité (Apogée ou Physalis) ou autre part si c'est
possible, à vous de voir.
Le répertoire [`dist/SQL`](dist/SQL) contient ceci :
- Un script `01-tables.sql` pour créer les tables qui contiendront les données retournées par le web service.
- Un dossier `apogee` concernant les établissements ayant Apogée.
- Un dossier `physalis` concernant les établissements ayant Physalis (Cocktail).
Quelque soit votre logiciel de scolarité, utilisez le script `01-tables.sql` pour créer les tables qui contiendront
bientôt les données retournées par le web service.
Quelque soit votre logiciel de scolarité, utilisez le script `01-tables.sql` pour créer les tables `SYGAL_*`.
Prenons maintenant l'exemple d'Apogée. Le répertoire `apogee` contient 2 scripts SQL :
- `01-vues-apogee-communes.sql` : script de création des vues communes à tous les établissements ayant ce logiciel
de scolarité, ne nécessitant aucune personnalisation.
- `02-vues-apogee-etab.sql` : script de création des vues contenant des données propres à votre établissement
en particulier, nécessitant donc une personnalisation de votre part.
- `01-vues-apogee-communes.sql` : script de création des vues `V_SYGAL_*` communes à tous les établissements
ayant ce logiciel de scolarité, ne nécessitant aucune personnalisation.
- `02-vues-apogee-etab.sql` : script de création des vues `V_SYGAL_*` contenant des données propres à votre
établissement en particulier, nécessitant donc une personnalisation de votre part.
Prenez connaissance de ces scripts, personnalisez ceux qui le requierent puis lancez-vous/les pour créer les
tables/vues nécesssaires.
### Mise à jour périodique des tables sources
Le WS puise dans des tables `SYGAL_*` qui doivent être mises à jour périodiquement à partir des vues `V_SYGAL_*`.
Il s'agit de CRONer l'exécution de la commande chargée de faire cette mise à jour.
- Créez sur le serveur du web service le fichier de config CRON `/etc/cron.d/sygal-import-ws-cron`
identique au fichier [dist/cron/sygal-import-ws-cron](dist/cron/sygal-import-ws-cron) fourni
puis adaptez si nécessaire son contenu :
- `APP_DIR=` : chemin vers le répertoire d'installation du web service.
- `LOG_FILE=` : chemin vers le fichier de log.
- `*/5` : périodicité d'exécution du script, initialisée à "toutes les 5 minutes".
- Testez que CRON sera en mesure de lancer le script d'après le contenu du fichier de config.
Exemple :
```bash
APP_DIR=/var/www/sygal-import-ws
/usr/bin/php ${APP_DIR}/public/index.php update-service-tables
```
- Vérifiez ensuite que le contenu de la table `SYGAL_INDIVIDU` (par exemple) a bien été mis à jour à l'instant
grâce à la colonne `inserted_on`.
Réseau
......@@ -159,7 +182,6 @@ ESUP-SyGAL.
Il est conseillé de restreindre cette autorisation à cette seule adresse IP d'origine.
Test
----
......
# sygal-import-ws
sygal-import-ws
===============
Que fait *sygal-import-ws* ?
----------------------------
## Que fait *sygal-import-ws* ?
*sygal-import-ws* est un web service (une API REST) qui interroge les données présentes dans un SI (via des vues
et des tables en base de données) et les met à disposition pour leur lecture via des requêtes GET.
*sygal-import-ws* est un web service (ws) qui interroge les données présentes dans un SI (via des vues en base de données)
et les met à disposition pour leur lecture via des requêtes GET.
## Outils employés
*sygal-import-ws* repose sur l'utilisation de :
- [Apigility](https://apigility.org/) pour la fourniture du ws ;
- [Doctrine](http://www.doctrine-project.org/) pour la gestion de la partie BDD (notamment des schémas des tables).
## Installation
Installation
------------
Cf. [`INSTALL.md`](INSTALL.md).
## Lancement du web service *pour le dévelopement*
Lancement du web service *pour le dévelopement*
-----------------------------------------------
### Solution 1 : le serveur interne PHP
......@@ -50,7 +46,8 @@ Par exemple, `0.0.0.0:443->8443/tcp` indique que le ws est accessible sur la mac
à l'adresse `https://localhost:8443`.
## Les services fournis
Les services fournis
--------------------
Chaque vue en base de données peut être interrogée via un service dédié :
- `/structure`
......@@ -68,15 +65,19 @@ Chaque vue en base de données peut être interrogée via un service dédié :
- `/titre-acces`
- `/variable`
Il y a aussi un service `/version` permettant de connaître le numéro de version du web service (ex : '1.3.7').
## Versions
Versions
--------
L'API existe en plusieurs versions, veillez à spécifier la version correcte dans l'URL.
Exemple pour la version 1 : `https://localhost:8443/v1/variable`.
Exemple pour la version 2 : `https://localhost:8443/v2/variable`.
## Interrogation avec `curl`
Interrogation avec `curl`
-------------------------
Exemple :
```bash
......@@ -107,15 +108,10 @@ curl --insecure --header "Accept: application/json" --header "Authorization: Bas
```
## Remarques complémentaires
* Le web service ne répond qu'aux requêtes de type GET.
* Le web service retourne du json seulement.
Services acceptant un paramètre
-------------------------------
## Services acceptant un paramètre
Aucun service n'accepte de paramètre, sauf ceux qui suivent.
Aucun service n'accepte de paramètre GET, sauf ceux qui suivent.
### `/acteur`
......@@ -134,3 +130,14 @@ Exemple :
```bash
curl --insecure --header "Accept: application/json" --header "Authorization: Basic xxxxx" https://localhost:8443/v1/doctorant?these_id=13111
```
Ligne de commande
-----------------
La ligne de commande suivante permet de mettre à jour en base de données les tables `SYGAL_*` à partir des
vues `V_SYGAL_*` (ces tables sont les sources des données retournées par l'API) :
```bash
php public/index.php update-service-tables --verbose
```
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment