Elementverweisvariablentyp (Vorschau)

Um Flexibilität und Skalierbarkeit zu verbessern, führen wir erweiterte Variablen zusammen mit den vorhandenen grundlegenden Variablentypen ein. Diese erweiterten Variablen sind so konzipiert, dass sie wichtige Anforderungen erfüllen, z. B. die Parametrisierung externer und interner Verbindungen (z. B. Snowflake, AWS, OneLake).

Eine Elementverweisvariable ist ein erweiterter Variablentyp, der in der Fabric Variable Library verwendet wird, um einen Verweis auf ein vorhandenes Fabric-Element, wie beispielsweise ein Lakehouse, ein Notizbuch oder eine Datenpipeline, zu speichern, indem die Arbeitsbereichs-ID und Element-ID gespeichert werden. Dieser Typ von Variable ermöglicht die interne Verbindungsparameterisierung, sodass Entwickler Elemente dynamisch mit bestimmten Fabric-Elementen basierend auf der Bereitstellungsphase oder dem Arbeitsbereichskontext verknüpfen können.

Verwendung

Eine Elementverweisvariable kann wie andere Variablen in einer Variablenbibliothek verwendet werden.

1. Anmelden bei Microsoft Fabric
2. Navigieren Sie zu Ihrem Arbeitsbereich und Ihrer Variablenbibliothek
3. Wählen Sie oben +Neue Variable aus.
4. Geben Sie einen Namen für die Variable ein, wählen Sie einen Elementverweis für den Typ aus, und klicken Sie dann auf die ... , um einen Wert auszuwählen.
5. Dadurch wird ein Dialogfeld geöffnet, um das gewünschte Element auszuwählen. Es werden alle Elemente angezeigt, für die Sie über Berechtigungen verfügen, die für die Auswahl verfügbar sind. Verwenden Sie den Explorer auf der linken Seite, um die Liste nach Arbeitsbereich zu filtern. Verwenden Sie den Filter in der oberen rechten Ecke, um nach Typ zu filtern.

6. Nach der Auswahl wird sie auf der Varlib-Seite wie folgt angezeigt – als schreibgeschützte Komponente, die den Namen des Elements anzeigt.

Wenn Sie einen Elementverweis bearbeiten müssen oder den Wert doppelt überprüfen müssen:

• um weitere Details anzuzeigen, klicken Sie auf den Wert.
• um diesen Wert oder die Werte anderer Wertsätze zu bearbeiten, klicken Sie auf die Schaltfläche neben dem Wert.

Funktionsweise

Der Wert einer Elementreferenzvariablen ist im Wesentlichen ein statischer Zeiger auf ein Fabric-Element, das durch arbeitsbereichs-ID + Element-ID identifiziert wird. Der Wert wird als Ein paar GUIDs gespeichert, die dem Arbeitsbereich des Zielelements und dem Element selbst entsprechen. Ein Verweis kann z. B. intern gespeichert werden als:

• WorkspaceID = aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
• ItemID = 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Diese beiden IDs identifizieren das referenzierte Element eindeutig.

Beachten Sie beim Arbeiten mit Elementverweise Folgendes:

• Elementverweise ermöglichen die interne Verbindungsparameterisierung, sodass Entwickler Elemente dynamisch mit bestimmten Fabric-Ressourcen basierend auf der Bereitstellungsphase oder dem Arbeitsbereichskontext verknüpfen können.
• Der Verweis ist statisch, zeigt auf ein bestimmtes Element und passt sich nicht automatisch über verschiedene Umgebungen hinweg an.
• Verwenden Sie für phasenspezifische Variationen Wertsätze, bei denen jeder Satz auf ein anderes statisches Element verweisen kann (z. B. unterschiedliche Seehäuser pro Stufe).
• Alle Werte über Wertsätze hinweg sollten demselben Elementtyp entsprechen, um Kompatibilität zu gewährleisten und Laufzeitfehler zu verhindern. Wir erzwingen jedoch nicht, dass derselbe Elementtyp über Wertsätze hinweg vorhanden ist.

Unterstützte Elemente

Es folgt eine Liste der Elemente, die derzeit mithilfe der Elementreferenz unterstützt werden:

• Tastenkombination für ein Seehaus
• Benutzerdatenfunktionen
• Laptop durch NotebookUtils

Hinweis

Durch %%configure wird das Notizbuch nicht unterstützt.

Einschränkungen

Derzeit können Sie nur auf Fabric-Elemente und semantische Modelle verweisen. Andere Power BI-Elemente, z. B. Datamarts, Dataflow Gen1 werden derzeit nicht unterstützt.

Zum Erstellen/Verwenden von Elementverweisen erforderliche Berechtigungen

Die Verwendung von Elementreferenzvariablen umfasst zwei Berechtigungsebenen:

• Erstellen/Bearbeiten – Zwar kann jeder Arbeitsbereich-Mitwirkende Variablenwerte ändern, aber eine Elementreferenzvariable erlaubt es Benutzern nur, Elemente als Werte festzulegen, für die sie Leseberechtigungen besitzen. Dies gilt für jeden Wert, den Standard-Aktivwertsatz oder andere Wertmengen. Beachten Sie, dass beim Speichern eines Variablenbibliothekselements eine Berechtigungsprüfung für die aktiven Werte von Elementverweisvariablen für den Benutzer ausgeführt wird, der das Element speichert, auch wenn diese Werte unverändert bleiben.
• Verwenden Sie eine Elementreferenzvariable – Beim Erstellen/Aktualisieren eines Verweises auf eine Variable in einem Consumerelement können Benutzer keinen Verweis auf eine Elementreferenzvariable festlegen, es sei denn, sie verfügen über mindestens READ-Berechtigung für das Element im aktiven Wertsatz.

Berechtigungsüberprüfung

Die Berechtigungsüberprüfung wird in den folgenden Anwendungsfällen ausgelöst:

• Bearbeiten Eines Variablenbibliothekselements mit Elementverweisvariablen Beim Bearbeiten überprüfen wir, ob die referenzierten Elemente vorhanden sind und dass der Benutzer mindestens Leseberechtigungen für alle Elementverweiswerte im aktiven Wertsatz hat, für die folgenden Szenarien:

• Benutzeroberfläche : Beim SPEICHERN des Variablenbibliothekselements wird eine Berechtigungsprüfung für die aktiven Werte von Elementverweisvariablen für den Benutzer ausgeführt, der das Element speichert, auch wenn diese Werte unverändert bleiben.

• APIs/Git-Update – Die Berechtigungsüberprüfung erfolgt während eines Updates und schlägt fehl, wenn keine Leseberechtigung für den aktiven Wert der Item-Ref im aktualisierten Arbeitsbereich vorhanden ist.

• Bereitstellung – Die Bereitstellung eines Variablenbibliothekselements schlägt fehl, wenn keine Leseberechtigung für den aktiven Wert des Zielarbeitsbereichs des Elementverweises vorhanden ist.

• Auf der Seite "Variablenbibliothek" (nur UI) können Benutzer mit Zugriff auf die Variablenbibliothek (WS-Viewer oder höher), die keine Berechtigungen für das Element in der referenzierten Variablen haben, deren Details in der Benutzeroberfläche nicht sehen. Stattdessen wird anstelle der Detailkomponente die Element-ID angezeigt, die von einer Daraufzeigernachricht begleitet wird.

• Erstellen/Bearbeiten der Elementreferenzvariable

  • Benutzeroberfläche : Beim Aktualisieren des Werts eines beliebigen Wertsatzes (Standard oder anderer Wert) kann der Benutzer ein Element aus einer Liste auswählen, in der nur Elemente angezeigt werden, für die er mindestens leseberechtigungen hat.
  • APIs/Git-Update oder -Bereitstellung – siehe oben das Element "Variable-Bibliothek bearbeiten".

• Verwenden der Elementverweisvariable in einem Verbraucherelement

  • Benutzeroberfläche – Erstellen eines Verweises auf Variable – Beim Erstellen eines Elements einen Verweis auf eine Variable "Elementverweis" mithilfe des Ui-Dialogfelds "Variable auswählen" (z. B. in Verknüpfung für Lakehouse und Datenpipeline) gibt es eine Überprüfung, dass der Benutzer, der den Verweis erstellt, mindestens leseberechtigung für die Elemente in den Variablen "Elementverweis" hat (die Überprüfung gilt nur für die aktiven Werte). Wenn nicht, sieht der Benutzer nur die Element-ID.

Verhalten in CI/CD-Pipelines und Bereitstellungsphasen

Die Variable Library ermöglicht CI/CD für Fabric-Inhalte in allen Umgebungen (Dev, Test, Prod) mithilfe von Elementreferenzvariablen für phasenspezifische Konfigurationen. Beachten Sie Folgendes:

Statische Verweise

• Elementverweise sind an einen bestimmten Arbeitsbereich und eine Element-ID gebunden.
• Beim Bereitstellen in eine neue Phase verweisen diese Verweise weiterhin auf den ursprünglichen Arbeitsbereich, es sei denn, sie werden manuell aktualisiert.
• Verwenden Sie für jede Phase mehrere Value-Sets, und aktivieren Sie den richtigen Satz manuell oder über API-Skripts.

Weitere Informationen finden Sie unter Wertsätze in Variablenbibliotheken.

Darstellung in Git und APIs

Die Variable-Bibliothek wird als Code verwaltet. Bei Verwendung von Git- oder REST-APIs weisen Elementreferenzvariablen ein klares JSON-Format auf. Alle Variablen erscheinen in der Definitionsdatei der Variablenbibliothek (gewöhnlich in Git als .json gespeichert), die Eigenschaften wie Name, Typ und Wert auflistet.

Für eine statische Elementverweisvariable ist der Wert eine strukturierte Darstellung der Daten für Arbeitsbereichs- und Element-IDs. Beispiel:

{
 "name": "MyDataLake",
 "note": "",
 "type": "ItemReference",
 "value": {
  "itemId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "workspaceId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
 }
}

 

Beachten Sie Folgendes beim Arbeiten über die API:

• Nur IDs werden gespeichert; Namen und Metadaten werden zur Laufzeit abgerufen oder in Fabric zwischengespeichert.
• Beim Erstellen oder Aktualisieren über die API müssen Sie die Arbeitsbereichs- und Element-IDs bereitstellen. Ungültige IDs verursachen Fehler.

Verwandte Inhalte

• Übersicht über die Variablenbibliothek
• Variablentypen
• Wertsätze
• Berechtigungen der Variablenbibliothek](./variable-library-permissions.md)