Langue
Français

Vue d'ensemble de l'API Embed

L'API Embed permet à la page qui héberge une carte Icon Map incorporée de piloter la carte en JavaScript et de recevoir ses notifications en retour. Si vous avez déjà utilisé la bibliothèque cliente de Power BI Embedded, le principe est le même, appliqué aux cartes : un petit SDK, un handle, des commandes qui renvoient des promesses et des événements auxquels vous vous abonnez.

Cette section s'adresse aux développeurs qui créent la page hôte. Si vous êtes l'auteur de la carte et souhaitez la publier ou l'incorporer, commencez par Publication et partage et Incorporer des cartes.

const map = IconMapEmbed.embed(document.getElementById("map"), { publishId: "pub_..." });
await map.ready;

await map.flyTo({ center: [-0.12, 51.5], zoom: 11 });
await map.selectByKey({ layerId: "assets", field: "asset_id", keys: ["41B"], zoomTo: true });

map.on("featureClick", (feature) => feature && openAssetPanel(feature.fields));

Ce que vous pouvez faire

Domaine Exemples
Caméra Lire la vue, sauter ou voler vers un lieu, cadrer un rectangle englobant ou une couche entière, limiter le déplacement à une zone
Couches Lister les couches, les afficher et les masquer, lire chaque bascule dont dispose le lecteur (étiquettes, ombrage, graphiques et autres visuels)
Filtres Découvrir les filtres déclarés par l'auteur, les définir (y compris des plages numériques et « 30 derniers jours »), actualiser les données en direct
Segments Lire et définir les segments du lecteur, lister les valeurs proposées par un segment
Sélection Sélectionner des entités à l'aide de vos propres clés (« équipement 41B »), mettre en surbrillance sans sélectionner, filtrer de manière croisée depuis un graphique
Scènes Capturer toute la vue sous la forme d'un seul objet, la restaurer plus tard, appliquer les signets de l'auteur, lire des visites
Présentation Basculer entre les fonds de carte publiés, masquer les contrôles propres à la carte, passer en mode sombre, lire la légende sous forme de données, exporter une image
Commandes de fenêtre contextuelle Ajouter votre propre action à la fenêtre contextuelle d'une entité (« Créer une intervention pour cet équipement »)
Analyse Exécuter le moteur d'analyse d'une couche et recevoir ses résultats, sur les cartes qui en ont un
Événements Changements de vue, clics sur des entités, sélection, filtres, segments, clics sur des liens, état des données, expiration du jeton

Le guide des commandes les présente avec des exemples ; la référence de l'API liste chaque commande, événement, code d'erreur et limite.

Fonctionnement

Le SDK monte la carte dans un <iframe> et communique avec elle par postMessage. Aucune partie de la carte ne s'exécute dans votre page, et aucune partie de votre page ne s'exécute dans la carte.

  1. Votre page appelle embed(). Le SDK crée le cadre et attend qu'il signale qu'il est prêt.
  2. Les deux côtés conviennent d'une version de protocole, et la carte vérifie l'origine de votre page par rapport à la liste des sites autorisés par son auteur.
  3. Si vous êtes autorisé, la carte répond par un descripteur de capacités : les commandes et événements auxquels cette carte répondra. await map.ready se résout avec ce descripteur.
  4. Ensuite, chaque appel de méthode correspond à un message envoyé à la carte et à une réponse en retour.

Vous n'avez rien à synchroniser. Les commandes appelées avant la fin du démarrage de la carte sont mises en attente et traitées dès que la partie de la carte dont elles ont besoin existe.

Deux façons d'incorporer, une seule API

Carte publiée Incorporation pour votre organisation
Qui la consulte Toute personne à qui vous donnez la page, sans compte Fabric Des collègues, chacun connecté avec son propre compte professionnel
Données Figées ou en direct, via la publication En direct, lues au nom de chaque lecteur : les autorisations Fabric et la sécurité au niveau des lignes s'appliquent
Point d'entrée embed(element, { publishId }) embedForOrganization(element, { mapItem })
Qui peut la piloter Les sites figurant dans les Allowed origins de la publication Les sites figurant dans les origines Embedding for your organization de l'élément

Les deux renvoient le même handle avec les mêmes méthodes. Quelques groupes n'existent que sur les cartes publiées (filtres déclarés et actualisation des données), car un élément en direct n'a pas de publication dans laquelle les déclarer. capabilities.commands vous indique toujours exactement ce dont vous disposez.

Ce que contrôle l'auteur

Le contrôle de l'incorporation s'active carte par carte, par son auteur, dans la boîte de dialogue de publication :

  • Allowed origins. Seules les pages de ces sites peuvent ouvrir une session de contrôle. Une carte sans origine autorisée peut toujours s'afficher, mais ne peut pas être pilotée.
  • Groupes de commandes. Caméra, couches, filtres, segments, sélection, scènes, présentation, commandes de fenêtre contextuelle, actualisation des données, analyse, et Read state and events. Tous sont activés par défaut ; l'auteur peut désactiver n'importe lequel.

Ces deux réglages font partie de la publication signée : ils ne peuvent pas être élargis en modifiant des fichiers ni par quoi que ce soit envoyé par votre page.

Ce que l'API ne fera pas

Ce sont des limites délibérées et permanentes, utiles à connaître avant de concevoir votre page :

  • Rien qu'un lecteur ne pourrait faire en cliquant. Aucune commande n'accepte une URL, une requête, un style ou une définition de couche. Pour afficher une autre carte, publiez une autre carte.
  • Rien que le lecteur ne peut voir. featureClick ne transporte que les champs d'info-bulle de la couche. Il n'existe aucune lecture en masse des données d'une couche, ni aucun accès à la configuration de la carte, à ses sources de données ou à ses requêtes.
  • Uniquement les filtres déclarés. setFilters accepte les filtres déclarés par l'auteur et rien d'autre ; les valeurs sont liées comme paramètres sur le serveur, jamais collées dans une requête.
  • La visibilité, pas le style. Vous pouvez afficher et masquer une couche. Vous ne pouvez pas la recolorer ni modifier son style.
  • Les étiquettes de confidentialité sont respectées. exportImage et print sont refusées lorsqu'une étiquette appliquée aux données de la carte n'autorise pas l'exportation.

Étapes suivantes