Altova MapForce Server 2024 Advanced Edition

Cet exemple vous montre comment appeler un service Web REST-style qui requiert une autorisation OAuth 2.0. L’application client est un un fichier d’exécution de MapForce Server (.mfx) 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 du mappage 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

•MapForce Server Advanced 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.

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.

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.

Exécuter le mappage avec MapForce Server (autonome)

Cette section traite spécifiquement l’exécution du mappage OAuth 2.0 démo avec MapForce Server installé en tant que produit autonome, et non avec FlowForce Server management. Pour toute information sur l’exécution de tels mappages avec MapForce Server dans FlowForce Server management, consultez la documentation de FlowForce Server, où cet exemple est poursuivi.

Pour exécuter un mappage OAuth 2.0 avec MapForce Server autonome, il y a deux manières de traiter les identifications OAuth 2.0 :

•Inclure un jeton OAuth 2.0 (sous forme encryptée) dans le fichier .mfx compilé. Avec cette approche, vous devrez fournir toute information d’identification OAuth 2.0 dans la ligne de commande (ou dans l'appel API de MapForce Server) parce que l’identification incorporée sera utilisée. Toutefois, ceci signifie que chacun avec un accès au fichier .mfx sera à même de l’exécuter sans fournir le jeton d’autorisation—jusqu’à expiration de celui-ci ou si le serveur d’autorisation le révoque. Plus important encore, vous pouvez toujours écraser le jeton d’autorisation depuis la ligne de commande sans avoir à recompiler le fichier .mfx (voir la prochaine puce).

•Ne pas inclure le jeton OAuth 2.0 dans le fichier .mfx compilé. Avec cette approche, vous (ou tout autre utilisateur qui exécute un fichier .mfx) devrez fournir un jeton d’autorisation OAuth 2.0 dans la ligne de commande ou l’appel API de MapForce Server. Le jeton d’autorisation lui-même doit être obtenu en dehors de MapForce Server, par exemple avec MapForce, tel que décrit précédemment.

Dans cet exemple, le jeton d’autorisation ne sera pas inclus dans le fichier .mfx compilé. Mais il sera fourni au moment de l’exécution.

1.Dans MapForce, cliquez avec la touche de droite sur une zone vide du mappage et sélectionnez Ouvrir Manager d’identifiants.

2.Double-cliquez sur l’enregistrement de l’identifiant (« my.oauth », dans cet exemple) et désactivez la case à cocher Inclure dans le fichier d’exécution et le déploiement de mappage dans MapForce Server.

3.Enregistrez le fichier design de mappage (.mfd).

Compilons maintenant le mappage vers un fichier d’exécution (.mfx) de MapForce Server :

1.Dans le menu Fichier, cliquez sur Compiler vers un fichier d’exécution (.mfx) de MapForce Server.

2.Sélectionnez un répertoire de destination et enregistrez le fichier en tant que GetCalendarEvents.mfx.

Vous pouvez désormais ouvrir une fenêtre d’invite de commandes et exécutez le fichier .mfx file avec une commande telle que :

Emplacement :

•mapforceserver-exec est le chemin vers le fichier exécutable de MapForce Server, typiquement C:\Program Files\Altova\MapForceServer2024\bin\MapForceServer.exe.

•GetCalendarEvents.mfx est le chemin vers le fichier .mfx par rapport au répertoire actuel de la ligne de commande. Ajustez le chemin, le cas échéant, ou utilisez un chemin absolu.

•calendarId est le nom du paramètre d’entrée tel qu’il a été créé dans MapForce

•my.oauth est le nom de l’identification tel qu’elle a été créée dans MapForce lors d’une étape précédente.

•mytoken est la valeur du jeton d’autorisation obtenu de manière externe (dans ce cas, avec MapForce).

Lorsque l’exécution et l’autorisation OAuth 2.0 ont réussi, le résultat de la ligne de commande affiche la réponse retournée par l'API Calendrier de Google, par exemple :