Les modèles WebServices

Généralités

Un modèle WebService permet de se connecter à :

Un WebService de type REST (pour lesquels données sont accessibles via une seule URL)
Renvoyant des données au formats JSON ou XML
Ayant un protocole d'identification login/password ou OAuth 2.0

Dans le cas d'un WebService exploitant le protocole d’authentification OAuth 2.0, MyReport ne gère pas le cas où à la demande d'un "Access Token" le WebService modifie le "Refresh Token".

La configuration d'une connexion à un WebService doit respecter la documentation du WebService : chaque WebService a ses propres règles de nommage, d'authentification, de pagination, et de structure des données retournées.

Note

Le rafraichissement des tokens pour les connexions webservice est vérifié tous les jours à 00h00 (ce qui entraine un chargement du projet)

Paramétrage

Accès aux données

Complément d’URL d'accès aux données : Il s’ajoute à l’url de la connexion WebService associée pour définir la connexion à un WebService.
L'URL finale est construite à partir de la concaténation de l'url de la connexion WebService avec complément d'url d'accès aux données.

Les paramètres

Ils s'ajoutent à l'URL d'accès aux données.
Ces paramètres sont consolidés avec ceux de la connexion WebService.
Lorsque des paramètres ont le même nom, ceux du modèle écrasent ceux de la connexion.

Pagination

MyReport gère plusieurs types de paginations :

Aucune : Le Webservice ne nécessite aucune pagination (toutes les données sont retournées lors d'un seul appel).
Numéro de page: Le Webservice nécessite un paramètre qui défini le numéro de la page demandée. Il est possible de choisir si le premier appel à besoin de ce paramètre.
Nombre d'éléments par page : Le Webservice nécessite de savoir à partir de quel élément il doit retourner des données. L'offset à définir est utilisé pour savoir à partir de quel élément la page doit commencer. A chaque appel, l'offset est augmenté de la valeur choisie. Il est aussi possible de choisir si l'offset doit être utilisé lors du premier appel, et avec quelle valeur.
URL suivante: Le Webservice fournit l'URL à appeler pour la prochaine page.
MyReport doit connaitre la propriété à lire pour récupérer l'URL des pages suivantes.
Attention
Si le nom de la propriété est mal saisi, il n'y aura pas d'erreur, si la propriété n'existe pas dans la réponse, cela signifie simplement que c'était la dernière page de données.
Le chemin d'accès à cette propriété n'est pas dépendant du nœud racine qui peux être sélectionné.
```
Exemple avec OData (API Microsoft Graph)
Nom de la propriété: @odata.nextLink
```

Récupération des enregistrements

Sélection du nœud racine

La sélection d'un nœud racine permet de filtrer le retour du WebService avec le tableau qui possède réellement les données utiles.

Exemple d'utilisation :
Le WebService retourne les données suivantes :
{
    'Version' : '5.0.0',
    'Author': 'Moi',
    'Page': '2',
    'Values' : [
        { 'Contact': 'toto' },
        { 'Contact': 'tata' }
    ]
}

* Si aucun nœud racine n'est sélectionné, MyReport va créer les champs tables suivants : "Version", "Author", "Page", "Values.Contact"
* Si le nœud racine "Values" est sélectionné, MyReport va créer les champs tables suivants : "Contact"

Généralités sur les décroisement des données Json

Lorsque la source de données contient des sous-tableaux, MyReport remonte un enregistrement pour chaque élément du sous-tableau.

Avertissement

Les sous-tableaux doivent avoir la même structure.

Exemple 1 : Exemple d'éléments imbriqués, et résultat remonté par MyReport

Json récupéré du webservice

[
  {
    'Contact': 'toto',
    'Mails': [
      {'Mail': 'toto@report-one.com'},
      {'Mail': 'toto_alias@report-one.com'}
    ]
  },
  {
    'Contact': 'tata',
    'Mails': [
      {'Mail': 'tata@report-one.com'}
     ]
  }
]

Tableau 8.1. Données dans MyReport :

Contact	Mails_Mail
toto	toto@report-one.com
toto	toto_alias@report-one.com
tata	tata@report-one.com

Exemple 2 : Exemple de Json ne pouvant pas être traité par MyReport ('tata' n'a pas de ligne 'Mail')

[
  {
    'Contact': 'toto',
    'Mails': [
      {
        'Mail': 'toto@report-one.com'
      }
    ]
  },
  {
    'Contact': 'tata',
    'Mails': []
  }
]

Cas particulier des tableaux de valeurs

Chaque élément d'un tableau de valeurs sera traduit par un champ lors du décroisement

exemple de JSON avec des tableaux de valeurs :

[{
  'a': '10',
  'b' : [['Albi', '53'], ['Lyon', '3']]
},
{
  'a': '11',
  'b' : [['Paris', '20']]
}]

Tableau 8.2. Données dans MyReport :

a	b_Champ1	b_Champ2
10	Albi	53
10	Lyon	3
11	Paris	20

Exemples de mise en place

Web Service "themoviedb" (Pagination par page)

Cet exemple va récupérer toutes les entreprises référencées par "themoviedb" qui dépendent de "sony".

Documentation de l'API : https://developers.themoviedb.org/3/getting-started/introduction

Ce Web Service utilise une clé d'api (à récupérer sur votre compte "themoviedb") pour identifier un utilisateur, et fonctionne sur un système de pages.

Voici le paramétrage à effectuer dans MyReport BE :

Connexion :
  * URL d'accès aux données : https://api.themoviedb.org/3
  * Paramètres :
    * api_key=XXXXXX
  * Type d'authentification : Aucun

Modèle :
  * Complément d'url : /search/company
  * Paramètres :
    * query=sony
  * Pagination : Page
    * Nom de l'Offset : page
    * Utilisation du paramètre de pagination au premier appel : coché

Génération des URL's associées :
https://api.themoviedb.org/3/search/company?api_key=XXXXX&query=sony&page=1
https://api.themoviedb.org/3/search/company?api_key=XXXXX&query=sony&page=2
https://api.themoviedb.org/3/search/company?api_key=XXXXX&query=sony&page=3...

Web Service MailJet (Login/MDP et Pagination via un nombre d'éléments par page)

Cet exemple va récupérer tous les contacts que l'utilisateur authentifié a ajouté à son service MailJet.

MailJet fournit un WebService avec une authentification basée sur un Login/MDP., et gère aussi la pagination.

La documentation de MailJet nous fournit les informations suivantes :

URL : https://api.mailjet.com/v3/REST/contact
Paramètres :
- Limit : définit combien de contacts doivent envoyés (Méthode : GET, valeur par défaut : 10, Valeur max : 1000)
- Offset : définit le premier contact devant être envoyé (Méthode : GET, valeur par défaut : non définit)
Complément : Le premier élément est identifié par l'Offset "0"

Pour avoir tous les contacts en un minimum d'appel, il nous faut donc faire les appels suivants :

https://api.mailjet.com/v3/REST/contact?Limit=1000
Renvoi les contacts "0" à "999"
https://api.mailjet.com/v3/REST/contact?Limit=1000&Offset=1000
Renvoi les contacts "1000" à "1999"
https://api.mailjet.com/v3/REST/contact?Limit=1000&Offset=2000
https://api.mailjet.com/v3/REST/contact?Limit=1000&Offset=3000
...

Voici le paramétrage à effectuer dans MyReport BE :

Connexion :
  * URL d'accès aux données : https://api.mailjet.com/v3/REST
  * Type d'authentification : Login / Mot de passe

Modèle :
  * Complément d'url : /contact
  * Paramètres :
    * Limit=1000
  * Pagination : Nombre d'éléments par page
    * Nom de l'Offset : Offset
    * Valeur de l'Offset : 1000
    * Utilisation du paramètre de pagination au premier appel : décoché

WebService Google Analytics (OAuth 2.0 et Pagination via un nombre d'éléments par page)

Etape préalable : L'administrateur du compte Google Analytics doit fournir les éléments permettant d'accéder à une vue

Récupération de l'identifiant de la vue
Cette information est disponible sur le site https://analytics.google.com, dans les paramètres de la vue
Donner accès au compte utilisateur
Cette action est à effectuer sur le site https://analytics.google.com, dans les paramètres de la vue
Récupération des identifiants de connexion ( client_id et client_secret )
Ces informations sont disponibles sur le site https://console.developers.google.com
Liste des opérations à effectuer
- Activer l'API "Google Analytics API"
- Renseigner les informations de "l'Écran d'autorisation OAuth"
- Créer un identifiant "ID client OAuth" avec un type d'application "Autre"

Paramétrage du modèle

URL d'accès aux données : https://www.googleapis.com/analytics/v3/data/ga

Tableau 8.3. Paramètres en GET:

ids=ga:[Identifiant de la vue]	Remplacer [Identifiant de la vue] par l'identifiant fourni par l'administrateur du compte Google Analytics
dimensions=ga:[Liste des dimensions]	La liste des dimensions, séparées par une virgule. Exemple pour récupérer la date de connexion et la région: date,region
metrics=ga:[Liste des indicateurs]	Liste des indicateurs, séparés par une virgule. Exemple pour récupérer le nombre de sessions : sessions
[Dates]	Définition de la période à analyser Exemple pour récupérer les données des 7 derniers jours : start-date=7daysAgo&end-date=today
max-results=[Nombre d'éléments dans une page]	Définition du nombre d'éléments à récupérer dans une page Exemple pour récupérer 1000 données par page : max-results=1000

Vous pouvez trouver de la documentation pour vous aider à construire cette URL sur les pages suivantes

https://ga-dev-tools.appspot.com/query-explorer/ : Constructeur d'URLs d'accès aux données
https://developers.google.com/analytics/devguides/reporting/core/dimsmets#mode=api : Documentation et métriques de Google Analytics.

Pagination :
- Type de pagination : Nombre d'éléments par page
- Nom de l'offset : start-index
- Méthode : GET
- Valeur de l'offset : La même valeur que le paramètre "max-results"
- Valeur initiale de l'offset : 1 (La documentation Google nous disant : "Result indexes are 1-based. That is, the first row is row 1, not row 0.".)
- Utiliser le paramètre de pagination au premier appel : non (dans ce WebService, les valeurs par défaut correspondent au premier appel que l'on veut faire)

Authentification :

Type d'authentification : OAuth2.0
Méthode : GET

URL d'authentification : https://accounts.google.com/o/oauth2/v2/auth?client_id=[IdentificationClient]&scope=https%3a%2f%2fwww.googleapis.com%2fauth%2fanalytics

client_id=[IdentificationClient]	Remplacer [IdentificationClient] par le "client_id" fourni par l’administrateur de l'API Google Analytics
scope=https%3a%2f%2fwww.googleapis.com%2fauth%2fanalytics	Paramètre permettant de définir quels sont les droits utilisés par l'URL d'accès aux données.

URL de retour :http://127.0.0.1:9099/

URL de récupération des Tokens : https://www.googleapis.com/oauth2/v4/token?client_id=[IdentificationClient]&client_secret=[ClientSecret]

client_id=[IdentificationClient]	Remplacer [IdentificationClient] par le "client_id" fourni par l’administrateur de l'API Google Analytics
client_secret=[ClientSecret]	Remplacer [ClientSecret] par la "secret_id" fournir par l'administrateur de l'API Google Analytics

Voici un exemple de paramétrage à effectuer dans MyReport BE :

Connexion :
  * URL d'accès aux données : https://www.googleapis.com/analytics/v3/data/ga
  * Type d'authentification : OAuth 2.0
  * URL d'authentification : https://accounts.google.com/o/oauth2/v2/auth
    * Paramètres :
      * client_id=*****
      * scope=https%3a%2f%2fwww.googleapis.com%2fauth%2fanalytics
  * URL de retour : http://127.0.0.1
  * URL de récupération des Tokens : https://www.googleapis.com/oauth2/v4/token
    * Paramètres :
      * client_id=*****
      * client_secret=*****
  * Fréquence d'actualisation : une fois par semaine

Modèle :
  * Complément d'url : {vide}
  * Paramètres :
    * ids=ga:*****
    * dimensions=ga:date,region
    * metrics=ga:sessions
    * start-date=7daysAgo
    * end-date=today
    * max-results=1000
  * Pagination : Nombre d'éléments par page
    * Nom de l'Offset : start-index
    * Valeur de l'Offset : 1000
    * Valeur initiale de l'offset de pagination : 1
    * Utilisation du paramètre de pagination au premier appel : coché

Précédent	Niveau supérieur	Suivant
	Sommaire

Les modèles WebServicesChapitre 8. Les WebServices