Tipo de variable de referencia de elemento (versión preliminar)

Para mejorar la flexibilidad y la escalabilidad, estamos introduciendo variables avanzadas junto con los tipos de variables básicas existentes. Estas variables avanzadas están diseñadas para cumplir los requisitos clave, como parametrizar conexiones externas e internas (por ejemplo, Snowflake, AWS, OneLake).

Una variable de referencia de elemento es un tipo avanzado de variable que se usa en la Biblioteca de Variables de Fabric para contener una referencia a un elemento existente de Fabric, como un lakehouse, notebook o canalización de datos, almacenando su identificador de área de trabajo e identificador de elemento. Este tipo de variable permite la parametrización de conexión interna, lo que permite a los desarrolladores vincular dinámicamente los elementos a elementos específicos de Fabric en función de la fase de implementación o el contexto del área de trabajo.

Cómo se usa

Una variable de referencia de elemento se puede usar igual que otras variables de una biblioteca de variables.

1. Iniciar sesión en Microsoft Fabric
2. Vaya al área de trabajo y a la biblioteca de variables.
3. En la parte superior, seleccione + Nueva variable.
4. Proporcione un nombre para la variable, seleccione la referencia de elemento para el tipo y, a continuación, haga clic en ... para seleccionar un valor.
5. Se abrirá un cuadro de diálogo para seleccionar el elemento deseado. Verá todos los elementos en los que tiene permisos, disponibles para su selección. Use el explorador de la izquierda para filtrar la lista por área de trabajo. Use el filtro en la esquina superior derecha para filtrar por tipo.

6. Una vez seleccionado, aparecerá como este en la página varlib, como un componente de solo lectura que muestra el nombre del elemento.

Si necesita editar una referencia de elemento o debe volver a comprobar el valor:

• para ver detalles adicionales, haga clic en el valor.
• para editar este valor o valores de otros conjuntos de valores: haga clic en el botón situado junto al valor.

Cómo funciona

El valor de una variable de referencia de elemento es esencialmente un puntero estático a un elemento de Fabric identificado por el ID de área de trabajo e ID de elemento. El valor se almacena como un par de GUID correspondientes al área de trabajo del elemento de destino y al propio elemento. Por ejemplo, una referencia podría almacenarse internamente como:

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

Estos dos identificadores en conjunto identifican de forma única el elemento al que se hace referencia.

Tenga en cuenta lo siguiente al trabajar con referencias de elementos:

• Las referencias de elementos permiten la parametrización de conexión interna, lo que permite a los desarrolladores vincular dinámicamente elementos a recursos específicos de Fabric en función de la fase de implementación o el contexto del área de trabajo.
• La referencia es estática, apunta a un elemento específico y no se ajusta automáticamente entre entornos.
• En el caso de las variaciones específicas de la fase, use conjuntos de valores, donde cada conjunto puede apuntar a un elemento estático diferente (por ejemplo, diferentes almacenes de lago por fase).
• Todos los valores de conjuntos de valores deben ser del mismo tipo de elemento para garantizar la compatibilidad y evitar errores en tiempo de ejecución. Sin embargo, no se exige utilizar el mismo tipo de elemento en todos los conjuntos de valores.

Representación en Git y API

La biblioteca de variables se administra como código. Con las API de GIT o REST, las variables de referencia de elemento tienen un formato JSON claro. Todas las variables aparecen en el archivo de definición de la biblioteca de variables (almacenado en Git, normalmente .json), enumerando propiedades como nombre, tipo y valor.

Para una variable de Referencia de Ítem (Estática), el valor es datos estructurados correspondientes a los IDs del área de trabajo y del ítem. Ejemplo:

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

 

Recuerde lo siguiente al trabajar a través de la API:

• Solo se almacenan los identificadores; los nombres y los metadatos se recuperan en tiempo de ejecución o se almacenan en caché en Fabric.
• Al crear o actualizar a través de la API, debes proporcionar los identificadores del área de trabajo y del elemento. Los identificadores no válidos provocan errores.

Elementos admitidos

A continuación se muestra una lista de elementos que se admiten actualmente mediante la referencia de elementos:

• Acceso directo a una casa de lago
• Funciones de datos de usuario
• Notebook, a través de NotebookUtils

Ejemplo de código de Python

En el ejemplo de código siguiente se muestra cómo usar una referencia de elemento en un script de 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)

Este código hace lo siguiente:

• Resuelve una variable de referencia de elemento de una biblioteca de variables de Fabric
• Recupera el objeto de metadatos para ese elemento al que se hace referencia.
• Extrae el identificador del área de trabajo y el identificador de elemento.
• Los imprime para que se puedan usar mediante programación.

Permisos necesarios para crear o usar variables de referencia de elementos

El uso de variables de referencia de elementos implica dos capas de permisos:

• Crear y editar una variable de referencia de elemento: los usuarios con roles de colaborador o superior en el área de trabajo pueden crear y editar variables en la biblioteca, mientras que los visores son de solo lectura.
• Acceso a la variable de referencia de elemento: además de los derechos de la biblioteca de variables, debe tener al menos permiso de lectura en la variable de referencia de elemento a la que desea hacer referencia.

Para obtener más información sobre los permisos y la validación de permisos, consulte Permisos de biblioteca de variables.

Limitaciones

Actualmente, solo puede hacer referencia a elementos de tejido y modelos semánticos. Actualmente no se admiten otros elementos de Power BI, como Datamarts, Dataflow Gen1.

Información adicional

La biblioteca de variables habilita CI/CD para contenido de Fabric en entornos (desarrollo, pruebas y producción) utilizando variables de referencia de elementos para configuraciones específicas de cada fase. Tenga en cuenta lo siguiente:

• Las referencias de elemento están vinculadas a un área de trabajo y un identificador de elemento específicos.
• Al desplegarse en una nueva etapa, estas referencias siguen apuntando al área de trabajo original a menos que se actualicen manualmente.
• Use varios Value-Sets para cada fase y active el conjunto correcto manualmente o a través de scripts de API.

Para obtener más información, consulte conjuntos de valores en bibliotecas de variables.

Contenido relacionado

• Introducción a la biblioteca de variables
• Tipos de variables
• Conjuntos de valores
• Permisos de biblioteca de variables](./variable-library-permissions.md)