====== GLPI - Utiliser l'API REST de GLPI avec Postman======
===== Présentation =====
vous allez utiliser différents outils pour découvrir l'utilisation de l'API de GLPI :
* Postman : c'est un outil utile lorsqu'un site Web de développeur d'API n'est pas disponible tout en offrant la possibilité d'enregistrer, d'organiser et de réutiliser facilement les API.
* Python
===== Utiliser Postman pour effectuer des appels d'API au simulateur d'API =====
==== Installation de Postman sur votre ordinateur ====
* le fichier d'installation Windows est dans le dossier Classe
* site de téléchargement : https://www.postman.com/downloads/
Après installation du logiciel il n'est pas nécessaire de se créer un compte.
Cliquez sur le lien **Skip an go to the app** :
{{ :si7:configuration:postman_01.png?500 |}}
==== 1ère requête sans authentification====
- Dans la fenêtre principale à côté de l'onglet **Overview**, cliquez sur l'icône plus **"+"** pour créer une **requête sans titre**. Par défaut, il s'agit d'une requête **GET**.
- Cliquez sur la flèche vers le bas en regard de **GET** pour afficher les différentes opérations d'API, y compris GET, POST et DELETE. Laissez la sélection sur **GET**. Cliquez sur la flèche vers le haut en regard de **GET** pour fermer la liste.
- Entrez l'URL suivante de la demande dans le champ Request URL et cliquez sur **Send** : [[http://10.xxx.xxx.xxx/glpi/apirest.php/]]
{{ :si7:configuration:postman_02.png |}}
Pour vérifier que la demande d'API a réussi regardez le code Status :
* il indique **200 OK** ;
* la section **Body** permet de voir la réponse qui est **Pretty** et **HTML** : vous avez le contenu d'une page HTML qui est la documentation sur l'API de GLPI ;
==== Accès à la documentation de l'API====
Saisissez l'URL de l'API dans un navigateur pour accéder à la documentation de l'API :
* [[http://10.xxx.xxx.xxx/glpi/apirest.php/]]
{{ :si7:configuration:postman_03.png |}}
==== Requête pour obtenir la liste des entités accessibles à un utilisateur====
Pour utiliser une API, il est indispensable de s'appuyer sur la documentation de celle-ci.
En consultant l'API de GLPI vous pouvez visualiser qu'il y a une requêter **GET** appelé **Get my entities** qui donne les informations suivantes :
^ Documentation ^ Commentaires ^
| __**Get my entities**__| nom de la requête
* **URL** : apirest.php/getMyEntities/
* **Description**: Return all the possible entities of the current logged user (and for current active profile).
* **Method**: GET
* **Parameters** : (Headers)
* //Session-Token//: session var provided by **initSession** endpoint. Mandatory.
* //App-Token//: authorization string provided by the GLPI API configuration. Optional.
* **Parameters**: (query string)
* //is_recursive// (default: false): Also display sub entities of the active entity. Optionnal
* **Returns**:
* 200 (OK) with an array of all entities (with id and name).
* 400 (Bad Request) with a message indicating an error in input parameter.
Il est nécessaire de renseigner des paramètres dans l'entête (**Headers**) :
* d'un jeton de session (**Session-Token**) qui vous devrez obtenir au préalable avec une requête **initSession**
* d'un jeton d'application (**App-Token**) qui a été créé pour vous permettre d'utiliser l'API de GLPI. Demandez à l'enseignant de vous communiquer cet **App-Token**.
Vous pouvez indiquer des paramètres dans l'URL (query string) :
* le paramètre //is_recursive// (par défaut à false) est facultatif et sera à indiquer sous la forme d'un couple nom=valeur. Si vous indiquez ce paramètre il s'écrira **is_recursive=true**.
==== Requête pour obtenir un jeton de session====
Voici la documentation de l'API de GLPI à propos de la requête **Init session** :
__**Init session**__
* **URL**: apirest.php/initSession/
* **Description**: Request a session token to uses other API endpoints.
* **Method**: GET
* **Parameters**: (Headers)
* //App-Token//: authorization string provided by the GLPI API configuration. Optional.
* a couple //login & password//: 2 parameters to login with user authentication. You should pass this 2 parameters in http basic auth. It consists in a Base64 string with login and password separated by ":" A valid Authorization header is:
* "Authorization: Basic base64({login}:{password})"
* OR
* an //user_token// defined in User Preference (See 'Remote access key') You should pass this parameter in 'Authorization' HTTP header. A valid Authorization header is:
* "Authorization: user_token q56hqkniwot8wntb3z1qarka5atf365taaa2uyjrn"
* **Parameters**: (query string)
* //get_full_session// (default: false): Get the full session, useful if you want to login and access session data in one request.
* **Returns**:
* 200 (OK) with the session_token string.
* 400 (Bad Request) with a message indicating an error in input parameter.
* 401 (UNAUTHORIZED)
Il est nécessaire de renseigner des paramètres dans l'entête (**Headers**) :
* le jeton d'application (**App-Token**) qui a été créé pour vous permettre d'utiliser l'API de GLPI. Demandez à l'enseignant de vous communiquer cet **App-Token**.
* une authentification soit par un couple de login /mot de passe soit en utilisant un jeton d'utilisateur (//user_token//). C'est cette deuxième méthode que vous allez utiliser.
=== Obtenir un jeton d'application (App-Token)===
Demandez à l'enseignant de vous communiquer cet **App-Token** pour l'API de GLPI.
=== Obtenir un jeton d'utilisateur (user_token)===
Pour obtenir un jeton d'accès pour votre compte GLPI :
* **connectez-vous** à GLPI ;
* Accédez aux **préférences** de votre compte : cliquez sur votre nom de compte en haut et à droite ;
* Dans la rubrique d'**accès distant**, faite une demande **Regénérer** puis **Sauvegarder** pour avoir un jeton d'API ;
* **copier** la valeur de votre clé d'API privée.
{{ :si7:configuration:postman_04.png |{{ :si7:configuration:postman_03.png?500 |}}
=== Créer la requête avec Postman ===
- Dans la fenêtre principale, cliquez sur l'icône plus **"+"** pour créer une requête sans titre.
- Gardez le type de requête GET ;
- Entrez l'URL suivante de la demande dans le champ Request URL : [[http://10.xxx.xxx.xxx/glpi/apirest.php/initSession]]
- Cliquez sur l'onglet **Authorization** et choisissez dans la liste déroulante **API Key**
- Dans le champ **Key** saisissez **user_token** ;
- Dans le champ **Value** collez la valeur du jeton d'API que vous avez généré pour votre compte et que vous avez copiée ;
- Dans le champ **Add to** sélectionnez dans la liste déroulante **Query Params**
{{ :si7:configuration:postman_05.png |}}
- Cliquez sur l'onglet **Headers** pour saisir la clé d'application (App-Token) qui vous a été communiquée par l'enseignant ;
- Dans le champ **Key** saisissez **App-Token** ;
- Dans le champ **Value** collez la valeur de la clé d'application (App-Token) qui vous a été communiquée par l'enseignant ;
{{ :si7:configuration:postman_06.png |}}
En cliquant sur le lien **6 Hidden** vous pouvez visualiser tous les champs d'en-tête transmis dans la requête d'API en HTTP.
{{ :si7:configuration:postman_07.png |}}
=== Lancer la requête ===
- Cliquez sur **Send** ;
{{ :si7:configuration:postman_08.png |}}
Pour vérifier que la demande d'API a réussi regardez le code Status :
* il indique **200 OK** ;
* la section **Body** permet de voir la réponse qui est **Pretty** et **JSON** : vous avez le jeton de session au format JSON.
==== Créer la requête pour obtenir la liste des entités accessibles à un utilisateur ====
Vous avez maintenant toutes les informations pour obtenir la liste des entités accessibles à un utilisateur :
* le jeton de session **Session-Token** ;
* le jeton d'application **App-Token**.
- Dans la fenêtre principale, cliquez sur l'icône plus **"+"** pour créer une requête sans titre.
- Gardez le type de requête GET ;
- Entrez l'URL suivante de la demande dans le champ **Request URL** : [[http://10.xxx.xxx.xxx/glpi/apirest.php/getMyEntities/]]
- Cliquez sur l'onglet **Headers** et saisissez les deux paramètres suivants :
- le paramètre **App-Token** avec la valeur communiquée par l'enseignant ;
- le paramètre **Session-Token** avec la valeur que vous avez obtenue ave la requête **initSession** ;
{{ :si7:configuration:postman_09.png |}}
- Cliquez sur l'onglet **Params** et saisissez le paramètre facultatif suivant pour visualiser en plus des l'entités les sous entités :
- le paramètre **is_recursive** avec la valeur **true** ;
{{ :si7:configuration:postman_10.png |}}
- Lancer la requête en cliquant sur **Send** ;
Pour vérifier que la demande d'API a réussi regardez le code Status :
* il indique **200 OK** ;
* la section **Body** permet de voir la réponse qui est **Pretty** et **JSON** : vous avez la lise des entités et des sous-entités avec leur identifiant.
{{ :si7:configuration:postman_11.png |}}
**Travail à faire :**
En vous aidant de la documentation de l'API de GLPI, **créez avec Postman** une requête pour afficher les informations sur votre ordinateur renseignées dans GLPI.
Vous aurez besoin :
* de consulter la documentation sur la requête **Get an item** ;
* du type d'élément (itemtype) : **Computer**
* de l'identifiant de votre ordinateur (**id**) : pour obtenir cet ID depuis GLPI, sélectionner votre ordinateur et vous devriez visualiser dans l'url son **id**.
L'URL de la requête **Get an item** est de la forme : **apirest.php/:itemtype/:id**.
Cela signifie que l'URL de votre requête pour l'ordinateur dont l'ID est 24 doit être : **apirest.php/Computer/24**
**Information** : Les types d'équipement sont les suivants : Computer, NetworkEquipment, Peripheral, Phone, Printer
==== Retour Activité A8 ====
* [[glpi_gestionconfig_00|A8 - La gestion des configurations avec GLPI]]