Une connexion WebService permet de se connecter à un WebService de type REST (pour lesquels les données sont accessibles via une seule URL) :
- Renvoyant des données au formats JSON ou XML
- Ayant un protocole d'identification Aucun, login/mot de passe, ou OAuth 2.0
Note
Lien vers la FAQ MyReport des connexions WebServices réussies par nos équipes : Lien vers la FAQ
Important
Il est important de bien lire la documentation du WebService pour comprendre comment s'y connecter.
Il est fortement conseillé de valider la connexion avec un outil externe comme postman ou insomnia avant de tenter la connexion dans MyReport Data.
Accès aux données
- URL d'accès aux données : Elle permet de définir le WebService auquel on souhaite accéder. On peut mettre dans cette URL tous les paramètres demandés par le WebService pour filtrer les données à récupérer.
Les paramètres
- Ils s'ajoutent à l'URL d'accès aux données.
- Chaque paramètre peut être passé au WebService soit en GET soit en POST soit en HEAD
Il est possible d'ajouter des paramètres variables ou statiques lors du paramétrage d'un WebService
Les paramètres variables sont des formules MyReport qui doivent renvoyer du texte.
Syntaxe : MyReport (... ) Exemple : MyReport ( DateEnTexte ( DateDernierETLOK ) )
Authentification
MyReport gère différents types d'authentification :
- Aucune : le WebService ne nécessite aucune authentification.
Login / Mot de passe : le WebService nécessite un couple login/Mot de passe (aussi appelé Credential) qui est passé dans l’entête de la requête HTTP(s).
Il existe deux modes Login / Mot de passe :
Login / Mot de passe :
- MyReport effectue d'abord un challenge HTTP (un premier appel au serveur sans authentification).
- Le serveur renvoi une erreur 401 avec l'entête
WWW-Authenticate: Basic realm="...." - MyReport effectue un second appel avec l'entête
Authorization: Basic ....
Basic Auth :
MyReport ne fait qu'un appel avec l'entête
Authorization: Basic ....Ce mode existe parce que certains serveurs ne respectent pas le protocole du challenge et ne mettent pas la bonne entête dans la réponse.
OAuth 2.0 : le WebService nécessite une authentification de type OAuth 2.0. Cette authentification utilise un système de Token à durée limitée.
Autorisation code : La récupération d'un Token se fait via une URL d'authentification et via une URL de récupération de Token.
- URL d'authentification : cette URL permet à l'utilisateur de s'authentifier. Cette étape n'est faite que lors de la configuration du modèle.
- URL de retour : cette URL est utilisée pour fournir à MyReport les informations d'authentification par le WebService. Cette dernière est possiblement à définir aussi dans la configuration du WebService. Si cette configuration n'est pas demandée par le WebService, il est conseillé de mettre l'URL "http://127.0.0.1".
- URL de récupération du Token : cette URL sert à récupérer le Token que MyReport doit fournir dans l'URL d'accès aux données. MyReport rajoute à cette URL les informations récupérées après l'appel à l'URL d'authentification.
- Fréquence d'actualisation du Token : ces paramètres permettent d'avoir toujours un Token valide en appelant l'URL de récupération du Token régulièrement.
Client Credentials : La récupération d'un Token se fait à l'aide d'une URL de récupération de Token. Il n'y a pas de phase d'authentification (Login / mot de passe). 3 paramètres sont obligatoires pour cette url :
- client_id : la valeur doit être renseignée
- client_secret: la valeur doit être renseignée
- scope : La valeur n'est pas obligatoire (cela dépend du WebService)
Délai d’exécution : Ce paramètre permet de définir quel est le temps maximum autorisé à un appel au WebService avant qu'il soit rejeté.
Important
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 WebService doit respecter la documentation du WebService: chaque WebService a ses propres règles de nommage, d'authentification et de structure des données retournées.
3 URLs sont à configurer pour la mise en place d'une authentification avec le protocole OAuth 2.0 - Autorisation Code:
URL d'authentification (nommée
{URLAuthentification})URL de retour (nommée
{URLRetour})URL de récupération des Tokens (nommée
{URLToken})
La plupart des WebServices ne font pas de contrôle sur l'URL de Retour. Si la documentation ne donne pas d'information dessus, il est conseillé de mettre ce champ à "http://127.0.0.1"
Procédure d'authentification OAuth2 dans MyReport pour les sources WebService
Cette procédure permet de récupérer l'AccessToken.
{URLAuthentification}?response_type=code&redirect_uri={URLRetour}
Récupération d'un code "code" {codeValue} basé sur un Login/Mot de passe demandé pendant la configuration de la connexion/modèle
{URLToken}?redirect_uri={URLRetour}&grant_type=authorization_code&code={CodeValue}
Récupération d'un RefreshToken "refresh_token" {RefreshTokenValue}
{URLToken}?redirect_uri={URLRetour}&grant_type=refresh_token&refresh_token={RefreshTokenValue}
Récupération d'un AccessToken "access_token" {AccessTokenValue}
Exploitation de l'AccessToken
MyReport appelle l'URL des données en ajoutant automatiquement le paramètre :
access_token={AccessTokenValue}Lors de l'ETL, on n'utilise que l' URL de récupération des Tokens pour avoir un nouveau AccessToken
Rafraîchissement de l'AccesToken
Le RefreshToken est stocké dans la configuration du modèle, et est actualisé par le Serveur en fonction de la fréquence configurée en rappelant l' URL de récupération des Tokens
