Exemple: Autorisation OAuth 2.0
Cet exemple vous montre comment appeler un service Web REST-style qui requiert une autorisation OAuth 2.0. L’application client est un mappage MapForce qui récupérera des événements de calendrier utilisant l’API Calendrier de Google (https://developers.google.com/calendar/). Pour être simple, la tâche liée au fichier .mfx récupérera l’information de calendrier « as is » et produira juste un résultat JSON brut sans autre traitement.
Exigences préalables :
•MapForce Enterprise Edition
•Pour suivre cet exemple étape par étape, vous devez avoir un compte Google. Si vous voulez appeler un autre service Web, demandez des identifiants OAuth 2.0 de votre fournisseur de service Web et utilisez-les à la place dans les instructions ci-dessous.
Obtenir des identifiants OAuth 2.0
Si vous avez déjà des identifiants OAuth 2.0 requis pour accéder au service Web, vous pouvez ignorer cette étape. Autrement, les instructions exactes pour les obtenir dépendent du fournisseur du service Web que votre mappage appellera. Pour appeler l’API Calendrier de Google comme dans l’exemple, suivez les étapes suivantes :
1.Connexion à la Console d’API de Google (https://console.developers.google.com/).
2.Créer un nouveau projet.
3.Cliquer sur OAuth consent screen.
4.Sélectionnez Externe en tant que type d’utilisateur, sauf si vous avez un compte G Suite qui vous permet d’allouer un accès API uniquement à des utilisateurs au sein de votre organisation.
5.Saisissez « mapforce-demo » en tant que nom d’application et enregistrez les paramètres.
6.Cliquez sur Créer identifiants, puis sélectionnez OAuth Client ID.
7.Saisissez Desktop app en tant que type d’application et « MapForce Client » en tant que nom client.
8.Cliquez sur Créer. L’ID client est créé et devient disponible sur la page Identifiants.
9.Cliquez sur 
pour télécharger les détails d’autorisation pour OAuth 2.0 en tant que fichier JSON.
Vous avez désormais obtenu les détails d’autorisation OAuth 2.0 depuis la Console d’API de Google, notamment :
1.Point de terminaison d’autorisation
2.Point de terminaison de jeton
3.ID Client
4.Secret client
Activer l’API Calendrier de Google
Pour accepter des appels de clients, l’API Calendrier de Google utilisée dans cet exemple doit être acceptée. Dans la Console d’API de Google, cliquez sur Library, recherchez l’API Calendrier de Google et activez-la :
Dans cet exemple, nous allons appeler la méthode de liste de l’entité Événements. Vous pouvez trouver une référence détaillée pour cette méthode d’API sur https://developers.google.com/calendar/v3/reference/events/list. Pour l’instant, veuillez noter les points importants suivants :
1.Tel que mentionné dans la documentation, la méthode doit être appelée en envoyant une requête GET à https://www.googleapis.com/calendar/v3/calendars/calendarId/events, où calendarId est l’identifiant pour un calendrier Google. Le paramètre de requête calendarId sera configuré depuis MapForce lors d’une étape suivante.
2.Appeler une méthode d’API requiert au moins l’une des deux étendues suivantes :
•https://www.googleapis.com/auth/calendar.readonly
•https://www.googleapis.com/auth/calendar
•https://www.googleapis.com/auth/calendar.events.readonly
•https://www.googleapis.com/auth/calendar.events
Au cours de la procédure d’autorisation pour OAuth 2, votre mappage devra fournir l’une des étendues ci-dessus —ceci sera également configuré à une étape suivante. À des fins d’exemple, la première étendue « read-only » sera suffisante.
Demander un jeton d’autorisation
Pour prévisualiser le mappage dans MapForce, vous devrez ajouter les détails d’autorisation pour OAuth 2.0 au mappage et demander un jeton d’autorisation, tel qu’illustré ci-dessous.
1.Dans MapForce, cliquez avec la touche de droite sur une zone vide du mappage, et sélectionnez Ouvrir Manager d’identifiants depuis le menu contextuel.
2.Cliquez sur 
Ajouter identifiant.
3.Saisissez un nom (« my.oauth », dans cet exemple), et sélectionnez OAuth 2 comme type.
4.Remplissez les zones de texte Point de terminaison d’autorisation, Point de terminaison jeton, ID client, Secret client avec les valeurs correspondantes depuis le fichier JSON téléchargé précédemment.
5.Saisissez https://www.googleapis.com/auth/calendar.readonly dans la zone de texte étendue.
6.Laissez tous les autres paramètres tel quel.
7.Cliquez sur Demander jeton d’accès pour obtenir le jeton depuis le serveur d’autorisation (dans cet exemple, Google). Une fenêtre de navigation s’ouvre demandant de vous connecter à votre compte Google.
8.Connexion à votre compte Google. Puisque vous n’avez pas encore soumis de requête de vérification d’appli à Google, la page suivante apparaît.
9.Cliquez sur Avancé, puis cliquez sur Aller à mapforce-demo (unsafe).
10.Cliquez sur Autoriser. Une confirmation est désormais affichée dans le navigateur.
MapForce vous informe également que le code d’autorisation OAuth 2.0 a été récupéré avec succès.
11.Cliquez sur OK. Notez que les champs Jeton d’accès et Jeton d’actualisation ont maintenant été complétés avec des données.
12.Enregistrez le mappage en tant que GetCalendarEvents.mfd.
Dans ce tutoriel, la case à cocher Save encrypted in MFD file est sélectionnée dans la boîte de dialogue Éditer identifiants. Pour cette raison, les champs sensibles Secret client, Jeton d’autorisation et Jeton d’actualisation seront enregistrés sous forme encryptée dans le fichier de création du mappage (.mfd) quand vous enregistrez le mappage. |
Sachez que le jeton d’autorisation expirera après une période. Lorsque cela arrive, vous ne pourrez plus exécuter le mappage (à cette étape, aucun mappage n’a été conçu, mais il sera créé à une étape suivante). À chaque fois que vous devez obtenir un nouveau code d’autorisation manuellement, cliquez sur Demander jeton d’accès et suivez les étapes décrites ci-dessus.
Concevoir l’appel de service Web
Le mappage GetCalendarEvents.mfd créé ne fait rien pour le moment. La chose qu’il contient sont les identifiants OAuth 2.0 qui permettent l’accès à l’API Calendrier de Google.
Concevons maintenant le service Web dans MapForce, comme suit :
1.Ouvrez le mappage GetCalendarEvents.mfd.
2.Dans le menu Insérer, cliquez sur Fonction du service Web. La boîte de dialogue « Web Service Call Settings » apparaît.
3.Cliquez sur Manual.
4.Sélectionnez GET comme méthode de requête et entrez l’URL dans le service Web mentionné dans l’étape précédente : https://www.googleapis.com/calendar/v3/calendars/calendarId/events.
5.Puisque calendarId est un espace réservé qui doit être alloué en tant que paramètre, encadrez-le à l’intérieur des accolades, tel qu’affiché ci-dessous.
6.Cliquez sur le bouton 
Ajouter paramètre et définissez les détails de paramètre comme suit :
Dans la configuration ci-dessus, le style du « Template » permet de remplacer la partie URL encadrée à l’intérieur des accolades avec la valeur paramètre au moment de l’exécution. « Mappable » signifie que vous pouvez fournir la valeur depuis le mappage (par exemple, depuis un paramètre d’entrée, ou éventuellement un paramètre de constante). Enfin, le paramètre a été marqué en tant que « requis » parce que l’appel API ne peut pas être réalisé sans. Pour de plus amples informations, voir Définir paramètres du service Web.
7.Cliquez sur le bouton Éditer adjacent aux paramètres de sécurité HTTP.
8.Dans la boîte de dialogue « Paramètres de sécurité HTTP », sélectionnez Use Credential et sélectionnez l’enregistrement d’identification « my.oauth » configuré précédemment.
Le service Web configuré jusqu’à cette étape a l’apparence suivante sur le mappage :
Vous pouvez maintenant terminer le design en effectuant les étapes suivantes :
1.Dans le menu Insérer, cliquez sur Insert Input, et configurez les composants comme suit :
La composante d’entrée, telle qu’illustrée ci-dessus, est dotée de la valeur « primary » au moment du design. Selon la documentation API, la valeur « primary » signale au serveur API d’accéder au Calendrier principal de Google de l’utilisateur actuellement connecté. Notez que la valeur est une valeur design-time et s’applique uniquement lorsque vous prévisualisez le mappage dans MapForce. Lorsque le mappage est exécuté dans un environnement de serveur, vous allez devoir fournir la valeur désirée au moment de l’exécution.
2.Glissez la fonction decode-mime-entity depuis la fenêtre Libraries dans l’espace de mappage. Cette fonction convertit la partie MIME brute reçue du serveur en un string.
3.Dans le menu Insérer, cliquez sur Insérer Résultat, et ajoutez une composante de résultat simple dont le rôle est de générer le résultat en tant que string normal.
4.Établissez les connexions entre les composantes, tel qu’illustré ci-dessous.
Ceci conclut la partie design dans MapForce.
Tester l’exécution de mappage
Pour tester l’exécution de mappage dans MapForce, cliquez sur l’onglet Résultats et notez le résultat affiché dans la fenêtre des Messages.
Si vous recevez une erreur d’autorisation telle que « non autorisé (401) », notez les conseils relatifs à la résolution des problèmes suivants :
1.Assurez-vous que l’API Calendrier de Google est activée, voir Activer l’Activer l’API Calendrier de Google.
2.Demander un nouveau jeton d’autorisation, dans le cas où le jeton d’accès précédemment obtenu est venu à expiration.
3.Revérifier que tous les détails OAuth 2.0 ont été saisis correctement dans MapForce.
Si vous avez réussi l’exécution et l'autorisation OAuth 2.0 de MapForce, le résultat de mappage devrait normalement être similaire à celui ci-dessous :
Si vous avez utilisé un compte Google qui ne contient pas d’événements de calendrier comme dans cet exemple, l’array « items » sera vide en affichant la réponse. Par contre, si vous ajoutez un événement à votre calendrier Google et exécutez le mappage une nouvelle fois, le résultat reflétera cet ajout. En note rapide, vous pouvez aussi extraire des événements d’un autre calendrier que le calendrier par défaut. Par exemple, vous pouvez extraire des données depuis un calendrier public comme dans celui des « Jours fériés aux États-Unis d’Amérique ». Pour ce faire, définissez la valeur du paramètre de calendarId à en.usa#holiday@group.v.calendar.google.com au lieu de primary.
Pour toute information sur d’autres paramètres que vous pouvez ajouter à l’appel API, consultez la documentation de la méthode API au lien https://developers.google.com/calendar/v3/reference/events/list.