Utilisez les API keys pour exploiter les services géospatiaux d'ArcGIS Platform

Bonjour, aujourd'hui je vais vous expliquer comment utiliser les services géospatiaux d'ArcGIS Platform dans vos applications grâce aux API Keys. Nous verrons d'abord ce qu'est une API Key (clé API)  puis comment la définir, la gérer et l'utiliser pour surveiller l'usages des services géospatiaux.

I/ Définition des API Keys

Une clé API est un identifiant unique utilisé pour se connecter ou effectuer un appel API. Le processus de clé API est similaire à l'authentification utilisateur pour les applications Web et les appareils mobiles - l'appel API commence par une API en appelant une autre, puis en passant la clé API pour accéder.

La clé API signifie que l'API de connexion a un "mot de passe" ou une clé et un ensemble défini de droits d'accès. Par exemple, une application qui envoie des formulaires médicaux aux patients devrait connecter sa propre API à celle d'une application qui stocke des formulaires médicaux. Le propriétaire de l'API des formulaires médicaux attribue une clé API, qui permet à la première application d'accéder aux formulaires médicaux et à rien d'autre.

Elles sont normalement utilisées pour aider à suivre et à contrôler la façon dont l'interface est utilisée. Souvent, il le fait pour éviter les abus ou l'utilisation malveillante de l'API en question.

Une clé API peut agir comme un jeton d'authentification secret ainsi que comme un identifiant unique. En règle générale, la clé est fournie avec un ensemble de droits d'accès pour l'API à laquelle elle est associée.

II/ Définir et gérer une API Key dans ArcGIS Platform

Dans le cadre d'ArcGIS Platform, une API Key est nécessaire pour permettre l'accès aux services géospatiaux, aux cartes Web et aux scènes Web hébergés sur la plateforme ArcGIS. Tout est expliqué dans la documentation sur le site développeur. Je vais réexpliquer dans cet article comment définir et utiliser une API Key.

Créer une nouvelle API Key (clé API)

Votre première API Key est créée automatiquement pour vous lorsque vous créez un compte développeur gratuit ArcGIS Developer. Si vous disposez déjà d'un compte ArcGIS, vous pouvez vous connecter pour afficher cette clé API et créer d'autres clés API. Pour cela il faut :

1. Dans le tableau de bord du développeur, panneau des clés API, cliquez sur Manage.
2. Cliquez sur + New API Key.
1. Attribuez un titre et une description à votre nouvelle clé API.
2. Cliquez sur Create API Key pour enregistrer.
3. Votre tableau de bord affiche désormais la nouvelle clé API, y compris ses services géospatiaux attribués.

Le gif en début d'article montre exactement le processus de création d'une API key.

Définissez votre API Key (clé API)

Votre API Key est étendue par défaut pour inclure tous les services illustrés dans les tutoriels. Ces tutoriels fournissent des scénarios pour vous aider lors de la création de vos propres applications, y compris la définition de l'API Key.

1. Dans votre tableau de bord développeur, sélectionnez et copiez une clé API.
2. Dans votre code, remplacez la chaîne "YOUR_API_KEY" par la clé API de votre tableau de bord.

require([ "esri/config", ], function (esriConfig) { // set a global API key for all requests esriConfig.apiKey= "YOUR-API-KEY"; });

Assurez-vous que votre API Key est configurée pour accéder aux services géospatiaux appropriés avant de l'utiliser. Les API Keys sont configurées avec un accès au service de couche de fond de carte et au service de géocodage par défaut.

Gérez votre API Key (clé API)

Vous pouvez modifier les services géospatiaux, le contenu et les éléments, ou les en-têtes de référence configurés sur une clé API existante, surveiller son utilisation et mettre à jour son nom, sa description et d'autres paramètres. 

Les paramètres de API Key sont configurés à partir de l'onglet API Key du tableau de bord ArcGIS Developer.

1. Pour configurer une clé API, sélectionnez-la dans la liste des clés API, puis cliquez sur Edit API Key.
2. Pour configurer les services géospatiaux, votre clé API est autorisée à accéder:
1. Dans l'onglet Présentation> Location services tile, cliquez sur Configure services.
2. Cliquez pour cocher le (s) service (s) que vous souhaitez ajouter ou supprimer de cette clé API dans la fenêtre contextuelle Configure services.
3. Cliquez sur Configure # services pour enregistrer vos modifications.
4. Pour supprimer un service, cliquez sur Ø à côté du service dans le panneau ou répétez les étapes précédentes. Il vous sera demandé de confirmer votre suppression.
3. Pour ajouter du contenu et des éléments de carte et de couche à votre clé API:
1. Sur la vignette Contenu et éléments, cliquez sur +Add items.
2. Recherchez une carte ou une couche dans le menu de recherche. Vous pouvez limiter ce champ de recherche par type d'élément (couche d'entités hébergée, couche de tuiles, carte Web, GeoJSON ou CSV) ou rechercher tous les types d'éléments. Notez que vous devez avoir préalablement créé des éléments de carte et de couche.
3. Une fois que vous avez localisé et sélectionné les éléments de carte et de couche à attacher à votre clé API, cliquez sur Add Items pour les enregistrer et fermer la fenêtre contextuelle.
4. Pour ajouter un ou plusieurs en-têtes Referrer à votre clé API:
1. Sur la vignette Referrers, cliquez sur + Add Referrer.
2. Saisissez l'adresse d'en-tête (URL) du référent à utiliser avec cette clé API.
3. Cliquez sur Add Referrer Header pour l'enregistrer et fermer cette fenêtre contextuelle.
4. Pour supprimer un référent, cliquez sur Ø à côté du référent. Il vous sera demandé de confirmer votre suppression.
5. Pour modifier un référent, cliquez sur l'icône en forme de crayon. Cliquez sur Edit Referrer Header pour enregistrer vos modifications.
5. Pour surveiller l'utilisation de vos clés API.
1. Cliquez sur l'onglet Usage pour afficher et surveiller l'utilisation de cette clé API.
6. Pour mettre à jour le nom, les balises, la description d'une clé API, désactiver ses protections ou la supprimer du système:
1. Cliquez sur l'onglet Settings.
2. Attribuez un titre, des balises et une description, puis cliquez sur Save settings.
3. Basculez l'icône de protection pour activer ou désactiver la suppression. Ce paramètre empêche la suppression de la clé API par d'autres utilisateurs ou par vous-même, sauf si vous revenez à cet écran.
4. Cliquez sur Delete API Key pour supprimer cette clé API. Cela l'invalide définitivement de toute application tentant d'utiliser cette clé pour l'authentification.

Services

Les clés API peuvent être autorisées à accéder à différents services. Pour configurer les services auxquels votre clé API est autorisée à accéder à partir de votre tableau de bord ArcGIS Developers, onglet API keys:

1. Sélectionnez-le dans la liste des clés API, puis cliquez sur Edit API Key.
2. Dans l'onglet Overview > Location Services tile, cliquez sur Configure services.
3. Cliquez pour vérifier le(s) service(s) à ajouter ou à supprimer de cette clé API dans la fenêtre contextuelle Configure services.
4. Cliquez sur Configure # services pour enregistrer vos modifications.
5. Pour supprimer un service, cliquez sur Ø à côté du service dans le panneau ou répétez les étapes précédentes en désélectionnant le service que vous souhaitez supprimer. Il vous sera demandé de confirmer avant de supprimer un service.

Contenu et éléments (bêta)

Seuls les comptes ArcGIS Developer peuvent utiliser des clés API pour lire du contenu privé. Pour ajouter des éléments de carte ou de couche à votre clé API à partir de votre tableau de bord ArcGIS Developers, onglet Clés API:

1. Sélectionnez-le dans la liste des clés API, puis cliquez sur Edit API Key.
2. Dans l'onglet Présentation> vignette Contenu et éléments, cliquez sur +Add items.
3. Recherchez une carte ou une couche dans le menu de recherche. Vous pouvez limiter ce champ de recherche par type (couche d'entités hébergée, couche de tuiles, carte Web, GeoJSON ou CSV) ou rechercher tous les types d'éléments.
4. Une fois que vous avez localisé et sélectionné les éléments de carte et de couche à attacher à votre clé API, cliquez sur Add Items pour les enregistrer et fermer la fenêtre contextuelle.

Vous devez avoir créé au préalable du contenu et des éléments de carte et de couche pour pouvoir les localiser à l'aide d'une recherche de contenu et d'éléments et les ajouter à votre clé API.

Referer

Pour configurer le ou les HTTP referer header(s) que vous souhaitez attacher à votre clé API à partir de votre tableau de bord ArcGIS Developer, onglet API keys:

1. Sélectionnez-le dans la liste des clés API, puis cliquez sur Edit API Key.
2. Sous l'onglet Overview> Referer tile, cliquez sur + Add Referrer.
3. Entrez l'adresse d'en-tête du Referer (par exemple https: //*.your-app.com) à utiliser avec cette clé API.
4. Cliquez sur Add Referrer Header pour l'enregistrer et fermer cette fenêtre contextuelle.
5. Pour supprimer un référent, cliquez sur Ø à côté du référent. Il vous sera demandé de confirmer votre suppression.
6. Pour modifier un référent, cliquez sur l'icône en forme de crayon. Cliquez sur Edit Referrer Header pour enregistrer vos modifications.

Il n'est actuellement pas possible d'utiliser les referer headers avec les API ArcGIS Runtime.

Surveiller l'utilisation

Nous vous recommandons de surveiller régulièrement l'utilisation de votre clé API pour détecter les irrégularités et de faire fréquemment pivoter les clés API pour empêcher tout accès non autorisé.

Il existe plusieurs façons d'examiner et de surveiller l'utilisation des clés d'API:

1. Vérifiez l'utilisation globale à partir du panneau Utilisation du tableau de bord ArcGIS Developer.
2. Dans l'onglet API keys, sélectionnez  View usage d'une clé API dans votre liste de clés API.
3. Sélectionnez une clé API individuelle, puis cliquez sur son onglet Usage.

Pour clairement appliquer les API keys dans un exemple, n'hésitez pas à suivre ce tutoriel, Créez une carte en moins de 5 minutes.

Depuis la version 4.19 arrivée en Avril 2021

Au fil des versions, les capacités et usages des API Keys sera élargi et plus complet. On retrouve notamment ces nouveautés dans cet article.

La version 4.19 ajoute un contrôle plus fin des clés API et ajoute plus de flexibilité. Par exemple :

Il est désormais plus facile d'utiliser les clés API conjointement (si nécessaire) avec les identités ArcGIS (et l'Identity Manager)

- Les widgets Search et Directions seront automatiquement câblés par défaut sur les services appropriés lors de l'utilisation d'une clé API globale.
- Vous pouvez définir explicitement une clé API à utiliser avec les widgets Search et Directions.

Pour voir des exemples d'utilisation des clés API, consultez les exemples de widgets Directions et Search.

Depuis la version 4.20 arrivée en Juillet 2021

Au cours des deux dernières versions, Esri a ajouté la prise en charge d'une clé API globale (4.18) pour utiliser avec les services de géolocalisés d'ArcGIS Platform et une prise en charge des services de calcul d'itinéraire (4.19). La version 4.20 s'ajoute à cela en ajoutant la possibilité de définir des clés API pour des couches individuelles, ce qui vous donne un contrôle plus précis sur la clé utilisée pour une couche particulière

Vous pouvez vous abonner à ce blog pour lire d'autres articles sur le développement Web d'applications cartographiques et découvrir comment notre API est une superbe alternative à Google Maps !

Vous voulez vous aussi réaliser des applications Web cartographiques et dynamiques ? N'hésitez pas à souscrire à un plan gratuit ArcGIS for Developers pour développer vos propres applications cartographiques 2D ou 3D ! Cet article résume ce que vous obtiendrez. Et pour en savoir sur l'API c'est ici.