Altova FlowForce Server 2025 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 une tâche de FlowForce Server 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  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

•FlowForce 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.

Déployez le mappage sur FlowForce Server

Cette section vous montre comment exécuter le mappage OAuth 2.0 démo avec MapForce Server installé dans FlowForce Server management. Les prérequis suivants doivent être en place :

1.FlowForce Server Advanced Edition doit être installée et sous licence.

2.MapForce Server Advanced Edition doit être installée et sous licence.

3.Le service de FlowForce Web Server doit être lancé et à l’écoute sur l’adresse et le port configurés. Si FlowForce Server a été installé sur l’ordinateur actuel avec les paramètres par défaut, l’adresse est http://localhost:8082.

4.Vous devez avoir un compte utilisateur de FlowForce Server et un accès en écriture vers l’un des conteneurs de FlowForce Server. Pour rester simple, cet exemple utilise le compte par défaut de la racine du serveur FlowForce et déploie le mappage vers le conteneur public par défaut ; ces détails se laissent configurés autrement.

Pour exécuter le mappage en tant que tâche dans un environnement de serveur, vous devez le déployer vers l’instance désignée dans le serveur FlowForce. Avant de déployer le mappage, vous pouvez traiter les identifications OAuth 2.0 d’une des manières suivantes :

•Inclure le jeton OAuth 2.0 (sous forme encryptée) dans le package déployé vers le serveur FlowForce. Avec cette approche, vous devrez fournir toute information d’identification OAuth 2.0 lorsque la tâche est exécutée parce que le jeton incorporé sera utilisé. Il sera possible d’exécuter la tâche de FlowForce jusqu’à expiration du jeton d’autorisation ou si le serveur d’autorisation le révoque. Veuillez noter que vous pouvez toujours remplacer les détails d’autorisation OAuth 2.0 avec de nouveaux (voir la prochaine puce).

•Ne pas inclure le jeton OAuth 2.0 dans le package déployé vers FlowForce. Dans ce cas, vous devez fournir le chemin vers un enregistrement d’identification OAuth 2.0 à une tâche lors de sa configuration. À ces fins, vous pouvez créer un tout nouvel enregistrement d’identification OAuth 2.0 dans le serveur FlowForce ou déployer un enregistrement d’identification OAuth 2.0 existant depuis MapForce vers FlowForce Server.

Dans ce tutoriel, à titre d’exemple, l’identification OAuth 2.0 ne sera pas incluse dans le package déployé. Vous allez plutôt la déployer séparément, puis configurer la tâche FlowForce pour la référencer. À cette fin, suivez les étapes suivantes :

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).

Déployons maintenant le mappage dans FlowForce Server :

1.Dans le menu Fichier, cliquez Déployer sur FlowForce Server.

2.Remplissez les détails applicables à FlowForce Server et cliquez sur OK. Après le déploiement réussi, la fenêtre Messages affiche un message pertinent :

Séparément, déployons également l’identifiant OAuth 2.0 existant :

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

2.Dans le Manager d’identifiants, cliquez sur l’enregistrement « my.oauth » de la touche droite de la souris et sélectionnez Déployer Identifiant sur FlowForce Server depuis le menu contextuel.

3.Remplissez les détails applicables à FlowForce Server et cliquez sur OK. Après le déploiement réussi, la fenêtre Messages affiche un message pertinent :

Pour visionner l’identifiant déployé, connectez-vous à FlowForce Server et ouvrez la page des identifiants depuis le chemin ci-dessus.

Configurer la tâche FlowForce Server

Lors d’une étape précédente, vous avez déployé le mappage GetCalendarEvents.mfd sur une instance de FlowForce Server qui est exécutée localement. À cette étape, vous allez transformer le mappage déployé en une tâche FlowForce. Dans cet exemple, la tâche sera appelée comme un service Web de manière à pouvoir être rapidement déclenchée sur demande.

1.Connectez-vous sur FlowForce Server et ouvrez GetCalendarEvents.mapping depuis le conteneur « public ». Dans FlowForce Server, les mappages déployés deviennent des fonctions, à savoir la terminologie utilisée sur l’interface ci-dessous. Veuillez noter que la fonction exige un identifiant en tant que paramètre d’entrée. Le nom de l’identifiant est le même que celui donné dans MapForce, à savoir « my.oauth ».

2.Cliquez sur Créer la tâche. La page de configuration de la tâche s’ouvre.

3.Sous « Paramètres d’entrée de la tâche », cliquez et créez un nouveau paramètre appelé calendarId, avec une valeur par défaut de en.usa#holiday@group.v.calendar.google.com (de manière alternative, vous pouvez saisir primary en tant que valeur par défaut, la même valeur utilisée précédemment dans l’aperçu de l’exécution).

4.Sous « Étapes d’exécution », trouvez le paramètre de calendarId, cliquez « Affecter à » et sélectionnez calendarId.

5.En ce qui concerne le paramètre my.oauth, cliquez sur le bouton, choisissez Sélectionnez l’identification existante, et recherchez l’identification OAuth 2.0 précédemment déployée. Vous la trouverez dans le conteneur public si vous n’avez pas modifié les paramètres par défaut lors du déploiement :

6.Sous « Service », cliquez sur la case à cocher Rendre la tâche disponible via HTTP... et saisissez un nom de service (« GetCalendarEvents », dans cet exemple).

7.Sous « Identification », sélectionnez Définir identification locale, et saisissez les informations d’identification de votre système d’exploitation. N’oubliez pas que celles-ci sont différentes de vos identifications de compte de votre FlowForce Server et sont requises pour exécuter la tâche.

8.Laissez tous les autres paramètres tels quels et enregistrez la tâche.

Vous pouvez désormais exécuter la tâche comme suit :

1.Sous « Service », cliquez sur Lancer tâche URL dans le bouton de la nouvelle fenêtre.

2.Lorsqu’on vous demande de saisir vos informations d’identification, saisissez vos identifications de compte de FlowForce Server.

Lorsque l’exécution et l’autorisation OAuth 2.0 ont réussi, le navigateur affiche la réponse JSON reçue de l'API Calendrier de Google, par exemple :

Dans l’appel du service Web illustré ci-dessus, la valeur par défaut de calendarId a été utilisée. En option, vous pouvez ajouter un paramètre d’entrée à l’URL, par exemple : http://localhost:4646/service/GetCalendarEvents?calendarId=primary. Appeler le service Web génère désormais l’extraction de l’API Calendrier de Google pour l’identifiant calendrier fourni en tant que paramètre.

Dans cet exemple, le paramètre calendarId a été fourni par le biais d’une méthode HTTP GET parce que vous appelez le service Web directement depuis le navigateur. Si vous appelez le service Web via un programme, il est également possible d’utiliser une méthode HTTP POST. Pour plus d’informations, voir Exposer des tâches en tant que Services Web.