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.

É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

Note

Le notebook n’est %%configure pas pris en charge.

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.

Autorisations requises pour créer/utiliser des références d’élément

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

• Créer/modifier - Bien que tout contributeur d’espace de travail puisse modifier les valeurs des variables, une variable de référence d’élément permet uniquement aux utilisateurs de définir comme éléments de valeur pour lesquels ils disposent d’autorisations de lecture. Cela s’applique à n’importe quelle valeur, au jeu de valeurs actif par défaut ou à d’autres jeux de valeurs. N’oubliez pas que lors de l’enregistrement d’un élément de bibliothèque de variables, une vérification des autorisations est effectuée sur les valeurs actives des variables de référence d’élément pour l’utilisateur qui enregistre l’élément, même si ces valeurs restent inchangées.
• Utiliser une variable ref d’élément : lors de la création/de la mise à jour d’une référence à une variable dans un élément consommateur, les utilisateurs ne peuvent pas définir de référence à une variable de référence d’élément, sauf s’ils disposent au moins d’une autorisation READ pour l’élément dans le jeu de valeurs actif.

Validation des autorisations

La validation d’autorisation est déclenchée dans les cas d’usage suivants :

• Modifiez un élément de la bibliothèque de variables qui a des variables de référence des éléments. Lors de la modification, nous vérifions que les éléments référencés existent et que l'utilisateur dispose au moins des autorisations de lecture pour ces éléments, pour toutes les valeurs de référence d'élément dans l'ensemble de valeurs actives, pour les scénarios suivants :

• Lors de l'ENREGISTREMENT d'un élément de la bibliothèque de variables dans l'interface utilisateur, une vérification des autorisations est effectuée sur les valeurs actives des variables de référence de cet élément pour l'utilisateur qui effectue l'enregistrement, même si ces valeurs sont inchangées.

• API/Mise à jour Git : la validation des autorisations est effectuée pendant la mise à jour et échoue si aucune autorisation de lecture n’est accordée à la valeur active de l’élément ref de l’espace de travail mis à jour.

• Déploiement : le déploiement d’un élément de bibliothèque de variables échoue si aucune autorisation de lecture n’est accordée à la valeur active de l’élément ref de l’espace de travail cible.

• Afficher les informations de référence d’élément supplémentaires dans la page bibliothèque de variables (interface utilisateur uniquement) Les utilisateurs ayant accès à la bibliothèque de variables (visionneuse WS ou ultérieure) qui n’ont pas d’autorisations pour l’élément dans la variable d’élément référencée, ne verront pas leurs détails dans l’interface utilisateur. Au lieu de cela, ils verront l’ID d’élément accompagné d’un message de pointage, plutôt que du composant de détails.

• Créer/modifier une variable de référence d’élément

  • Interface utilisateur : lors de la mise à jour de la valeur d’un jeu de valeurs (valeur par défaut ou autre), l’utilisateur peut sélectionner un élément dans une liste affichant uniquement les éléments auxquels il a au moins l’autorisation de lecture.
  • API/Mise à jour ou déploiement Git : consultez Modifier l’élément de bibliothèque de variables ci-dessus.

• Utilisation de la variable de référence d’élément dans un objet consommateur

  • Interface utilisateur - Création d’une référence à une variable - Lors de la création dans un élément d’une référence à une variable « Référence d’élément » à l’aide de la boîte de dialogue d’interface utilisateur « Sélectionner une variable » (comme dans Raccourci pour Lakehouse et pipeline de données), l’utilisateur qui crée la référence dispose au moins d’une autorisation de lecture pour les éléments dans les variables « référence d’élément » (la validation concerne uniquement les valeurs actives). Si ce n’est pas le cas, l’utilisateur voit uniquement l’ID des éléments.

Comportement dans les pipelines CI/CD et les phases de déploiement

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 :

Références statiques

• 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.

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.

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)