Entwickeln skalierbarer Mehrinstanzenfähigkeitsanwendungen mit Power BI-Einbettung

  • Artikel

In diesem Artikel wird beschrieben, wie Sie eine mehrinstanzenfähige Anwendung entwickeln, die Power BI-Inhalte einbettet und gleichzeitig ein Höchstmaß an Skalierbarkeit, Leistung und Sicherheit erreicht. Durch das Entwerfen und Implementieren einer Anwendung mit Dienstprinzipalprofilen können Sie eine Mehrinstanzenlösung erstellen und verwalten. Diese kann Zehntausende von Kundenmandanten umfasst, die Berichte an Zielgruppen mit über 100.000 Benutzer*innen übermitteln können.

Dienstprinzipalprofile ist ein Feature, dass Ihnen das Verwalten von Organisationsinhalten in Power BI und die effizientere Nutzung Ihre Kapazitäten erleichtert. Die Verwendung von Dienstprinzipalprofilen kann jedoch die Komplexität Ihres Anwendungsentwurfs noch zusätzlich erhöhen. Daher sollten Sie sie nur verwenden, wenn eine erhebliche Skalierung erforderlich ist. Dienstprinzipalprofile sind zu empfehlen, wenn Sie über viele Arbeitsbereiche und mehr als 1.000 Anwendungsbenutzer verfügen.

Hinweis

Der Nutzen durch die Verwendung von Dienstprinzipalprofilen steigt mit dem Bedarf an Skalierung und der Notwendigkeit, die höchsten Sicherheits- und Mandantenisolationsebenen zu erreichen.

Sie können die Power BI-Einbettung durch zwei verschiedene Einbettungsszenarien erreichen: Einbetten für Ihre Organisation und Einbetten für Ihre Kund*innen.

Das Szenario Einbetten für Ihre Organisation findet Anwendung, wenn die Zielgruppe der App interne Benutzer*innen umfasst. Interne Benutzer*innen verfügen über Organisationskonten und müssen sich mit Microsoft Entra ID (ehemals Azure Active Directory) authentifizieren. In diesem Szenario handelt es sich bei Power BI um Software-as-a-Service (SaaS). Dieses Szenario wird manchmal auch als Benutzer besitzt die Daten bezeichnet.

Das Szenario Einbetten für Ihre Kund*innen findet Anwendung, wenn die Zielgruppe der App externe Benutzer*innen umfasst. Die Anwendung übernimmt die Authentifizierung der Benutzer*innen. Für den Zugriff auf Power BI-Inhalte verwendet die Anwendung eine Einbettungsidentität (Microsoft Entra-Dienstprinzipal oder Masterbenutzerkonto), um sich bei Microsoft Entra zu authentifizieren. In diesem Szenario handelt es sich bei Power BI um Plattform-as-a-Service (PaaS). Dieses Szenario wird manchmal auch als Die App besitzt die Daten bezeichnet.

Hinweis

Es ist wichtig zu verstehen, dass das Feature „Dienstprinzipalprofile“ für die Verwendung mit dem Szenario Einbetten für Ihre Kund*innen entwickelt wurde. Dies liegt daran, dass dieses Szenario ISVs und Unternehmensorganisationen die Möglichkeit bietet, eine große Anzahl von Benutzer*innen und Kundenmandanten in größerem Umfang einzubetten.

Entwicklung von mehrinstanzenfähigen Anwendungen

Wenn Sie mit Microsoft Entra vertraut sind, denken Sie beim Wort Mandant vermutlich an einen Microsoft Entra-Mandanten. Das Konzept eines Mandanten unterscheidet sich jedoch im Kontext der Erstellung einer Mehrinstanzenfähigkeitslösung, die Power BI-Inhalte einbettet. In diesem Kontext wird ein Kundenmandant im Namen jedes Kunden bzw. jeder Kundin erstellt, für den bzw. die die Anwendung Power BI-Inhalte mithilfe des Szenarios Einbetten für Ihre Kund*innen einbettet. In der Regel stellen Sie für jeden Kundenmandanten einen einzelnen Power BI-Arbeitsbereich bereit.

Um eine skalierbare mehrinstanzenfähige Lösung zu erstellen, muss die Erstellung neuer Kundenmandanten automatisiert werden können. Die Bereitstellung eines neuen Kundenmandanten umfasst in der Regel das Schreiben von Code, der die Power BI REST-API verwendet, um einen neuen Power BI-Arbeitsbereich zu erstellen, semantische Modelle (früher als Datensätze bekannt) durch den Import von Power BI Desktop (.pbix)-Dateien zu erstellen, Datenquellenparameter zu aktualisieren, Anmeldeinformationen für die Datenquelle festzulegen und die geplante Aktualisierung des Semantikmodells einzurichten. Das folgende Diagramm zeigt, wie Sie Power BI-Elemente wie Berichte und Semantikmodelle zu Arbeitsbereichen hinzufügen können, um Kundenmandanten einzurichten.

Diagram that shows a setup for three tenants. Each tenant has its own data source and workspace.

Wenn Sie eine Anwendung entwickeln, die das Szenario Einbetten für Ihre Kund*innen verwendet, ist es möglich, Aufrufe der Power BI-REST-API mithilfe einer Einbettungsidentität durchzuführen. Bei dieser handelt es sich entweder um ein Masterbenutzerkonto oder einen Dienstprinzipal. Es empfiehlt sich, für Produktionsanwendungen einen Dienstprinzipal zu verwenden. Dieser bietet die höchste Sicherheit und ist aus diesem Grund der von Microsoft Entra empfohlene Ansatz. Außerdem unterstützt er eine bessere Automatisierung und Skalierung, und es gibt weniger Verwaltungsaufwand. Allerdings sind für die Einrichtung und Verwaltung Power BI-Administratorrechte erforderlich.

Durch die Verwendung eines Dienstprinzipals können Sie häufige Probleme im Zusammenhang mit Masterbenutzerkonten vermeiden, z. B. Authentifizierungsfehler in Umgebungen, in denen sich Benutzer mithilfe der mehrstufigen Authentifizierung (Multi-Factor Authentication, MFA) anmelden müssen. Der Einsatz eines Dienstprinzipals entspricht auch der Idee, dass das Szenario Einbetten für Ihre Kund*innen auf der Einbettung von Power BI-Inhalten basiert, indem eine PaaS-Strategie im Gegensatz zu einer SaaS-Strategie verwendet wird.

Beschränkung auf 1.000 Arbeitsbereiche

Wenn Sie eine Mehrinstanzenumgebung entwerfen, für die Sie das Szenario Einbetten für Ihre Kund*innen gewählt haben, sollten Sie bedenken, dass die Einbettungsidentität nur auf höchstens 1.000 Arbeitsbereiche zugreifen kann. Der Power BI-Dienst schränkt den Zugriff ein, um eine gute Leistung bei REST-API-Aufrufen zu gewährleisten. Der Grund für diese Einschränkung hängt damit zusammen, wie Power BI sicherheitsbezogene Metadaten für einzelne Identitäten verwaltet.

Power BI verwendet Metadaten, um die Arbeitsbereiche und Arbeitsbereichselemente nachzuverfolgen, auf die eine Identität zugreifen kann. In der Tat muss Power BI eine separate Zugriffssteuerungsliste (Access Control List, ACL) für jede Identität im Autorisierungssubsystem verwalten. Wenn eine Identität einen REST-API-Aufruf für den Zugriff auf einen Arbeitsbereich vornimmt, muss Power BI eine Sicherheitsüberprüfung für die ACL der Identität durchführen, um sicherzustellen, dass diese autorisiert ist. Die Zeit, die zum Ermitteln benötigt wird, ob der Zielarbeitsbereich innerhalb der ACL liegt, nimmt mit zunehmender Anzahl von Arbeitsbereichen exponentiell zu.

Hinweis

Power BI erzwingt die Einschränkung auf 1.000 Arbeitsbereiche nicht über Code. Wenn Sie dies versuchen, fügen Sie zu mehr als 1.000 Arbeitsbereichen eine Einbettungsidentität hinzu. Sie werden sehen, dass dann REST-API-Aufrufe weiterhin erfolgreich ausgeführt werden. Ihre Anwendung wechselt jedoch in einen nicht unterstützten Zustand. Dies kann Auswirkungen haben, wenn Sie versuchen, Hilfe vom Microsoft-Support anzufordern.

Stellen Sie sich ein Szenario vor, in dem jeweils zwei mehrinstanzenfähige Anwendungen für die Verwendung eines einzelnen Dienstprinzipals eingerichtet wurden. Angenommen, die erste Anwendung hat 990 Arbeitsbereiche erstellt, während die zweite Anwendung 1.010 Arbeitsbereiche erstellt hat. Aus Supportsicht liegt die erste Anwendung innerhalb der unterstützten Grenzen, die zweite Anwendung aber nicht.

Vergleichen Sie nun diese beiden Anwendungen ausschließlich in Bezug auf die Leistung. Es gibt keinen so großen Unterschied, da die ACLs für beide Dienstprinzipale die Metadaten für ihre ACLs bis zu einem Punkt ansteigen lassen, an dem die Leistung bis zu einem gewissen Grad beeinträchtigt wird.

Dies ist die wichtigste Beobachtung: Die Anzahl der Arbeitsbereiche, die von einem Dienstprinzipal erstellt werden, wirkt sich direkt auf die Leistung und Skalierbarkeit aus. Ein Dienstprinzipal, der Mitglied von 100 Arbeitsbereichen ist, führt REST-API-Aufrufe schneller aus als ein Dienstprinzipal, der Mitglied von 1.000 Arbeitsbereichen ist. Gleichermaßen führt ein Dienstprinzipal, der Mitglied von 10 Arbeitsbereichen ist, REST-API-Aufrufe schneller aus als ein Dienstprinzipal, der Mitglied von 100 Arbeitsbereichen ist.

Wichtig

Aus Sicht der Leistung und Skalierbarkeit ist die optimale Anzahl von Arbeitsbereichen, bei denen ein Dienstprinzipal Mitglied ist, genau eins.

Verwalten der Isolation für Semantikmodelle und Datenquellenanmeldeinformationen

Ein weiterer wichtiger Aspekt beim Entwerfen einer mehrinstanzenfähigen Anwendung ist die Isolierung von Kundenmandanten. Es ist wichtig, dass Benutzer*innen aus einem Kundenmandanten keine Daten angezeigt werden, die zu einem anderen Kundenmandanten gehören. Daher müssen Sie wissen, wie Sie den Semantikmodellbesitz und die Anmeldeinformationen für die Datenquelle verwalten müssen.

Besitz des semantischen Modells

Jedes Power BI-Semantikmodell verfügt über einen einzelnen Besitzenden, bei dem es sich entweder um ein Benutzerkonto oder einen Dienstprinzipal handelt. Der Besitz des semantischen Modells ist erforderlich, um geplante Aktualisierungs- und Semantikmodellparameter einzurichten.

Tipp

Im Power BI-Dienst können Sie bestimmen, wer der Besitzer des semantischen Modells ist, indem Sie die Semantikmodelleinstellungen öffnen.

Bei Bedarf können Sie den Besitz des Semantikmodells auf ein anderes Benutzerkonto oder einen anderen Dienstprinzipal übertragen. Sie können dies im Power BI-Dienst oder mithilfe des REST-API-Vorgangs TakeOver durchführen. Wenn Sie eine Power BI Desktop-Datei importieren, um ein neues Semantikmodell mithilfe eines Dienstprinzipals zu erstellen, wird der Dienstprinzipal automatisch als Semantikmodellbesitzer festgelegt.

Anmeldeinformationen für die Datenquelle

Um ein Semantikmodell mit der zugrunde liegenden Datenquelle zu verbinden, muss der Besitzer des semantischen Modells Datenquellenanmeldeinformationen festlegen. Die Anmeldeinformationen für die Datenquelle werden von Power BI verschlüsselt und zwischengespeichert. Ab da verwendet Power BI diese Anmeldeinformationen, um sich bei der zugrunde liegenden Datenquelle zu authentifizieren, wenn die Daten aktualisiert werden (für Importspeichertabellen) oder beim Ausführen von Passthroughabfragen (für DirectQuery-Speichertabellen).

Es wird empfohlen, bei der Bereitstellung eines neuen Kundenmandanten ein allgemeines Entwurfsmuster anzuwenden. Sie können unter Verwendung der Identität des Dienstprinzipals eine Reihe von REST-API-Aufrufen ausführen:

  1. Erstellen eines neuen Arbeitsbereichs
  2. Ordnen Sie den neuen Arbeitsbereich einer dedizierten Kapazität zu.
  3. Importieren Sie eine Power BI Desktop-Datei, um ein Semantikmodell zu erstellen.
  4. Legen Sie die Quellanmeldeinformationen für das Semantikmodell fest.

Nach Abschluss dieser REST-API-Aufrufe hat der Dienstprinzipal einen Administratorzugriff auf den neuen Arbeitsbereich und ist der Besitzer des Semantikmodells und der Datenquellenanmeldeinformationen.

Wichtig

Es ist ein weit verbreiteter Irrglaube, dass die Berechtigungsnachweise für semantische Modelldatenquellen auf Arbeitsbereichsebene skaliert sind. Das stimmt aber nicht. Anmeldeinformationen für die Datenquelle gelten für den Dienstprinzipal (oder das Benutzerkonto), und dieser Geltungsbereich erstreckt sich auf alle Power BI-Arbeitsbereiche im Microsoft Entra-Mandanten.

Es ist möglich, dass ein Dienstprinzipal Anmeldeinformationen für eine Datenquelle erstellt, die von Semantikmodellen in verschiedenen Arbeitsbereichen für Kundenmandanten gemeinsam verwendet werden, wie im folgenden Diagramm dargestellt.

Diagram that shows a setup for two tenants. Each tenant share the same data source credentials.

Wenn Anmeldeinformationen für die Datenquelle von Semantikmodellen freigegeben werden, die zu verschiedenen Kundenmandanten gehören, sind die Kundenmandanten nicht vollständig isoliert.

Entwurfsstrategien vor der Verfügbarkeit von Dienstprinzipalprofilen

Es kann hilfreich sein, die Entwurfsstrategien vor der Einführung des Dienstprinzipalprofils zu verstehen, um die Notwendigkeit dieses Features zu erkennen. Vor diesem Zeitpunkt haben Entwickler*innen mehrinstanzenfähige Anwendungen mithilfe einer der folgenden drei Entwurfsstrategien erstellt:

  • Einzelner Dienstprinzipal
  • Dienstprinzipalpooling
  • Ein Dienstprinzipal pro Arbeitsbereich

Es gibt bei jeder dieser Entwurfsstrategien Vor- und Nachteile.

Bei der Entwurfsstrategie eines einzelnen Dienstprinzipals ist die einmalige Erstellung einer Microsoft Entra-App-Registrierung erforderlich. Daher ist der Verwaltungsaufwand geringer als bei den anderen beiden Entwurfsstrategien, da nicht mehrere Microsoft Entra-App-Registrierungen erstellt werden müssen. Diese Strategie ist auch am einfachsten, da Sie keinen zusätzlichen Code schreiben müssen, der den aufrufenden Kontext zwischen Dienstprinzipalen wechselt, wenn REST-API-Aufrufe ausgeführt werden. Ein Problem bei dieser Entwurfsstrategie ist jedoch, dass sie nicht skalierbar ist. Es wird nur eine Mehrinstanzenfähigkeitsumgebung unterstützt, die bis zu 1.000 Arbeitsbereiche umfassen kann. Außerdem wird die Leistung sicher beeinträchtigt, da dem Dienstprinzipal Zugriff auf eine größere Anzahl von Arbeitsbereichen gewährt wird. Zudem gibt es ein Problem mit der Kundenmandantenisolation, da der einzelne Dienstprinzipal der Besitzer jedes Semantikmodells und aller Datenanmeldeinformationen für alle Kundenmandanten wird.

Die Entwurfsstrategie für Dienstprinzipalpooling wird häufig verwendet, um die Beschränkung auf 1.000 Arbeitsbereiche zu umgehen. Dabei kann die Anwendung auf eine beliebige Anzahl von Arbeitsbereichen skaliert werden, indem dem Pool die entsprechende Anzahl von Dienstprinzipalen hinzugefügt wird. Beispielsweise ermöglicht ein Pool von fünf Dienstprinzipalen das Skalieren auf bis zu 5.000 Arbeitsbereiche. Ein Pool von 80 Dienstprinzipalen ermöglicht das Skalieren auf bis zu 80.000 Arbeitsbereiche usw. Obwohl bei dieser Strategie auf eine große Anzahl von Arbeitsbereichen skaliert werden kann, hat sie mehrere Nachteile. Erstens muss zusätzlicher Code geschrieben und Metadaten gespeichert werden, um bei REST-API-Aufrufen einen Kontextwechsel zwischen den Dienstprinzipalen zu ermöglichen. Des Weiteren ist der Verwaltungsaufwand höher, da Sie Microsoft Entra-App-Registrierungen erstellen müssen, wenn Sie die Anzahl der Dienstprinzipale im Pool erhöhen möchten.

Darüber hinaus ist die Pooling-Strategie für Dienstprinzipale nicht auf Leistung ausgelegt, da Dienstprinzipale Mitglieder von Hunderten von Arbeitsbereichen werden können. Dies ist auch aus Sicht der Kundenmandantenisolation nicht ideal, da die Dienstprinzipale Besitzer von Semantikmodellen und Datenanmeldeinformationen werden können, die von Kundenmandanten gemeinsam genutzt werden.

Die Entwurfsstrategie für einen Dienstprinzipal pro Arbeitsbereich umfasst die Erstellung eines Dienstprinzipals für jeden Kundenmandanten. Theoretisch ist diese Strategie die beste Lösung, da sie die Leistung von REST-API-Aufrufen optimiert und gleichzeitig eine echte Isolation für Semantikmodelle und Anmeldeinformationen für die Datenquelle auf Arbeitsbereichsebene bietet. Doch was in der Theorie am besten funktioniert, ist in der Praxis nicht immer die beste Lösung. Das liegt daran, dass die Anforderung, einen Dienstprinzipal für jeden Kundenmandanten zu erstellen, für viele Organisationen unpraktisch ist. Das liegt daran, dass einige Organisationen offizielle Genehmigungsprozesse haben oder bei der Erstellung von Microsoft Entra-App-Registrierungen übermäßigen bürokratischen Aufwand beitreiben. Folglich kann es unmöglich sein, einer benutzerdefinierten Anwendung die Berechtigung zu erteilen, die sie benötigt, um Microsoft Entra-App-Registrierungen bedarfsgesteuert und auf die für Ihre Lösung erforderliche automatisierte Weise zu erstellen.

In weniger häufigen Szenarien, in denen einer benutzerdefinierten Anwendung die entsprechenden Berechtigungen erteilt wurden, kann sie die Microsoft Graph-API verwenden, um bei Bedarf Microsoft Entra-App-Registrierungen zu erstellen. Die Entwicklung und Bereitstellung der benutzerdefinierten Anwendung ist jedoch häufig aufwendig, da sie die Anmeldeinformationen für die Authentifizierung für jede Microsoft Entra-D-App-Registrierung irgendwie nachverfolgen muss. Außerdem muss sie Zugriff auf diese Anmeldeinformationen erhalten, wenn sie sich authentifizieren und Zugriffstoken für einzelne Dienstprinzipale abrufen muss.

Dienstprinzipalprofile

Das Feature der Dienstprinzipalprofile wurde entwickelt, um Ihnen das Verwalten von Organisationsinhalten in Power BI und die effizientere Nutzung Ihrer Kapazitäten zu erleichtern. Sie helfen bei der Bewältigung von drei spezifischen Herausforderungen, die den geringsten Aufwand für die Entwickler*innen bedeuten. Zu diesen Herausforderungen gehören:

  • Skalieren auf eine große Anzahl von Arbeitsbereichen
  • Optimieren der Leistung von REST-API-Aufrufen
  • Isolieren von Semantikmodellen und Datenquellen-Anmeldeinformationen auf Kundenmandantenebene.

Wenn Sie eine mehrinstanzenfähige Anwendung mithilfe von Dienstprinzipalprofilen entwerfen, können Sie von den Stärken der drei Entwurfsstrategien (beschrieben im vorherigen Abschnitt) profitieren und gleichzeitig damit einhergehende Schwachstellen vermeiden.

Dienstprinzipalprofile sind lokale Konten, die im Kontext von Power BI erstellt werden. Ein Dienstprinzipal über den REST-API-Vorgang Profiles neue Dienstprinzipalprofile erstellen. Ein Dienstprinzipal kann einen eigenen Satz von Dienstprinzipalprofilen für eine benutzerdefinierte Anwendung erstellen und verwalten, wie im folgenden Diagramm dargestellt.

Diagram that shows a service principal creating three service principal profiles in Power BI.

Zwischen einem Dienstprinzipal und den Dienstprinzipalprofilen, die er erstellt, besteht immer eine über-/untergeordnete Beziehung. Sie können kein Dienstprinzipalprofil als eigenständige Entität erstellen. Vielmehr erstellen Sie ein Dienstprinzipalprofil mithilfe eines bestimmten Dienstprinzipals, welcher als übergeordnetes Profil dient. Zudem ist ein Dienstprinzipalprofil nie für Benutzerkonten oder andere Dienstprinzipale sichtbar. Ein Dienstprinzipalprofil kann nur vom Dienstprinzipal angezeigt und verwendet werden, von dem es erstellt wurde.

Microsoft Entra hat keine Informationen zu Dienstprinzipalprofilen

Zwar sind der Dienstprinzipal selbst und die ihm zugrunde liegende Microsoft Entra-App-Registrierung in Microsoft Entra bekannt, aber zu Dienstprinzipalprofilen liegen Microsoft Entra ID keine Informationen vor. Das liegt daran, dass Dienstprinzipalprofile von Power BI erstellt werden und nur im Subsystem des Power BI-Diensts vorhanden sind, das die Sicherheit und Autorisierung von Power BI steuert.

Die Tatsache, dass Dienstprinzipalprofile in Microsoft Entra ID nicht bekannt sind, hat sowohl Vor- als auch Nachteile. Der Hauptvorteil besteht darin, dass eine Anwendung für das Szenario Einbetten für Ihre Kund*innen keine speziellen Microsoft Entra-Berechtigungen benötigt, um Dienstprinzipalprofile zu erstellen. Dies bedeutet auch, dass die Anwendung eine Reihe von lokalen Identitäten erstellen und verwalten kann, die von Microsoft Entra getrennt sind.

Dies hat aber auch Nachteile. Da Dienstprinzipalprofile in Microsoft Entra nicht bekannt sind, können Sie auch kein Dienstprinzipalprofil zu einer Microsoft Entra-Gruppe hinzufügen, um ihm implizit Zugriff auf einen Arbeitsbereich zu gewähren. Außerdem können externe Datenquellen, z. B. eine Azure SQL-Datenbank oder Azure Synapse Analytics, Dienstprinzipalprofile beim Herstellen einer Verbindung mit einer Datenbank nicht als Identität erkennen. Daher ist die Entwurfsstrategie mit einem Dienstprinzipal pro Arbeitsbereich (wobei ein Dienstprinzipal für jeden Kundenmandanten erstellt wird) möglicherweise die bessere Wahl, wenn eine Verbindung mit diesen Datenquellen über einen separaten Dienstprinzipal mit eindeutigen Anmeldeinformationen für jeden Kundenmandanten hergestellt werden muss.

Dienstprinzipalprofile sind erstklassige Sicherheitsprinzipale.

Zwar sind Dienstprinzipalprofile in Microsoft Entra nicht bekannt, Power BI erkennt sie jedoch als erstklassige Sicherheitsprinzipale. Genau wie ein Benutzerkonto oder ein Dienstprinzipal lassen sich Dienstprinzipalprofile zu einer Arbeitsbereichsrolle hinzufügen (als Administrator*in) oder als Mitglied). Sie können es auch als Semantikmodellbesitzer und Besitzer von Datenquellen-Anmeldeinformationen festlegen. Aus diesen Gründen ist das Erstellen eines neuen Dienstprinzipalprofils für jeden neuen Kundenmandanten eine bewährte Methode.

Diagram that shows multiple customer tenants, each with their own service principal profiles.

Tipp

Wenn Sie eine Anwendung für das Szenario Einbetten für Ihre Kund*innen mithilfe von Dienstprinzipalprofilen entwickeln, müssen Sie nur eine einzelne Microsoft Entra-App-Registrierung erstellen, um für Ihre Anwendung einen einzelnen Dienstprinzipal bereitzustellen. Dieser Ansatz senkt den Verwaltungsaufwand im Vergleich zu anderen Entwurfsstrategien für Mehrinstanzenfähigkeit erheblich, bei denen nach der Bereitstellung der Anwendung in der Produktion laufend zusätzliche Microsoft Entra-App-Registrierungen erstellt werden müssen.

Ausführen von REST-API-Aufrufen als Dienstprinzipalprofil

Ihre Anwendung kann REST-API-Aufrufe mithilfe der Identität eines Dienstprinzipalprofils ausführen. Somit kann es eine Reihe von REST-API-Aufrufen ausführen, um einen neuen Kundenmandanten bereitzustellen und einzurichten.

  1. Wenn ein Dienstprinzipalprofil einen neuen Arbeitsbereich erstellt, fügt Power BI dieses Profil automatisch als Arbeitsbereichsadministrator hinzu.
  2. Wenn ein Dienstprinzipalprofil eine Power BI Desktop-Datei importiert, um ein semantisches Modell zu erstellen, legt Power BI dieses Profil als Semantikmodellbesitzer fest.
  3. Wenn ein Dienstprinzipalprofil Datenquellen-Anmeldeinformationen festlegt, legt Power BI dieses Profil als Besitzer der Datenquellen-Anmeldeinformationen fest.

Es ist wichtig zu verstehen, dass ein Dienstprinzipal in Power BI über eine Identität verfügt, die sich von den Identitäten seiner Profile unterscheidet. So haben Sie als Entwickler*in die Wahl. Sie können REST-API-Aufrufe mithilfe der Identität eines Dienstprinzipalprofils ausführen. Alternativ können Sie REST-API-Aufrufe auch ohne Profil ausführen, wobei die Identität des übergeordneten Dienstprinzipals verwendet wird.

Es wird empfohlen, REST-API-Aufrufe als übergeordneter Dienstprinzipal auszuführen, wenn Sie Dienstprinzipalprofile erstellen, anzeigen oder löschen. Zudem sollten Sie das Dienstprinzipalprofil verwenden, um alle anderen REST-API-Aufrufe auszuführen. Diese anderen Aufrufe können Arbeitsbereiche erstellen, Power BI Desktop-Dateien importieren, Semantikmodellparameter aktualisieren und Anmeldeinformationen für Datenquellen festlegen. Sie können auch Metadaten von Arbeitsbereichselementen abrufen und Einbettungstoken generieren.

Nehmen wir ein Beispiel, bei dem Sie einen Kundenmandanten für einen Kunden namens Contoso einrichten müssen. Im ersten Schritt wird ein REST-API-Aufruf ausgeführt, um ein Dienstprinzipalprofil zu erstellen, dessen Anzeigename auf Contoso festgelegt ist. Dieser Aufruf erfolgt über die Identität des Dienstprinzipals. Alle verbleibenden Einrichtungsschritte verwenden das Dienstprinzipalprofil, um die folgenden Aufgaben auszuführen:

  1. Erstellen eines Arbeitsbereichs.
  2. Zuordnen einer Kapazität zu einem Arbeitsbereich
  3. Importieren einer Power BI Desktop-Datei
  4. Legen Sie Semantikmodellparameter fest.
  5. Bearbeiten der Datenquellen-Anmeldeinformationen
  6. Einrichten einer geplanten Datenaktualisierung

Es ist wichtig zu wissen, dass der Zugriff auf den Arbeitsbereich und seine Inhalte über die Identität des Dienstprinzipalprofils erfolgen muss, das zum Erstellen des Kundenmandanten verwendet wurde. Außerdem ist zu beachten, dass der übergeordnete Dienstprinzipal keinen Zugriff auf den Arbeitsbereich oder dessen Inhalt benötigt.

Tipp

Denken Sie daran: Verwenden Sie bei REST-API-Aufrufen den Dienstprinzipal, um Dienstprinzipalprofile zu erstellen und zu verwalten, und verwenden Sie das Dienstprinzipalprofil, um Power BI-Inhalte zu erstellen, einzurichten und darauf zuzugreifen.

Verwenden der REST-API-Vorgänge der Profile

Die Rest-API-Vorgangsgruppe Profile umfasst Vorgänge, die Dienstprinzipalprofile erstellen und verwalten:

  • Create Profile
  • Delete Profile
  • Get Profile
  • Get Profiles
  • Update Profile

Erstellen eines Dienstprinzipalprofils

Verwenden Sie den Rest-API-Vorgang Profil erstellen, um ein Dienstprinzipalprofil zu erstellen. Sie müssen die Eigenschaft displayName im Anforderungstext festlegen, um einen Anzeigenamen für den neuen Mandanten anzugeben. Der Wert muss für alle Profile des Dienstprinzipals eindeutig sein. Der Aufruf schlägt fehl, wenn bereits ein anderes Profil mit diesem Anzeigenamen für den Dienstprinzipal vorhanden ist.

Ein erfolgreicher Aufruf gibt die Eigenschaft id zurück, bei der es sich um eine GUID handelt, die das Profil darstellt. Bei der Entwicklung von Anwendungen, die Dienstprinzipalprofile verwenden, ist es sinnvoll, die Anzeigenamen der Profile und ihre ID-Werte in einer benutzerdefinierten Datenbank zu speichern. Auf diese Weise kann Ihre Anwendung die IDs ganz einfach abrufen.

Wenn Sie mit dem Power BI .NET-SDK programmieren, können Sie die Methode Profiles.CreateProfile verwenden, die ein Objekt ServicePrincipalProfile zurückgibt, das das neue Profil darstellt. Dies erleichtert die Bestimmung des Eigenschaftswerts id.

Hier sehen Sie ein Beispiel für das Erstellen eines Dienstprinzipalprofils und das Gewähren von Zugriff auf den Arbeitsbereich.

// Create a service principal profile
string profileName = "Contoso";

var createRequest = new CreateOrUpdateProfileRequest(profileName);
var profile = pbiClient.Profiles.CreateProfile(createRequest);

// Retrieve the ID of the new profile
Guid profileId = profile.Id;

// Grant workspace access
var groupUser = new GroupUser {
    GroupUserAccessRight = "Admin",
    PrincipalType = "App",
    Identifier = ServicePrincipalId,
    Profile = new ServicePrincipalProfile {
        Id = profileId
    }
};

pbiClient.Groups.AddGroupUser(workspaceId, groupUser);

Im Power BI-Dienst können Sie im Bereich Zugriff des Arbeitsbereichs bestimmen, welche Identitäten, einschließlich Sicherheitsprinzipalen, Zugriff haben.

Screenshot that shows a screenshot of the workspace Access pane. It shows a service principal profile with a display name of Contoso that has admin permission.

Löschen eines Dienstprinzipalprofils

Verwenden Sie den Rest-API-Vorgang Profil löschen, um ein Dienstprinzipalprofil zu löschen. Dieser Vorgang kann nur vom übergeordneten Dienstprinzipal aufgerufen werden.

Wenn Sie mit dem Power BI .NET-SDK programmieren, können Sie die Methode Profiles.DeleteProfile verwenden.

Abrufen aller Dienstprinzipalprofile

Verwenden Sie den Rest-API-Vorgang Profile abrufen, um eine Liste der Dienstprinzipalprofile abzurufen, die zum aufrufenden Dienstprinzipal gehören. Dieser Vorgang gibt JSON-Nutzdaten zurück, die die Eigenschaften id und displayName der einzelnen Dienstprinzipalprofile enthält.

Wenn Sie mit dem Power BI .NET-SDK programmieren, können Sie die Methode Profiles.GetProfiles verwenden.

Ausführen von REST-API-Aufrufen als Dienstprinzipalprofil

Es gibt zwei Anforderungen für das Ausführen von REST-API-Aufrufen mithilfe eines Dienstprinzipalprofils:

  • Sie müssen das Zugriffstoken für den übergeordneten Dienstprinzipal im Header Autorisierung übergeben.
  • Sie müssen einen Header namens X-PowerBI-profile-id mit dem Wert der ID des Dienstprinzipalprofils einschließen.

Wenn Sie das Power BI .NET-SDK verwenden, können Sie den Headerwert X-PowerBI-profile-id explizit festlegen, indem Sie die ID des Dienstprinzipalprofils übergeben.

// Create the Power BI client
var tokenCredentials = new TokenCredentials(GetACcessToken(). "Bearer");
var uriPowerBiServiceApiRoot = new Uri(uriPowerBiServiceApiRoot);
var pbiClient = new PowerBIClient(uriPowerBiServiceApiRoot, tokenCredentials);

// Add X-PowerBI-profile-id header for service principal profile
string profileId = "11111111-1111-1111-1111-111111111111";
pbiClient.HttpClient.DefaultRequestHeaders.Add("X-PowerBI-profile-id", profileId);

// Retrieve workspaces by using the identity of service principal profile
var workspaces = pbiClient.Groups.GetGroups();

Wie im obigen Beispiel gezeigt, ist es nach dem Hinzufügen des Headers X-PowerBI-profile-id zum Objekt PowerBIClient einfach, Methoden wie Groups.GetGroups aufzurufen, sodass sie mithilfe des Dienstprinzipalprofils ausgeführt werden.

Es gibt eine bequemere Möglichkeit, den Header X-PowerBI-profile-id für ein PowerBIClient-Objekt festzulegen. Sie können das Objekt initialisieren, indem Sie die ID des Profils an den Konstruktor übergeben.

// Create the Power BI client
string profileId = "11111111-1111-1111-1111-111111111111";

var tokenCredentials = new TokenCredentials(GetACcessToken(). "Bearer");
var uriPowerBiServiceApiRoot = new Uri(uriPowerBiServiceApiRoot);
var pbiClient = new PowerBiClient(uriPowerBiServiceApiRoot, tokenCredentials, profileId);

Beim Programmieren einer mehrinstanzenfähigen Anwendung müssen Sie wahrscheinlich zwischen der Ausführung von Aufrufen als übergeordneter Dienstprinzipal und der Ausführung von Aufrufen als Dienstprinzipalprofil wechseln. Ein sinnvoller Ansatz zur Handhabung des Kontextwechsels ist es, eine Variable auf Klassenebene zu deklarieren, die das Objekt PowerBIClient speichert. Anschließend können Sie eine Hilfsmethode erstellen, die die Variable mit dem entsprechenden Objekt festlegt.

// Class-level variable that stores the PowerBIClient object
private PowerBIClient pbiClient;

// Helper method that sets the correct PowerBIClient object
private void SetCallingContext(string profileId = "") {

    if (profileId.Equals("")) {
        pbiClient = GetPowerBIClient();    
    }
    else {
        pbiClient = GetPowerBIClientForProfile(new Guid(profileId));
    }
}

Wenn Sie ein Dienstprinzipalprofil erstellen oder verwalten müssen, können Sie die Methode SetCallingContext ohne Parameter aufrufen. So können Sie Profile erstellen und verwalten, indem Sie die Identität des Dienstprinzipals verwenden.

// Always create and manage profiles as the service principal
SetCallingContext();

// Create a service principal profile
string profileName = "Contoso";

var createRequest = new CreateOrUpdateProfileRequest(profileName);
var profile = pbiClient.Profiles.CreateProfile(createRequest);

Wenn Sie einen Arbeitsbereich für einen neuen Kundenmandanten erstellen und einrichten müssen, benötigen Sie dieses Code-as-a-Service-Prinzipalprofil. Daher sollten Sie die Methode SetCallingContext aufrufen, indem Sie die ID des Profils übergeben. Auf diese Weise können Sie den Arbeitsbereich erstellen, indem Sie die Identität des Dienstprinzipals verwenden.

// Always create and set up workspaces as a service principal profile
string profileId = "11111111-1111-1111-1111-111111111111";
SetCallingContext(profileId);

// Create a workspace
GroupCreationRequest request = new GroupCreationRequest(workspaceName);
Group workspace = pbiClient.Groups.CreateGroup(request);

Sobald Sie ein bestimmtes Dienstprinzipalprofil zum Erstellen und Konfigurieren eines Arbeitsbereichs verwendet haben, sollten Sie dasselbe Profil weiterhin zum Erstellen und Einrichten des Arbeitsbereichsinhalts verwenden. Es ist nicht erforderlich, die Methode SetCallingContext aufzurufen, um das Setup abzuschließen.

Entwicklerbeispiele

Es ist empfehlenswert, die Beispielanwendung mit dem Namen AppOwnsDataMultiTenant herunterzuladen.

Diese Beispielanwendung wurde mithilfe von .NET 6 und ASP.NET entwickelt und veranschaulicht, wie die in diesem Artikel beschriebenen Anleitungen und Empfehlungen angewendet werden. Sie können den Code durchgehen, um zu erfahren, wie Sie eine mehrinstanzenfähige Anwendung entwickeln können, die das Szenario Einbetten Ihrer Kund*innen mithilfe von Dienstprinzipalprofilen implementiert.

Zugehöriger Inhalt

Weitere Informationen zu diesem Artikel finden Sie in den folgenden Ressourcen: