Clés API, authentification et proxy
Certains fonds de carte et certaines couches proviennent de services qui exigent une clé ou une connexion. Cette page explique où placer ces informations d'identification, comment elles sont stockées et ce que fait le proxy Icon Map quand un serveur n'autorise pas Power BI à le lire.
Saisir une clé API
- Sélectionnez le visuel et ouvrez Volet Format > Clés API et authentification > Clés API.
- Collez la clé dans la zone du fournisseur.
- Choisissez le fournisseur comme fond de carte ou activez la couche qui l'utilise.
Sur une carte qui utilise la boîte de dialogue Fonds de carte, vous pouvez aussi saisir les clés Azure Maps, Mappable et Ordnance Survey dans la boîte de dialogue au moment d'ajouter l'un de ces fonds de carte. Elles sont enregistrées dans les mêmes paramètres quand vous sélectionnez Appliquer les modifications.
Clés API
| Paramètre | Utilisé pour | Valeur par défaut |
|---|---|---|
| Azure Maps | Les fonds de carte Azure Maps | Vide |
| Mappable | Les fonds de carte Mappable | Vide |
| Ordnance Survey | Les fonds de carte Ordnance Survey | Vide |
| Open Weather Map | La couche de référence Météo | Vide |
| Google Maps, Mapbox, Map Tiler | Des fonds de carte qui font partie du moteur Hérité. Voir la documentation des versions 1.1.0.9 et antérieures | Vide |
Le groupe commence par la note « Voir la section Authentification ArcGIS pour la clé API ArcGIS ». ArcGIS a son propre groupe, décrit ci-après.
Le détail des clés exigées par chaque fournisseur se trouve dans Autres fournisseurs de fonds de carte et Météo, trafic et lumière du jour. Les fonds de carte Icon Map n'exigent aucune clé.
Authentification ArcGIS
Le groupe Authentification ArcGIS définit la façon dont la carte se connecte à ArcGIS Online ou à ArcGIS Enterprise. Le guide complet, avec les étapes de chaque méthode, est Se connecter à ArcGIS. En résumé :
| Type d'authentification | Qui se connecte | Ce qui est enregistré dans le rapport |
|---|---|---|
| Clé API | Personne | La clé API |
| OAuth2 (ID client et secret) | Personne. Une application inscrite dans votre organisation ArcGIS se connecte | L'ID client, et le secret client sous forme protégée |
| Nom d'utilisateur et mot de passe | Chaque personne, dans une fenêtre de connexion Power BI | Rien. La session est conservée dans le stockage local du visuel, sur l'appareil de la personne |
| Se connecter avec ArcGIS | Chaque personne, dans un onglet du navigateur | Rien. La session est conservée dans le stockage local du visuel, sur l'appareil de la personne |
Avec Se connecter avec ArcGIS, la page de connexion ArcGIS s'ouvre dans un onglet du navigateur. Un relais hébergé sur api.iconmap.ai renvoie le résultat de la connexion au visuel, qui l'échange ensuite contre un jeton directement auprès de votre portail. Le jeton n'est pas envoyé à Icon Map.
Envoyer les informations d'identification en tant que définit la façon dont les informations d'identification sont transmises à ArcGIS : Paramètre d'URL (par défaut) ou En-tête Authorization (Bearer). Laissez Paramètre d'URL, sauf si votre serveur le rejette. ArcGIS Enterprise 11.5 et les versions ultérieures peuvent rejeter les clés API récentes transmises dans l'URL avec « Invalid Token ». Ces serveurs ont besoin de l'option En-tête Authorization et doivent autoriser l'en-tête Authorization dans leurs paramètres CORS.
Sans informations d'identification, le contenu ArcGIS est lu comme du contenu public.
Stockage des informations d'identification
- Les clés API sont enregistrées dans le rapport comme des paramètres ordinaires. Toute personne qui peut modifier le rapport peut les lire, et le visuel envoie chaque clé à son fournisseur quand il demande des tuiles. Restreignez les clés chez le fournisseur quand c'est possible, par exemple aux services que la carte utilise.
- Le Secret client ArcGIS est enregistré sous forme protégée et affiché sous forme de points une fois saisi.
- Les sessions issues d'une connexion ArcGIS personnelle sont conservées dans le stockage local du visuel, sur l'appareil du lecteur, et non dans le rapport. Votre locataire Power BI doit pour cela autoriser le stockage local pour les visuels personnalisés.
- La clé de licence Icon Map, quand il y en a une, est enregistrée dans le rapport, dans Icon Map Pro > Clé de licence (pour une licence non basée sur l'utilisateur). Voir Clés de licence et activation.
Le proxy
Pourquoi un proxy existe
Power BI exécute chaque visuel personnalisé dans un cadre isolé (sandbox). Un serveur web doit autoriser explicitement les requêtes provenant de ce cadre, au moyen d'en-têtes CORS, avant que le visuel puisse lire sa réponse. La plupart des services de cartes publics le font. Certains serveurs ne le font pas, en général des serveurs ArcGIS Enterprise et certains serveurs de tuiles, GeoJSON et WFS. Une couche issue d'un tel serveur reste vide, alors que le même lien s'ouvre dans un navigateur.
La solution qui vous laisse la maîtrise de tout consiste à autoriser CORS sur votre serveur. Quand vous ne le pouvez pas, le proxy Icon Map peut récupérer la ressource pour le compte du visuel et la renvoyer avec les en-têtes dont Power BI a besoin.
Le proxy est un service de relais exploité par Icon Map à l'adresse proxy.icon-map.com. Il est désactivé par défaut. Il exige une clé de licence Icon Map, et les requêtes passant par le proxy peuvent consommer des crédits d'utilisation supplémentaires.
Quand le proxy est utilisé
Le paramètre s'appelle Utiliser le proxy si nécessaire, et il fonctionne comme son nom l'indique :
- Chaque serveur est d'abord interrogé directement.
- Seul un serveur dont on constate qu'il n'autorise pas Power BI est interrogé via le proxy. Cela vaut pour la requête qui a révélé le blocage et pour les requêtes suivantes vers ce serveur pendant la même session. Les tuiles et les images de carte suivent la même règle.
- Les serveurs qui autorisent Power BI ne passent jamais par le proxy, même quand le commutateur est activé.
Le commutateur apparaît aux endroits suivants :
| Où | S'applique à | Quand il est affiché |
|---|---|---|
| Clés API et authentification > Authentification ArcGIS > Utiliser le proxy si nécessaire | Toutes les requêtes ArcGIS de la carte, y compris les fonds de carte et l'élévation ArcGIS | Toujours |
| Le groupe de configuration d'une couche de fichier ajoutée par lien (GeoJSON, KML, CSV, WFS), en couche de données ou en couche de référence | Le lien de cette couche | Une fois le lien détecté comme bloqué, ou quand le commutateur est déjà activé |
| Le groupe de configuration d'une couche de référence raster | Les tuiles de cette couche | Une fois le lien détecté comme bloqué, ou quand le commutateur est déjà activé |
| Utiliser le proxy CORS dans le groupe d'une couche de référence WMS | Cette couche WMS | Toujours |
Quand des serveurs ArcGIS ont été détectés comme bloqués, l'explication située sous le commutateur ArcGIS les nomme : « Ces serveurs ArcGIS ont bloqué les requêtes provenant de Power BI : ... ». La boîte de dialogue Parcourir ArcGIS propose le même choix avec un bouton Utiliser le proxy CORS.
Utiliser le proxy CORS sur une couche de référence WMS est un commutateur plus ancien, au comportement différent : quand il est activé, toutes les requêtes de cette couche WMS passent par le proxy, sans tentative directe préalable.
Il n'existe pas de commutateur de proxy pour les fonds de carte issus de votre propre serveur de tuiles, d'un WMS ou d'un lien de style. Les tuiles d'un serveur bloqué ne passent par le proxy que si le commutateur ArcGIS est activé ou si une couche a inscrit ce serveur.
Ce qui est envoyé au proxy
Rien n'est envoyé au proxy tant qu'aucun commutateur de proxy n'est activé, à une exception près, décrite ci-dessous sous « Couches WMS qui utilisent OAuth 2.0 ».
Pour ouvrir une session, le visuel envoie :
- la clé de licence Icon Map de la carte Icon Map Pro
- l'environnement dans lequel le rapport s'exécute (par exemple Power BI Desktop, le service Power BI ou Power BI Embedded)
- le nom du produit
- la Référence facultative de la carte Icon Map Pro
- l'ID d'instance du visuel et un ID de session
Le proxy répond par un jeton de session de courte durée, que le visuel réutilise jusqu'à peu avant son expiration.
Pour chaque requête passant par le proxy, le visuel envoie :
- l'adresse complète de la ressource, chaîne de requête comprise. Un jeton ou une clé qui fait partie de l'adresse est transmis avec elle
- le jeton de session
- les éventuels en-têtes de requête supplémentaires dont le serveur a besoin, par exemple un en-tête d'autorisation
Le proxy adresse la requête à votre serveur et renvoie la réponse, y compris le contenu binaire comme les tuiles. Pour une couche WMS, si aucune session ne peut être ouverte, le visuel envoie la clé de licence et les détails de session avec chaque requête à la place d'un jeton de session.
Ce que cela signifie :
- Le service de proxy voit l'adresse de chaque requête qui passe par lui, les informations d'identification qui y sont jointes et la réponse.
- Les lignes de vos données Power BI ne sont pas envoyées par ce mécanisme. Seules les requêtes de couches et de tuiles le sont. Si vous construisez le lien ou le filtre d'une couche à partir de vos données avec la mise en forme conditionnelle, les valeurs de ce lien font partie de l'adresse.
- Votre serveur doit être accessible depuis Internet pour que le proxy puisse l'interroger. Le proxy ne peut pas atteindre un serveur disponible uniquement à l'intérieur de votre réseau.
Couches WMS qui utilisent OAuth 2.0
Quand le Type d'authentification d'une couche de référence WMS est réglé sur OAuth 2.0, le visuel demande le jeton d'accès via le service de proxy Icon Map, que Utiliser le proxy CORS soit activé ou non. Cette requête contient l'URL OAuth2, l'ID client, le secret client et l'étendue que vous avez saisis pour la couche, ainsi que la clé de licence et les détails de session listés ci-dessus. Voir Tuiles raster, WMTS et WMS.
Désactiver le proxy partout
Activez Icon Map Pro > Personnalisation > Environnement isolé. La carte n'appelle alors aucun service Icon Map, proxy compris. Chaque commutateur de proxy est affiché désactivé et grisé, avec la note « Indisponible : l'Environnement isolé (airgapped) est activé, la carte n'appelle donc aucun service Icon Map, y compris le proxy. »
Voir Power BI Report Server (local).
Conseils et limites
- Préférez corriger CORS sur votre propre serveur. Vous évitez ainsi le proxy, l'exigence d'une clé de licence et le saut supplémentaire.
- Un lien qui s'ouvre dans un navigateur mais pas dans la carte est le signe habituel d'un blocage CORS. Voir Résolution des problèmes.
- Le proxy ne rend pas public un serveur privé. Il transmet les informations d'identification que votre carte utilise déjà.
- Si votre réseau restreint le trafic sortant, autorisez les adresses des fournisseurs et d'Icon Map listées dans Environnements pris en charge et limites.