Sprache
Deutsch

Embed API im Überblick

Mit der Embed API kann die Seite, in die eine Icon Map eingebettet ist, die Karte per JavaScript steuern und Rückmeldungen von ihr erhalten. Wenn Sie die Clientbibliothek von Power BI Embedded kennen: Das Prinzip ist dasselbe, nur für Karten. Ein kleines SDK, ein Handle, Befehle, die Promises zurückgeben, und Ereignisse, die Sie abonnieren können.

Dieser Abschnitt richtet sich an Entwickler, die die einbettende Seite bauen. Wenn Sie die Karte erstellt haben und sie veröffentlichen oder einbetten möchten, beginnen Sie mit Veröffentlichen und Freigeben und Karten einbetten.

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

Was Sie tun können

Bereich Beispiele
Kamera Die Ansicht auslesen, zu einem Ort springen oder fliegen, einen Begrenzungsrahmen oder eine ganze Ebene einpassen, das Verschieben auf einen Bereich beschränken
Ebenen Die Ebenen auflisten, ein- und ausblenden, jeden Schalter auslesen, den der Betrachter hat (Beschriftungen, Schummerung, Diagramme und andere Visuals)
Filter Die vom Autor deklarierten Filter ermitteln und setzen (auch Zahlenbereiche und „letzte 30 Tage“), Livedaten aktualisieren
Datenschnitte Die Datenschnitte des Betrachters auslesen und setzen, die Werte auflisten, die ein Datenschnitt anbietet
Auswahl Features über Ihre eigenen Schlüssel auswählen („Anlage 41B“), hervorheben ohne auszuwählen, über ein Diagramm kreuzfiltern
Szenen Die gesamte Ansicht als ein Objekt erfassen und später wiederherstellen, die Lesezeichen des Autors anwenden, Touren abspielen
Darstellung Zwischen den veröffentlichten Grundkarten wechseln, die Bedienelemente der Karte ausblenden, in den dunklen Modus wechseln, die Legende als Daten lesen, ein Bild exportieren
Popup-Befehle Dem Feature-Popup eine eigene Aktion hinzufügen („Auftrag für diese Anlage anlegen“)
Analyse Die Analyse-Engine einer Ebene ausführen und ihre Ergebnisse empfangen, auf Karten, die eine haben
Ereignisse Änderungen der Ansicht, Klicks auf Features, Auswahl, Filter, Datenschnitte, Linkklicks, Datenstatus, Ablauf des Tokens

Der Leitfaden zu den Befehlen führt mit Beispielen durch diese Bereiche; die API-Referenz listet jeden Befehl, jedes Ereignis, jeden Fehlercode und jedes Limit auf.

So funktioniert es

Das SDK bindet die Karte als <iframe> ein und kommuniziert mit ihr über postMessage. Nichts von der Karte läuft in Ihrer Seite, und nichts von Ihrer Seite läuft in der Karte.

  1. Ihre Seite ruft embed() auf. Das SDK erstellt den Frame und wartet, bis dieser meldet, dass er bereit ist.
  2. Beide Seiten einigen sich auf eine Protokollversion, und die Karte prüft den Ursprung Ihrer Seite gegen die Liste der Websites, die ihr Autor zugelassen hat.
  3. Ist Ihre Seite zugelassen, antwortet die Karte mit einem Capability-Deskriptor: den Befehlen und Ereignissen, die diese Karte beantwortet. await map.ready wird damit aufgelöst.
  4. Danach ist jeder Methodenaufruf eine Nachricht an die Karte und eine Antwort zurück.

Sie müssen nichts zeitlich abstimmen. Befehle, die Sie aufrufen, bevor die Karte vollständig gestartet ist, werden zurückgehalten und beantwortet, sobald der Teil der Karte existiert, den sie benötigen.

Zwei Arten der Einbettung, eine API

Veröffentlichte Karte Einbetten für Ihre Organisation
Wer sieht sie Jeder, dem Sie die Seite geben - kein Fabric-Konto nötig Kollegen, jeweils mit ihrem eigenen Geschäftskonto angemeldet
Daten Eingefroren oder live, über die Veröffentlichung Live, im Namen des jeweiligen Betrachters gelesen, sodass Fabric-Berechtigungen und Sicherheit auf Zeilenebene gelten
Einstiegspunkt embed(element, { publishId }) embedForOrganization(element, { mapItem })
Wer darf sie steuern Websites unter den Allowed origins der Veröffentlichung Websites unter den Ursprüngen für Embedding for your organization des Elements

Beide liefern dasselbe Handle mit denselben Methoden. Einige Gruppen gibt es nur bei veröffentlichten Karten (deklarierte Filter und Datenaktualisierung), weil ein Live-Element keine Veröffentlichung hat, in der sie deklariert werden könnten. capabilities.commands sagt Ihnen immer genau, was Ihnen zur Verfügung steht.

Was der Autor festlegt

Die Steuerung einer Einbettung wird pro Karte von ihrem Autor im Veröffentlichungsdialog aktiviert:

  • Allowed origins. Nur Seiten auf diesen Websites können eine Steuerungssitzung öffnen. Eine Karte ohne zulässige Ursprünge kann trotzdem angezeigt, aber nicht gesteuert werden.
  • Befehlsgruppen. Kamera, Ebenen, Filter, Datenschnitte, Auswahl, Szenen, Darstellung, Popup-Befehle, Datenaktualisierung, Analyse sowie Zustand und Ereignisse lesen. Alle sind standardmäßig aktiviert; der Autor kann jede davon deaktivieren.

Beide Einstellungen sind Teil der signierten Veröffentlichung. Sie lassen sich daher weder durch Bearbeiten von Dateien noch durch irgendetwas, das Ihre Seite sendet, erweitern.

Was die API nicht tut

Dies sind bewusste, dauerhafte Grenzen. Es lohnt sich, sie zu kennen, bevor Sie Ihr Design darauf aufbauen:

  • Nichts, was ein Betrachter nicht auch per Klick tun könnte. Es gibt keinen Befehl, der eine URL, eine Abfrage, einen Stil oder eine Ebenendefinition entgegennimmt. Um eine andere Karte zu zeigen, veröffentlichen Sie eine andere Karte.
  • Nichts, was der Betrachter nicht sehen kann. featureClick liefert nur die QuickInfo-Felder der Ebene. Es gibt kein Massenauslesen der Daten hinter einer Ebene und keinen Zugriff auf die Konfiguration, Datenquellen oder Abfragen der Karte.
  • Nur deklarierte Filter. setFilters akzeptiert die vom Autor deklarierten Filter und sonst nichts; die Werte werden auf dem Server als Parameter gebunden und nie in eine Abfrage eingefügt.
  • Sichtbarkeit, kein Styling. Sie können eine Ebene ein- und ausblenden. Sie können sie weder umfärben noch umgestalten.
  • Vertraulichkeitsbezeichnungen werden beachtet. exportImage und print werden abgelehnt, wenn eine Bezeichnung auf den Daten der Karte keinen Export zulässt.

Nächste Schritte