Tipo de variável de referência de item (versão prévia)

Para aprimorar a flexibilidade e a escalabilidade, estamos introduzindo variáveis avançadas junto com os tipos de variáveis básicas existentes. Essas variáveis avançadas são projetadas para atender aos principais requisitos, como parametrizar conexões externas e internas (por exemplo, Snowflake, AWS, OneLake).

Uma variável de referência de item é um tipo de variável avançado usado na Fabric Variable Library para manter uma referência a um item existente no Fabric, como um lakehouse, notebook ou pipeline de dados, armazenando sua ID do workspace e a ID do item. Esse tipo de variável permite a parametrização de conexão interna, permitindo que os desenvolvedores vinculem dinamicamente itens a itens específicos do Fabric com base no estágio de implantação ou no contexto do workspace.

Como usar

Uma variável de referência de item pode ser usada da mesma forma que outras variáveis em uma biblioteca de variáveis.

Entrar no Microsoft Fabric
Navegue até o seu espaço de trabalho e a biblioteca de variáveis
Na parte superior, selecione + Nova Variável
Forneça um nome para a variável, selecione referência de item para o tipo e clique em ... para selecionar um valor
Isso abrirá uma caixa de diálogo para selecionar o item desejado. Você verá todos os itens nos quais você tem permissões, disponíveis para seleção. Use o explorer à esquerda para filtrar a lista por workspace. Use o filtro no canto superior direito para filtrar por tipo.

6. Depois de selecionado, ele aparecerá assim na página varlib - como um componente somente leitura mostrando o nome do item.

Se você precisar editar uma referência de item ou precisar verificar o valor duas vezes:

para ver detalhes adicionais, clique no valor
para editar esse valor ou valores de outros conjuntos de valores, clique no botão ao lado do valor.

Como funciona

O valor de uma variável de Referência de Item é essencialmente um ponteiro estático para um item do Fabric identificado pela ID do Workspace + ID do Item. O valor é armazenado como um par de GUIDs correspondentes ao workspace do item de destino e ao próprio item. Por exemplo, uma referência pode ser armazenada internamente como:

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

Essas duas IDs juntas identificam exclusivamente o item referenciado.

Tenha em mente o seguinte ao trabalhar com referências de item:

As referências de item permitem a parametrização de conexão interna, permitindo que os desenvolvedores vinculem dinamicamente itens a recursos específicos do Fabric com base no estágio de implantação ou no contexto do workspace.
A referência é estática, apontando para um item específico e não se ajustando automaticamente entre ambientes.
Para variações específicas do estágio, use conjuntos de valores, em que cada conjunto pode apontar para um item estático diferente (por exemplo, casas de lago diferentes por estágio).
Todos os valores entre conjuntos de valores devem ser do mesmo tipo de item para garantir a compatibilidade e evitar erros de runtime. No entanto, não impõemos ter o mesmo tipo de item entre conjuntos de valores.

Itens com suporte

Veja a seguir uma lista de itens com suporte no momento usando a referência de item:

Observação

Não há suporte para notebook através de %%configure.

Limitações

Atualmente, você só pode referenciar itens de malha e modelos semânticos. Atualmente, não há suporte para outros itens do Power BI, como Datamarts, Dataflow Gen1.

Permissões necessárias para criar/usar referências de item

O uso de variáveis de referência de item envolve duas camadas de permissões:

Criar/Editar – embora qualquer colaborador de workspace possa modificar valores de variáveis, uma variável de referência de item permite que os usuários definam como valor apenas itens para os quais têm permissões de leitura. Isso se aplica a qualquer valor, ao conjunto de valores ativo padrão ou a outros conjuntos de valores. Lembre-se de que, durante o salvamento de um item da Biblioteca de Variáveis, uma verificação de permissão é executada nos valores ativos das variáveis de referência de item para o usuário que está salvando o item, mesmo que esses valores permaneçam inalterados.
Usar uma variável de referência de item – Ao criar/atualizar uma referência a uma variável para um item de consumidor, os usuários não podem definir uma referência a uma variável de item, a menos que tenham pelo menos permissão READ para o item no conjunto de valores ativos.

Validação de permissão

A validação de permissão é disparada nos seguintes casos de uso:

Editar um item de biblioteca variável que tem variáveis de referência de item ao editar validamos tanto que os itens referenciados existem, quanto que o usuário tem pelo menos permissões de leitura para eles, para todos os valores de referência de item no conjunto de valores ativos, para os seguintes cenários:
Interface do usuário – Durante SAVE do item biblioteca de variáveis, uma verificação de permissão é executada nos valores ativos das variáveis de referência de item para o usuário que está salvando o item, mesmo que esses valores permaneçam inalterados.
APIs/Atualização do Git – A validação de permissão é feita durante a Atualização e falha se não houver permissão de leitura para o valor ativo da referência do item do workspace atualizado.
Implantação – A implantação de um item de biblioteca de variáveis falhará se não houver permissão de leitura para o valor ativo da referência de item da área de trabalho de destino.
Exibir detalhes adicionais de referência de item na página da biblioteca de variáveis (somente interface do usuário). Usuários com acesso à biblioteca de variáveis (visualizador WS ou superior) que não têm permissões para o item na variável do item referenciado não verão seus detalhes na interface do usuário. Em vez disso, eles verão a ID do item acompanhada por uma mensagem ao passar o mouse, em vez do componente de detalhes.

Criar/Editar variável de referência de item
- Interface do usuário – Ao atualizar o Valor de qualquer conjunto de valores (padrão ou outro), o usuário pode selecionar o item de uma lista mostrando apenas os itens para os quais ele tem pelo menos permissão de leitura.
- APIs/Atualização ou Implantação do Git – consulte Editar item da biblioteca de variáveis acima.
Uso da variável de referência de item em um item de consumo
- Interface do usuário – Criando uma referência à variável: ao criar uma referência a uma variável de 'referência de item' em um item, usando a caixa de diálogo 'Selecionar variável' da interface do usuário (como no atalho para o Lakehouse e no pipeline de dados), é realizada uma validação para assegurar que o usuário que cria a referência tenha, no mínimo, permissão de leitura para os itens nas variáveis de 'referência de item' (a validação é somente para os valores ativos). Caso contrário, o usuário verá apenas a ID dos itens.

Comportamento nos pipelines de CI/CD e nas fases de implantação

A Biblioteca de Variáveis habilita CI/CD para conteúdo Fabric entre ambientes (Desenvolvimento, Teste, Produção) usando variáveis de referência de item para configurações específicas de fase. Lembre-se do seguinte:

Referências estáticas

As referências de item estão vinculadas a um workspace específico e à ID do item.
Ao implantar em um novo estágio, essas referências ainda apontam para o workspace original, a menos que sejam atualizadas manualmente.
Use vários Value-Sets para cada estágio e ative o conjunto correto manualmente ou por meio de scripts de API.

Para obter mais informações, consulte os conjuntos de valores em bibliotecas de variáveis.

Representação em Git e APIs

A Biblioteca de Variáveis é gerenciada como código. Usando APIs Git ou REST, as variáveis de Referência de Item têm um formato JSON claro. Todas as variáveis aparecem no arquivo de definição da Biblioteca de Variáveis (armazenado no Git, geralmente .json), listando propriedades como nome, tipo e valor.

Para uma variável de Referência de Item (Estática), o valor é dados estruturados para IDs de workspace e item. Exemplo:


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

Lembre-se do seguinte ao trabalhar por meio da API:

Somente as IDs são armazenadas; os nomes e metadados são recuperados em runtime ou armazenados em cache no Fabric.
Criando/atualizando por meio da API, você fornece IDs de workspace e de item. IDs inválidas causam erros.

Visão geral da biblioteca de variáveis
Tipos de variáveis
Conjuntos de valores
Permissões de biblioteca de variáveis](./variable-library-permissions.md)

Comentários

Esta página foi útil?

Last updated on 2026-01-29