Type de variable de référence d’élément (préversion)

Pour améliorer la flexibilité et la scalabilité, nous introduisons des variables avancées en même temps que les types de variables de base existants. Ces variables avancées sont conçues pour répondre aux exigences clés, telles que la paramétrage des connexions externes et internes (par exemple, Snowflake, AWS, OneLake).

Une variable de référence d’élément est un type avancé de variable utilisée dans la bibliothèque de variables Fabric pour stocker une référence à un élément Fabric existant, tel qu’un lakehouse, un notebook ou un pipeline de données. Elle permet de conserver l’ID de l’espace de travail ainsi que l’ID de l’élément. Ce type de variable permet un paramétrage de connexion interne, ce qui permet aux développeurs de lier dynamiquement des éléments à des éléments Fabric spécifiques en fonction de l’étape de déploiement ou du contexte de l’espace de travail.

Guide pratique pour utiliser

Une variable de référence d’élément peut être utilisée comme d’autres variables dans une bibliothèque de variables.

1. Se connecter à Microsoft Fabric
2. Accédez à votre espace de travail et bibliothèque de variables
3. En haut, sélectionnez + Nouvelle variable
4. Indiquez un nom pour la variable, sélectionnez la référence d’élément pour le type, puis cliquez sur ... pour sélectionner une valeur.
5. Une boîte de dialogue s’ouvre pour sélectionner l’élément souhaité. Vous verrez tous les éléments sur lesquels vous avez des autorisations, disponibles à sélectionner. Utilisez l’Explorateur sur la gauche pour filtrer la liste par espace de travail. Utilisez le filtre dans le coin supérieur droit pour filtrer par type.

6. Une fois sélectionné, il s’affiche comme suit sur la page varlib, en tant que composant en lecture seule affichant le nom de l’élément.

Si vous avez besoin de modifier une référence d’élément ou de vérifier la valeur :

• pour afficher des détails supplémentaires, cliquez sur la valeur
• pour modifier cette valeur ou valeurs d’autres jeux de valeurs, cliquez sur le bouton en regard de la valeur.

Fonctionnement

La valeur d’une variable de référence d’élément est essentiellement un pointeur statique vers un élément Fabric identifié par ID d’espace de travail + ID d’élément. La valeur est stockée sous la forme d’une paire de GUID correspondant à l’espace de travail de l’élément cible et à l’élément lui-même. Par exemple, une référence peut être stockée en interne comme suit :

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

Ces deux ID identifient de manière unique l’élément référencé.

Gardez à l’esprit les éléments suivants lors de l’utilisation des références d’élément :

• Les références d’éléments permettent un paramétrage de connexion interne, ce qui permet aux développeurs de lier dynamiquement des éléments à des ressources Fabric spécifiques en fonction de l’étape de déploiement ou du contexte de l’espace de travail.
• La référence est statique, pointant vers un élément spécifique et ne s’ajuste pas automatiquement entre les environnements.
• Pour les variantes spécifiques à la phase, utilisez des ensembles de valeurs, où chaque ensemble peut pointer vers un élément statique différent (par exemple, différents lakehouses par phase).
• Toutes les valeurs entre les ensembles de valeurs doivent être du même type d’élément pour garantir la compatibilité et empêcher les erreurs d’exécution. Toutefois, nous n’appliquons pas le même type d’élément entre les jeux de valeurs.

Représentation dans Git et les API

La bibliothèque de variables est gérée en tant que code. À l’aide d’API Git ou REST, les variables de référence d’élément ont un format JSON clair. Toutes les variables apparaissent dans le fichier de définition de la bibliothèque de variables (stocké dans Git, généralement .json), qui répertorient les propriétés telles que le nom, le type et la valeur.

Pour une variable de référence d'élément (statique), la valeur est des données structurées pour les ID d’espace de travail et d’élément. Exemple :

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

 

N’oubliez pas ce qui suit lors de l’utilisation de l’API :

• Seuls les ID sont stockés ; les noms et les métadonnées sont récupérés au moment de l’exécution ou mis en cache dans Fabric.
• Lorsque vous effectuez une création ou une mise à jour via l’API, vous fournissez les identifiants de l’espace de travail et de l’élément. Les ID non valides provoquent des erreurs.

Éléments pris en charge

Voici une liste d’éléments actuellement pris en charge à l’aide de la référence d’élément :

• Raccourci pour un lakehouse
• Fonctions de données utilisateur
• Notebook, via NotebookUtils

Exemple de code Python

L’exemple de code suivant montre comment utiliser une référence d’élément dans un script Python.

var_ref = "$(/**/VarLibItem/itemReference)"
var_obj = notebookutils.variableLibrary.get(var_ref)
workspace_id = var_obj.get("workspaceId").value()
item_id = var_obj.get("itemId").value()
print(workspace_id)
print(item_id)

Ce code effectue les opérations suivantes :

• Résout une variable de référence d’élément à partir d’une bibliothèque de variables Fabric
• Récupère l’objet de métadonnées pour cet élément référencé
• Extrait l’ID d’espace de travail et l’ID d’élément
• Imprime-les afin qu’ils puissent être utilisés par programmation.

Autorisations requises pour créer/utiliser des variables de référence d’élément

L’utilisation de variables de référence d’élément implique deux couches d’autorisations :

• Créer et modifier une variable de référence d’élément : les utilisateurs disposant de rôles Contributeur ou supérieur dans l’espace de travail peuvent créer et modifier des variables dans la bibliothèque, tandis que les visionneuses sont en lecture seule.
• Accès à la variable de référence d’élément : en plus des droits sur la bibliothèque de variables, vous devez disposer d’au moins l’autorisation Lecture sur la variable de référence d’élément que vous envisagez de référencer.

Pour plus d’informations sur les autorisations et la validation des autorisations, consultez Autorisations de bibliothèque de variables

Limites

Actuellement, vous ne pouvez référencer que des éléments de structure et des modèles sémantiques. D’autres éléments Power BI, tels que Datamarts, Dataflow Gen1 ne sont actuellement pas pris en charge.

Informations complémentaires

La bibliothèque de variables permet l'activation du CI/CD pour le contenu Fabric à travers les environnements (Dev, Test, Prod) en utilisant des variables de référence d'élément pour des configurations spécifiques à chaque étape. Gardez à l’esprit les points suivants :

• Les références d’élément sont liées à un espace de travail et à un ID d’élément spécifique.
• Lors du déploiement vers un nouveau stade, ces références pointent toujours vers l’espace de travail d’origine, à moins d’être mises à jour manuellement.
• Utilisez plusieurs ensembles de valeurs pour chaque étape et activez l'ensemble correct manuellement ou via des scripts d’API.

Pour plus d’informations, consultez les jeux de valeurs dans les bibliothèques de variables.

Contenu connexe

• Vue d’ensemble de la bibliothèque de variables
• Types de variables
• Jeux de valeurs
• Autorisations de bibliothèque de variables](./variable-library-permissions.md)