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.

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.

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

Esempio di codice Python

L'esempio di codice seguente illustra come usare un riferimento a un elemento in uno 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)

Questo codice esegue le operazioni seguenti:

• Risolve una variabile Item Reference da una libreria di variabili Fabric
• Recupera l'oggetto metadati per l'elemento a cui si fa riferimento
• Estrae l'ID dell'area di lavoro e l'ID dell'elemento
• Li stampa in modo che possano essere usati programmaticamente.

Autorizzazioni necessarie per creare/usare le variabili di riferimento agli elementi

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

• Creare e modificare una variabile di riferimento di un elemento: gli utenti con ruoli collaboratore o superiore nell'area di lavoro possono creare e modificare variabili nella libreria, mentre i visualizzatori sono di sola lettura.
• Accesso alla variabile di riferimento dell'elemento: oltre ai diritti per la libreria di variabili, è necessario disporre almeno dell'autorizzazione Lettura per la variabile di riferimento dell'elemento a cui si intende fare riferimento.

Per altre informazioni sulle autorizzazioni e la convalida delle autorizzazioni, vedere Autorizzazioni della libreria di variabili

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.

Informazioni aggiuntive

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:

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

Contenuti correlati

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