API-Schlüssel, Authentifizierung und der Proxy
Manche Grundkarten und Ebenen stammen von Diensten, die einen Schlüssel oder eine Anmeldung verlangen. Diese Seite beschreibt, wo diese Anmeldeinformationen eingetragen werden, wie sie gespeichert werden und was der Icon Map-Proxy tut, wenn ein Server Power BI das Lesen nicht erlaubt.
Einen API-Schlüssel eingeben
- Wählen Sie das Visual aus und öffnen Sie Formatbereich > API-Schlüssel und Authentifizierung > API-Schlüssel.
- Fügen Sie den Schlüssel in das Feld des Anbieters ein.
- Wählen Sie den Anbieter als Grundkarte oder schalten Sie die Ebene ein, die ihn verwendet.
Auf einer Karte, die den Grundkarten-Dialog verwendet, können Sie die Schlüssel für Azure Maps, Mappable und Ordnance Survey auch im Dialog eingeben, wenn Sie eine dieser Grundkarten hinzufügen. Sie werden in denselben Einstellungen gespeichert, wenn Sie Änderungen übernehmen wählen.
API-Schlüssel
| Einstellung | Verwendet für | Standard |
|---|---|---|
| Azure Maps | Azure Maps-Grundkarten | Leer |
| Mappable | Mappable-Grundkarten | Leer |
| Ordnance Survey | Ordnance Survey-Grundkarten | Leer |
| Open Weather Map | Die Referenzebene Wetter | Leer |
| Google Maps, Mapbox, Map Tiler | Grundkarten, die zur Engine Legacy gehören. Siehe die Dokumentation für 1.1.0.9 und früher | Leer |
Die Gruppe beginnt mit dem Hinweis „Den ArcGIS-API-Schlüssel finden Sie im Abschnitt ArcGIS-Authentifizierung“. ArcGIS hat eine eigene Gruppe, die als Nächstes beschrieben wird.
Welcher Anbieter welchen Schlüssel braucht, steht unter Weitere Grundkartenanbieter und Wetter, Verkehr und Tageslicht. Icon Map-Grundkarten brauchen keinen Schlüssel.
ArcGIS-Authentifizierung
Die Gruppe ArcGIS-Authentifizierung legt fest, wie sich die Karte mit ArcGIS Online oder ArcGIS Enterprise verbindet. Die vollständige Anleitung mit den Schritten für jede Methode ist Mit ArcGIS verbinden. Kurz gefasst:
| Authentifizierungstyp | Wer sich anmeldet | Was im Bericht gespeichert wird |
|---|---|---|
| API-Schlüssel | Niemand | Der API-Schlüssel |
| OAuth2 (Client-ID und geheimer Clientschlüssel) | Niemand. Eine in Ihrer ArcGIS-Organisation registrierte App stellt die Verbindung her | Die Client-ID und der geheime Clientschlüssel in geschützter Form |
| Benutzername und Kennwort | Jede Person, in einem Anmeldefenster von Power BI | Nichts. Die Sitzung wird im lokalen Speicher des Visuals auf dem Gerät dieser Person gehalten |
| Mit ArcGIS anmelden | Jede Person, in einem Browsertab | Nichts. Die Sitzung wird im lokalen Speicher des Visuals auf dem Gerät dieser Person gehalten |
Bei Mit ArcGIS anmelden öffnet sich die ArcGIS-Anmeldeseite in einem Browsertab. Ein Relay unter api.iconmap.ai gibt das Anmeldeergebnis an das Visual zurück, und das Visual tauscht es dann direkt bei Ihrem Portal gegen ein Token ein. Das Token wird nicht an Icon Map gesendet.
Anmeldeinformation senden als legt fest, wie die Anmeldeinformation an ArcGIS übertragen wird: URL-Parameter (Standard) oder Authorization-Header (Bearer). Belassen Sie die Einstellung auf URL-Parameter, sofern Ihr Server dies nicht ablehnt. ArcGIS Enterprise 11.5 und höher kann neuere API-Schlüssel in der URL mit „Invalid Token“ ablehnen. Diese Server brauchen die Option Authorization-Header und müssen den Authorization-Header in ihren CORS-Einstellungen zulassen.
Ohne Anmeldeinformation werden ArcGIS-Inhalte als öffentliche Inhalte gelesen.
Wie Anmeldeinformationen gespeichert werden
- API-Schlüssel werden als gewöhnliche Einstellungen im Bericht gespeichert. Jeder, der den Bericht bearbeiten kann, kann sie lesen, und das Visual sendet jeden Schlüssel an seinen eigenen Anbieter, wenn es Kacheln anfordert. Schränken Sie Schlüssel nach Möglichkeit beim Anbieter ein, zum Beispiel auf die Dienste, die die Karte verwendet.
- Der Wert unter Geheimer Clientschlüssel für ArcGIS wird in geschützter Form gespeichert und nach der Eingabe als Punkte angezeigt.
- Sitzungen aus einer persönlichen ArcGIS-Anmeldung werden im lokalen Speicher des Visuals auf dem Gerät des Lesers gehalten, nicht im Bericht. Dafür muss Ihr Power BI-Mandant den lokalen Speicher für benutzerdefinierte Visuals zulassen.
- Der Icon Map-Lizenzschlüssel wird, sofern einer verwendet wird, im Bericht unter Icon Map Pro > Lizenzschlüssel (für nicht benutzerbasierte Lizenzierung) gespeichert. Siehe Lizenzschlüssel und Aktivierung.
Der Proxy
Warum es einen Proxy gibt
Power BI führt jedes benutzerdefinierte Visual in einem Sandbox-Frame aus. Ein Webserver muss Anfragen aus diesem Frame über CORS-Header ausdrücklich zulassen, bevor das Visual seine Antwort lesen kann. Die meisten öffentlichen Kartendienste tun das. Einige Server tun es nicht, typischerweise ArcGIS Enterprise-Server sowie manche Kachel-, GeoJSON- und WFS-Server. Eine Ebene von einem solchen Server bleibt leer, obwohl sich derselbe Link in einem Browser öffnen lässt.
Die Lösung, bei der alles in Ihrer Hand bleibt, ist, CORS auf Ihrem Server zuzulassen. Wenn das nicht möglich ist, kann der Icon Map-Proxy die Ressource im Auftrag des Visuals abrufen und mit den Headern zurückgeben, die Power BI braucht.
Der Proxy ist ein Relay-Dienst, den Icon Map unter proxy.icon-map.com betreibt. Er ist standardmäßig ausgeschaltet. Er erfordert einen Icon Map-Lizenzschlüssel, und über den Proxy geleitete Anfragen können zusätzliche Nutzungsguthaben verbrauchen.
Wann der Proxy verwendet wird
Die Einstellung heißt Proxy bei Bedarf verwenden und funktioniert so, wie der Name sagt:
- Jeder Server wird zuerst direkt versucht.
- Nur ein Server, bei dem sich zeigt, dass er Power BI nicht zulässt, wird über den Proxy abgerufen. Das gilt für die Anfrage, bei der die Blockierung festgestellt wurde, und für spätere Anfragen an diesen Server in derselben Sitzung. Für Kartenkacheln und Bilder gilt dieselbe Regel.
- Server, die Power BI zulassen, werden nie über den Proxy geleitet, auch nicht bei eingeschaltetem Schalter.
Der Schalter erscheint an diesen Stellen:
| Wo | Gilt für | Wann er angezeigt wird |
|---|---|---|
| API-Schlüssel und Authentifizierung > ArcGIS-Authentifizierung > Proxy bei Bedarf verwenden | Jede ArcGIS-Anfrage der Karte, einschließlich ArcGIS-Grundkarten und Höhendaten | Immer |
| Die Konfigurationsgruppe einer per Link hinzugefügten Dateiebene (GeoJSON, KML, CSV, WFS), als Datenebene oder Referenzebene | Den Link dieser Ebene | Nachdem der Link als blockiert erkannt wurde oder wenn der Schalter bereits eingeschaltet ist |
| Die Konfigurationsgruppe einer Raster-Referenzebene | Die Kacheln dieser Ebene | Nachdem der Link als blockiert erkannt wurde oder wenn der Schalter bereits eingeschaltet ist |
| CORS-Proxy verwenden in der Gruppe einer WMS-Referenzebene | Diese WMS-Ebene | Immer |
Wenn ArcGIS-Server als blockiert erkannt wurden, nennt die Erläuterung unter dem ArcGIS-Schalter sie: „Diese ArcGIS-Server haben Anfragen von Power BI blockiert: ...“. Der Dialog ArcGIS durchsuchen bietet dieselbe Wahl mit der Schaltfläche CORS-Proxy verwenden.
CORS-Proxy verwenden bei einer WMS-Referenzebene ist ein älterer Schalter und verhält sich anders: Ist er eingeschaltet, läuft jede Anfrage für diese WMS-Ebene über den Proxy, ohne vorherigen direkten Versuch.
Für Grundkarten von Ihrem eigenen Kachelserver, WMS oder Stil-Link gibt es keinen Proxy-Schalter. Kacheln von einem blockierten Server werden nur dann über den Proxy geleitet, wenn der ArcGIS-Schalter eingeschaltet ist oder eine Ebene diesen Server dafür freigegeben hat.
Was an den Proxy gesendet wird
An den Proxy wird nichts gesendet, solange kein Proxy-Schalter eingeschaltet ist. Die einzige Ausnahme ist unten unter „WMS-Ebenen mit OAuth 2.0“ beschrieben.
Um eine Sitzung zu öffnen, sendet das Visual:
- den Icon Map-Lizenzschlüssel aus der Formatkarte Icon Map Pro
- die Umgebung, in der der Bericht ausgeführt wird (zum Beispiel Power BI Desktop, der Power BI-Dienst oder Power BI Embedded)
- den Produktnamen
- die optionale Referenz aus der Formatkarte Icon Map Pro
- die Instanz-ID des Visuals und eine Sitzungs-ID
Der Proxy antwortet mit einem kurzlebigen Sitzungstoken, das das Visual bis kurz vor dessen Ablauf wiederverwendet.
Für jede über den Proxy geleitete Anfrage sendet das Visual:
- die vollständige Adresse der Ressource einschließlich ihrer Abfragezeichenfolge. Ein Token oder Schlüssel, der Teil der Adresse ist, wird mit übertragen
- das Sitzungstoken
- alle zusätzlichen Anfrage-Header, die der Server braucht, zum Beispiel einen Authorization-Header
Der Proxy stellt die Anfrage an Ihren Server und gibt die Antwort zurück, einschließlich binärer Inhalte wie Kacheln. Wenn bei einer WMS-Ebene keine Sitzung geöffnet werden kann, sendet das Visual statt eines Sitzungstokens mit jeder Anfrage den Lizenzschlüssel und die Sitzungsdetails.
Was das bedeutet:
- Der Proxy-Dienst sieht die Adresse jeder über ihn geleiteten Anfrage, alle daran angehängten Anmeldeinformationen und die Antwort.
- Die Zeilen Ihrer Power BI-Daten werden über diesen Mechanismus nicht gesendet, nur Ebenen- und Kachelanfragen. Wenn Sie den Link oder Filter einer Ebene mit bedingter Formatierung aus Ihren Daten aufbauen, sind die Werte in diesem Link Teil der Adresse.
- Ihr Server muss aus dem Internet erreichbar sein, damit der Proxy von ihm abrufen kann. Einen Server, der nur innerhalb Ihres Netzwerks verfügbar ist, kann der Proxy nicht erreichen.
WMS-Ebenen mit OAuth 2.0
Wenn bei einer WMS-Referenzebene der Authentifizierungstyp auf OAuth 2.0 steht, fordert das Visual das Zugriffstoken über den Icon Map-Proxy-Dienst an, unabhängig davon, ob CORS-Proxy verwenden eingeschaltet ist. Diese Anfrage enthält die OAuth2-URL, die Client-ID, den geheimen Clientschlüssel und den Bereich, die Sie für die Ebene eingegeben haben, zusammen mit dem Lizenzschlüssel und den oben genannten Sitzungsdetails. Siehe Rasterkacheln, WMTS und WMS.
Den Proxy überall ausschalten
Schalten Sie Icon Map Pro > Anpassung > Airgap-Umgebung ein. Die Karte ruft dann keine Icon Map-Dienste mehr auf, auch nicht den Proxy. Jeder Proxy-Schalter wird ausgeschaltet und deaktiviert angezeigt, mit dem Hinweis „Nicht verfügbar: Die Airgapped-Umgebung ist aktiviert, daher ruft die Karte keine Icon Map-Dienste auf, auch nicht den Proxy.“
Siehe Power BI Report Server (lokal).
Tipps und Grenzen
- Beheben Sie nach Möglichkeit CORS auf Ihrem eigenen Server. Das vermeidet den Proxy, die Lizenzschlüssel-Anforderung und den zusätzlichen Umweg.
- Ein Link, der sich im Browser öffnen lässt, aber nicht in der Karte, ist das übliche Zeichen für eine CORS-Blockierung. Siehe Problembehandlung.
- Der Proxy macht einen privaten Server nicht öffentlich. Er leitet die Anmeldeinformationen weiter, die Ihre Karte bereits verwendet.
- Wenn Ihr Netzwerk ausgehenden Datenverkehr einschränkt, lassen Sie die Adressen der Anbieter und von Icon Map zu, die unter Unterstützte Umgebungen und Grenzen aufgeführt sind.