Tipo di variabile di riferimento di elemento (anteprima)

Per migliorare la flessibilità e la scalabilità, vengono introdotti variabili avanzate insieme ai tipi di variabili di base esistenti. Queste variabili avanzate sono progettate per soddisfare i requisiti chiave, ad esempio la parametrizzazione di connessioni esterne e interne ,ad esempio Snowflake, AWS, OneLake.

Una variabile di riferimento agli elementi è un tipo di variabile avanzato usato all'interno della libreria di variabili Fabric per contenere un riferimento a un elemento Fabric esistente, ad esempio, un lakehouse, un notebook o una pipeline di dati, archiviando l'ID dell'area di lavoro e l'ID elemento. Questo tipo di variabile consente la parametrizzazione della connessione interna, consentendo agli sviluppatori di collegare dinamicamente elementi a elementi specifici di Fabric in base al contesto della fase di distribuzione o dell'area di lavoro.

Come usare

Una variabile di riferimento elemento può essere usata esattamente come altre variabili in una libreria di variabili.

1. Accedere a Microsoft Fabric
2. Passare all'area di lavoro e alla libreria di variabili
3. Nella parte superiore selezionare + Nuova variabile
4. Specificare un nome per la variabile, selezionare il riferimento all'elemento per il tipo e quindi fare clic su ... per selezionare un valore
5. Verrà aperta una finestra di dialogo per selezionare l'elemento desiderato. Verranno visualizzati tutti gli elementi per cui si dispone delle autorizzazioni disponibili per la selezione. Usare l'esploratore sulla sinistra per filtrare l'elenco in base all'area di lavoro. Usare il filtro nell'angolo superiore destro per filtrare in base al tipo.

6. Una volta selezionato, verrà visualizzato in questo modo nella pagina varlib - come un componente di sola lettura che mostra il nome dell'elemento.

Se è necessario modificare un riferimento a un elemento o controllare il valore:

• per visualizzare dettagli aggiuntivi, fare clic sul valore
• per modificare questo valore o i valori di altri set di valori, fare clic sul pulsante accanto al valore.

Come funziona

Il valore di una variabile Item Reference è essenzialmente un puntatore statico a un elemento fabric identificato da ID area di lavoro e ID elemento. Il valore viene archiviato come coppia di GUID corrispondenti all'area di lavoro dell'elemento di destinazione e all'elemento stesso. Ad esempio, un riferimento potrebbe essere archiviato internamente come segue:

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

Questi due ID identificano in modo univoco l'elemento a cui si fa riferimento.

Quando si lavora con i riferimenti agli elementi, tenere presente quanto segue:

• I riferimenti agli elementi abilitano la parametrizzazione interna della connessione, consentendo agli sviluppatori di collegare dinamicamente elementi a risorse di Fabric specifiche in base al contesto della fase di distribuzione o dell'area di lavoro.
• Il riferimento è statico e punta a un elemento specifico e non si regola automaticamente negli ambienti.
• Per le variazioni specifiche della fase, utilizzare set di valori, dove ogni set può puntare a un diverso elemento statico (ad esempio, diversi lakehouse per ciascuna fase).
• Tutti i valori nei set di valori devono essere dello stesso tipo di elemento per garantire la compatibilità e prevenire gli errori di runtime. Tuttavia, non viene applicata la presenza dello stesso tipo di elemento tra set di valori.

Elementi supportati

Di seguito è riportato un elenco di elementi attualmente supportati tramite riferimento agli elementi:

• Scorciatoia per una lakehouse
• Funzioni dati utente
• Notebook, tramite NotebookUtils

Annotazioni

Notebook, through %%configure non è supportato.

Limitazioni

Attualmente, è possibile fare riferimento solo agli elementi fabric e ai modelli semantici. Altri elementi di Power BI, ad esempio Datamarts, Dataflow Gen1 non sono attualmente supportati.

Autorizzazioni necessarie per creare/usare riferimenti agli elementi

L'uso delle variabili di riferimento elemento prevede due livelli di autorizzazioni:

• Crea/Modifica : anche se qualsiasi collaboratore dell'area di lavoro può modificare i valori delle variabili, una variabile di riferimento elemento consente solo agli utenti di impostare come elementi di valore per i quali dispongono delle autorizzazioni di lettura. Questo vale per qualsiasi valore, il valore attivo predefinito impostato o altri set di valori. Tenere presente che durante il salvataggio di un elemento libreria di variabili viene eseguito un controllo delle autorizzazioni sui valori attivi delle variabili di riferimento degli elementi per l'utente che salva l'elemento, anche se tali valori rimangono invariati.
• Usare una variabile ref dell'elemento : quando si crea o si aggiorna un riferimento a una variabile in un elemento consumer, gli utenti non possono impostare un riferimento a una variabile di riferimento a un elemento a meno che non dispongano almeno dell'autorizzazione READ per l'elemento nel set di valori attivo.

Convalida delle autorizzazioni

La convalida delle autorizzazioni viene attivata nei casi d'uso seguenti:

• Modificare un elemento della libreria di variabili che ha variabili di riferimento elementi. Quando si modificano, verifichiamo che gli elementi a cui si fa riferimento esistono e che verifichiamo che l'utente disponga almeno delle autorizzazioni di lettura per tali elementi, per tutti i valori di riferimento dell'elemento nel set di valori attivi, nei seguenti scenari:

• Interfaccia utente: durante il salvataggio dell'elemento libreria di variabili, viene eseguito un controllo delle autorizzazioni sui valori attivi delle variabili di riferimento degli elementi per l'utente che salva l'elemento, anche se tali valori rimangono invariati.

• API/Git Update: la convalida delle autorizzazioni viene eseguita durante l'aggiornamento e ha esito negativo se non viene eseguita alcuna autorizzazione di lettura per il valore attivo di Item ref dell'area di lavoro aggiornata.

• Distribuzione: la distribuzione di un elemento della libreria di variabili avrà esito negativo se non è disponibile alcuna autorizzazione di lettura per il valore attivo dell'elemento ref dell'area di lavoro di destinazione.

• Visualizzare i dettagli aggiuntivi relativi ai riferimenti agli elementi nella pagina Libreria variabili (solo interfaccia utente) Utenti con accesso alla libreria di variabili (visualizzatore WS o superiore) che non dispongono delle autorizzazioni per l'elemento nella variabile di elemento a cui si fa riferimento, non visualizzerà i dettagli nell'interfaccia utente. Verranno invece visualizzati l'ID elemento accompagnato da un messaggio al passaggio del mouse, anziché dal componente dei dettagli.

• Creare/modificare la variabile di riferimento dell'elemento

  • Interfaccia utente: quando si aggiorna il valore impostato (predefinito o altro), l'utente può selezionare un elemento da un elenco che mostra solo gli elementi a cui ha almeno l'autorizzazione di lettura.
  • API/Git Update o Distribuzione: vedere Modificare l'elemento della libreria delle variabili precedente.

• Uso della variabile di riferimento dell'oggetto in un oggetto consumer

  • Interfaccia utente - Creazione di un riferimento a variabile : quando si crea in un elemento un riferimento a una variabile 'Riferimento elemento' usando la finestra di dialogo dell'interfaccia utente 'Seleziona variabile', ad esempio in Shortcut for Lakehouse e nella pipeline di dati, viene convalidata che l'utente che crea il riferimento abbia almeno l'autorizzazione di lettura per gli elementi nelle variabili 'item reference' (la convalida è solo per i valori attivi). In caso contrario, l'utente visualizza solo l'ID degli elementi.

Comportamento tra pipeline CI/CD e fasi di distribuzione

La Variable Library abilita CI/CD per il contenuto di Fabric negli ambienti (Sviluppo, Test, Prod) usando le variabili di riferimento degli elementi per configurazioni specifiche per fase. Tieni presente quanto segue:

Riferimenti statici

• I riferimenti agli elementi sono associati a un'area di lavoro e a un ID elemento specifici.
• Durante la distribuzione in un nuovo ambiente, questi riferimenti continuano a puntare all'area di lavoro originale, a meno che non siano aggiornati manualmente.
• Usare più set di valori per ciascuna fase e attivare il set corretto manualmente o attraverso script API.

Per altre informazioni, vedere Set di valori nelle librerie di variabili.

Rappresentazione in Git e API

La libreria di variabili viene gestita come codice. Usando Git o le API REST, le variabili di riferimento agli elementi hanno un formato JSON non crittografato. Tutte le variabili vengono visualizzate nel file di definizione della libreria di variabili (archiviato in Git, in genere .json), elencando proprietà come nome, tipo e valore.

Per una variabile Di riferimento elemento (statico), il valore è costituito da dati strutturati per l'area di lavoro e gli ID elemento. Esempio:

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

 

Quando si lavora tramite l'API, tenere presente quanto segue:

• Vengono archiviati solo gli ID; i nomi e i metadati vengono recuperati in fase di esecuzione o memorizzati nella cache in Fabric.
• La creazione/l'aggiornamento tramite API consente di fornire ID di area di lavoro e di elementi. Gli ID non validi causano errori.

Contenuti correlati

• Panoramica della libreria di variabili
• Tipi di variabili
• Set di valori
• Autorizzazioni della libreria di variabili](./variable-library-permissions.md)