Partilhar via

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.

  1. Iniciar sessão no Microsoft Fabric
  2. Navegue até ao seu espaço de trabalho e à biblioteca de variáveis
  3. No topo, selecione + Nova Variável
  4. 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
  5. 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.

Captura de ecrã dos itens disponíveis para referência ao item. 6. Uma vez selecionado, aparecerá assim na página varlib - como um componente apenas de leitura que mostra o nome do item.

Captura de ecrã da referência 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.

Captura de ecrã do pop-up de referência ao item.

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.

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.

Itens suportados

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

Observação

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

Exemplo de código em Python

O exemplo de código seguinte mostra como usar uma referência de item num 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)

Este código faz o seguinte:

  • Resolve uma variável de Referência de Item a partir de uma Biblioteca de Variáveis de Fabric
  • Recupera o objeto de metadados desse item referenciado
  • Extrai o ID do espaço de trabalho e o ID do item
  • Imprime-os para que possam ser usados programaticamente.

Permissões Necessárias para Criar/Usar variáveis de referência de itens

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

  • Criar e Editar uma Variável de Referência de Item: Utilizadores com funções de Colaborador ou superiores no espaço de trabalho podem criar e editar variáveis na biblioteca, enquanto os Visualizadores apenas têm permissões de leitura.
  • Aceder à variável de referência do item: Para além dos direitos sobre a Biblioteca de Variáveis, deve ter pelo menos permissão de leitura na variável de referência do item que pretende referenciar.

Para mais informações sobre permissões e validação de permissões, veja Permissões da biblioteca de variáveis

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.

Informação adicional

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:

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

Conteúdo relacionado

  • Last updated on