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.

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

Nota:

No se admite el portátil a través de %%configure.

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.

Permisos necesarios para crear o usar referencias de elementos

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

• Crear/Editar - Aunque cualquier colaborador del espacio de trabajo puede modificar los valores de las variables, una variable de referencia de elemento solo permite a los usuarios establecer como valores los elementos para los que tienen permisos de lectura. Esto se aplica a cualquier valor, el valor activo predeterminado establecido u otros conjuntos de valores. Tenga en cuenta que, durante el guardado de un elemento biblioteca de variables, se realiza una comprobación de permisos en los valores activos de las variables de referencia de elemento para el usuario que guarda el elemento, incluso si esos valores permanecen sin cambios.
• Usar una variable de referencia de elemento - Al crear o actualizar una referencia a una variable de un elemento de consumo, los usuarios no pueden establecerla a menos que tengan como mínimo permiso de lectura READ para el elemento en el conjunto de valores activo.

Validación de permisos

La validación de permisos se desencadena en los siguientes casos de uso:

• Edite un elemento de biblioteca de variables que tenga variables de referencia de elementos. Al editar, validamos tanto que los elementos referenciados existen como que el usuario tiene al menos permisos de lectura para ellos, esto aplica a todos los valores de referencia de elementos en el conjunto de valores activos, para los siguientes escenarios:

• UI: durante SAVE del elemento Biblioteca de variables, se realiza una comprobación de permisos en los valores activos de variables de referencia de elemento para el usuario que guarda el elemento, incluso si esos valores permanecen sin cambios.

• API/Actualización de Git: se realiza la validación de permisos durante la actualización y se produce un error si no hay permiso de lectura en el valor activo de item ref del área de trabajo actualizada.

• Implementación: se producirá un error en la implementación de un elemento de biblioteca de variables si no hay permiso de lectura en el valor activo de item ref del área de trabajo de destino.

• Consulta detalles adicionales de referencia de elementos en la página de la biblioteca de variables (solo interfaz de usuario). Los usuarios con acceso a la biblioteca de variables (visor de WS o superior) que no tienen permisos para el elemento de la variable de elemento referenciado, no verán sus detalles en la interfaz de usuario. En su lugar, verán el identificador del elemento acompañado de un mensaje emergente, en vez del componente de detalles.

• Crear o editar variable de referencia de elementos

  • INTERFAZ de usuario: al actualizar el valor de cualquier conjunto de valores (predeterminado u otro), el usuario puede seleccionar elemento de una lista que muestre solo los elementos a los que tiene al menos permiso de lectura.
  • APIs/Actualización o implementación de Git: consulte el elemento de biblioteca de variables "Editar" arriba.

• Uso de la variable de referencia de elemento en un artículo de consumo

  • UI: crear una referencia a una variable: al crear en un elemento una referencia a una variable "Referencia de elemento" mediante el cuadro de diálogo de interfaz de usuario "Seleccionar variable" (como en Acceso directo para Lakehouse y canalización de datos), hay validación de que el usuario que crea la referencia tiene al menos permiso de lectura para los elementos de las variables "referencia de elemento" (la validación es solo para los valores activos). Si no es así, el usuario ve solo el identificador de los elementos.

Comportamiento entre canalizaciones de CI/CD y fases de implementación

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:

Referencias estáticas

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

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.

Contenido relacionado

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