Compartilhar via

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.

  1. Entrar no Microsoft Fabric
  2. Navegue até o seu espaço de trabalho e a biblioteca de variáveis
  3. Na parte superior, selecione + Nova Variável
  4. Forneça um nome para a variável, selecione referência de item para o tipo e clique em ... para selecionar um valor
  5. 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.

Captura de tela dos itens disponíveis para a referência do item. 6. Depois de selecionado, ele aparecerá assim na página varlib - como um componente somente leitura mostrando o nome do item.

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

Captura de tela da janela de referência do item.

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.

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.

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.

Exemplo de código do Python

O exemplo de código a seguir mostra como usar uma referência de item em um 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)

Esse código faz o seguinte:

  • Resolve uma variável de referência de item de uma biblioteca de variáveis do Fabric
  • Recupera o objeto de metadados para esse item referenciado
  • Extrai a ID do espaço de trabalho e a ID do item
  • Imprime-os para que possam ser usados programaticamente.

Permissões necessárias para criar/usar variáveis de referência de item

O uso 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: usuários no espaço de trabalho com função de Colaborador ou superior podem criar e editar variáveis na biblioteca, enquanto os Observadores têm permissão de apenas leitura.
  • Acessando a variável de referência de item: além dos direitos na Biblioteca de Variáveis, você deve ter pelo menos permissão de leitura na variável de referência de item que você pretende referenciar.

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

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.

Informações adicionais

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:

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

Conteúdo relacionado

  • Last updated on