Tipo de variável de referência do item (pré-visualização)

Para aumentar a flexibilidade e escalabilidade, estamos a introduzir variáveis avançadas juntamente com os tipos básicos de variáveis existentes. Estas variáveis avançadas são concebidas para satisfazer requisitos-chave, como a parametrização de ligações externas e internas (por exemplo, Snowflake, AWS, OneLake).

Uma variável de referência de item é um tipo avançado de variável utilizado dentro da Biblioteca de Variáveis Fabric para armazenar uma referência a um item existente no Fabric—como um lakehouse, notebook ou data pipeline—armazenando o seu ID de espaço de trabalho e ID de item. Este tipo de variável permite a parametrização interna da ligação, permitindo aos programadores ligar dinamicamente itens a itens específicos do Fabric com base na fase de implementação ou no contexto do espaço de trabalho.

Modo de utilização

Uma variável de referência de item pode ser usada tal como outras variáveis numa biblioteca de variáveis.

Iniciar sessão no Microsoft Fabric
Navegue até ao seu espaço de trabalho e à biblioteca de variáveis
No topo, selecione + Nova Variável
Forneça um nome para a variável, selecione a referência do item para o tipo, e depois clique em ... para selecionar um valor
Isto abrirá um diálogo para selecionar o item desejado. Verás todos os itens para os quais tens permissões, disponíveis para seleção. Use o explorador à esquerda para filtrar a lista por espaço de trabalho. Use o filtro no canto superior direito para filtrar por tipo.

6. Uma vez selecionado, aparecerá assim na página varlib - como um componente apenas de leitura que mostra o nome do item.

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

Para ver mais detalhes, clique no valor
Para editar este 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 Fabric item identificado por ID de Workspace + ID de Item. O valor é armazenado como um par de GUIDs correspondentes ao espaço de trabalho do item alvo 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

Estes dois IDs juntos identificam de forma única o item referenciado.

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

As referências aos itens permitem a parametrização interna da ligação, permitindo aos programadores ligar dinamicamente itens a recursos específicos do Fabric com base na fase de implementação ou no contexto do espaço de trabalho.
A referência é estática, apontando para um item específico e não ajustando-se automaticamente entre ambientes.
Para variações específicas de cada estágio, use conjuntos de valores, onde cada conjunto pode apontar para um item estático diferente (por exemplo, diferentes casas de lago por fase).
Todos os valores entre conjuntos de valores devem ser do mesmo tipo de item para garantir compatibilidade e evitar erros em tempo de execução. No entanto, não impomos que o mesmo tipo de item seja utilizado em todos os conjuntos de valores.

Itens suportados

Segue-se uma lista dos itens atualmente suportados usando referência de itens:

Observação

Notebook, through %%configure não é suportado.

Limitações

Atualmente, só podes consultar peças de tecido e modelos semânticos. Outros itens do Power BI, como Datamarts, Dataflow Gen1, não são atualmente suportados.

Permissões Necessárias para Criar/Usar Referências de Itens

A utilização de variáveis de referência de itens envolve duas camadas de permissões:

Criar/Editar - Embora qualquer contribuidor de espaço de trabalho possa modificar os valores das variáveis, uma variável de referência de Item só permite aos utilizadores definir como valor itens para os quais têm permissões de leitura. Isto aplica-se a qualquer valor, o conjunto de valores ativos padrão ou outros conjuntos de valores. Tenha em atenção que, durante a gravação de um item da Biblioteca de Variáveis, é realizada uma verificação de permissão nos valores ativos das variáveis de referência do item para o utilizador que está a guardar o item, mesmo que esses valores permaneçam inalterados.
Use uma variável de referência de item - Ao criar/atualizar uma referência a uma variável num artigo de consumo, os utilizadores não podem definir uma referência para uma variável de referência de artigo a menos que tenham pelo menos permissão de LEITURA para o item no conjunto de valores ativo.

Validação de permissão

A validação de permissões é acionada nos seguintes casos de uso:

Editar um item da biblioteca de variáveis que tenha variáveis de referência de item Ao editar, validamos tanto que os itens referenciados existem, como que o utilizador tem pelo menos permissões de leitura para eles, para todos os valores de referência de itens no conjunto de valores ativos, para os seguintes cenários:
UI - Durante o SAVE do item da Biblioteca de Variáveis, é realizada uma verificação de permissão nos valores ativos das variáveis de referência do item para o utilizador que está a guardar o item, mesmo que esses valores permaneçam inalterados.
APIs/Atualização do Git - A validação de permissões é realizada durante a atualização e falha se não houver permissão de leitura para o valor ativo da referência do item no espaço de trabalho atualizado.
Implantação - A implantação de um item da biblioteca variável falhará se não houver permissão de leitura para o valor ativo da referência do item no workspace alvo.
Ver detalhes adicionais da referência ao item na página da biblioteca de variáveis (apenas UI) Utilizadores com acesso à biblioteca de variáveis (visualizador WS ou superior) que não possuem permissões para o item na variável referenciada não verão os seus dados na interface. Em vez disso, verão o ID do item acompanhado de uma mensagem ao passar o cursor, em vez do componente de detalhes.

Criar/Editar variável de referência de item
- UI - Ao atualizar o Valor de qualquer conjunto de valores (Padrão ou outro), o utilizador pode selecionar um item de uma lista que mostre apenas os itens para os quais tem pelo menos permissão de leitura.
- APIs/Atualização ou Implementação Git - ver o item Editar biblioteca de variáveis acima.
Utilização da variável de referência do artigo num artigo de consumo
- UI - Criar uma Referência para variável - Ao criar num item uma referência a uma variável 'Item Reference' usando o diálogo UI 'Selecionar variável' (como no Atalho para Lakehouse e Data pipeline), verifica-se que o utilizador que cria a referência tem pelo menos permissão de leitura para os itens nas variáveis 'Item Reference' (a validação aplica-se apenas aos valores ativos). Caso contrário, o utilizador vê apenas o ID dos itens.

Comportamento ao longo dos pipelines CI/CD e fases de implementação

A Biblioteca de Variáveis permite CI/CD para conteúdo Fabric em diferentes ambientes (Desenvolvimento, Teste, Produção) utilizando variáveis de Referência de Item para configurações específicas de cada etapa. Tenha em mente o seguinte:

Referências estáticas

As Referências de Itens estão associadas a um espaço de trabalho específico e ao ID do item.
Durante a implantação para um novo estágio, estas referências continuam a apontar para o espaço de trabalho original, a menos que sejam atualizadas manualmente.
Use múltiplos Value-Sets para cada estágio e ative o conjunto correto manualmente ou através de scripts API.

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

Representação em Git e APIs

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

Para uma variável de Referência de Item (Estática), o valor é constituído por 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 via API:

Apenas os IDs são armazenados; nomes e metadados são recuperados em tempo de execução ou armazenados em cache no Fabric.
Ao criar/atualizar via API, forneces os IDs do espaço de trabalho e dos itens. IDs inválidos causam erros.

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

Feedback

Esta página foi útil?

Last updated on 2026-01-29