Entenda a vinculação de dependências em implantações entre espaços de trabalho

Quando você implanta itens do Fabric em diferentes espaços de trabalho (por exemplo, de Desenvolvimento para Teste e depois para Produção), as dependências entre os itens podem ser quebradas. Alguns itens armazenam referências às suas dependências como IDs de objeto (GUIDs específicos do workspace), enquanto outros usam IDs lógicos (identificadores portáteis entre espaços de trabalho armazenados no .platform arquivo).

Itens que usam IDs lógicos em suas definições se vinculam corretamente ao item correspondente no workspace de destino. Itens que usam IDs de objeto permanecem apontados para o espaço de trabalho de origem, o que faz a implantação falhar.

Este artigo mapeia quais tipos de itens Fabric suportam vinculação de dependências por IDs lógicos quando você usa integração com Git, e quais não. Para saber mais sobre IDs lógicos e como os itens são representados no controle de versão, veja ID Lógico no Fabric.

Conceitos principais

  • ID lógico: Um identificador entre espaços de trabalho gerado automaticamente no .platform arquivo. Itens com o mesmo ID lógico são tratados como o mesmo item em todos os workspaces.
  • ID de objeto: Um GUID específico de um espaço de trabalho que identifica uma instância específica. IDs de objetos não sobrevivem à implantação entre espaços de trabalho sem intervenção manual ou parametrização.
  • Vinculação de dependências (Git): Quando você sincroniza um branch Git com um novo workspace, o Fabric resolve referências de dependência usando IDs lógicos, apontando automaticamente para o item correto no workspace de destino.
  • Por nome ou por URI: Alguns itens referenciam dependências por nome de exibição ou URI em vez de por ID. Essas referências podem ou não ser resolvidas corretamente, dependendo das convenções de nomenclatura entre os espaços de trabalho.

Como funciona a vinculação de dependências

Dentro de um espaço de trabalho, os itens referenciam suas dependências usando IDs de objetos. Quando o Fabric exporta um item para o Git, ele substitui alguns desses IDs de objeto por IDs lógicos do .platform arquivo. Quando você sincroniza a branch do Git com um workspace diferente, o Fabric converte esses IDs lógicos novamente nos IDs corretos dos objetos no workspace de destino. É isso que faz a vinculação de dependências funcionar.

No entanto, nem todas as referências de dependência são substituídas por IDs lógicos durante a exportação. Itens que mantêm IDs de objetos em sua representação no Git ainda apontam para o espaço de trabalho original após a sincronização, e você precisa atualizá-los manualmente ou por meio de parametrização.

Importante

A vinculação de dependência se aplica apenas a referências entre itens do Fabric dentro do mesmo espaço de trabalho. Se um item referenciar um item do Fabric em um espaço de trabalho diferente, essa referência usa um ID de objeto e não se vincula automaticamente. Referências a conexões (conexões de fonte de dados, gateways) também não se vinculam automaticamente. Use Bibliotecas de Variáveis com conjuntos de valores específicos do ambiente para gerenciar referências de conexão entre ambientes.

Compatibilidade da associação de dependência

As tabelas a seguir mostram se as dependências de cada tipo de item do Fabric são vinculadas corretamente quando você implanta em diferentes workspaces. Atualmente, este artigo aborda o comportamento de integração com Git . Como a vinculação é determinada por como cada item armazena suas referências de dependência em sua definição, o mesmo comportamento se aplica a outros mecanismos de implantação que reutilizam essas definições, como pipelines de implantação e as APIs de importação (em massa).

Essas tabelas assumem que a dependência é outro item no mesmo espaço de trabalho que o item de origem. Uma referência a um item em outro espaço de trabalho nunca se vincula automaticamente. Ele permanece fixado ao ID do objeto de origem independentemente do valor mostrado na tabela.

A coluna Auto-bind in Git indica:

  • Sim: A definição do item no Git armazena a referência de dependência como um ID lógico. Quando você sincroniza o ramo para um novo workspace, a referência se vincula automaticamente ao item correspondente nesse workspace.
  • Não: A definição de item no Git armazena a referência da dependência como um ID de objeto (GUID específico do workspace). A referência continua apontando para o espaço de trabalho de origem após a sincronização. Você precisa atualizá-lo manualmente ou parametrizá-lo para implantação entre áreas de trabalho.
  • Parcial: O item resolve a dependência por nome ou URI, o que pode funcionar se a nomenclatura for consistente entre os espaços de trabalho.

Notebooks

Dependência Vinculação automática no Git Notes
Lakehouse Yes É necessário ativar o "Lakehouse Auto-Binding no Git" nas configurações do notebook. Quando ativado, o ID do objeto é substituído por um ID lógico em notebook-settings.json. Essa configuração é desmarcada por padrão. Para mais informações, veja Lakehouse auto-binding no Git.
Environment Yes
Banco de dados espelhado Não

Note

A vinculação do notebook ao Lakehouse não está habilitada por padrão. Você precisa ativar a configuração "Lakehouse Auto-Binding no Git" nas configurações de cada caderno. Para obter mais informações, consulte o controle do código-fonte e a implantação do Notebook.

Reports

Dependência Vinculação automática no Git Notes
Modelo Semântico (do relatório Power BI) Parcial O relatório faz referência ao modelo por meio de uma referência relativa byPath em definition.pbir, não de um ID lógico explícito. Isso é resolvido corretamente quando o modelo é implantado no mesmo local relativo no espaço de trabalho de destino, mas não é vinculado por meio de um ID lógico. Para mais informações, veja a pasta de relatórios de projetos do Power BI Desktop.
Modelo Semântico (do relatório paginado) Não A cadeia de conexão do relatório faz referência ao modelo semântico por um ID específico do workspace que não é reescrito durante a implantação, por isso continua apontando para o modelo de origem. Você precisa atualizar essa referência para a implantação entre espaços de trabalho. (Relatórios criados no Report Builder que fazem referência ao modelo pelo nome podem, em vez disso, resolver pelo nome de exibição, que é Parcial.)

Pipeline

Dependência Vinculação automática no Git Notes
Pipeline Yes
Notebook Yes
Fluxo de Dados Gen2 Yes
Banco de Dados SQL Yes
Definição de Trabalho do Spark Não A atividade SparkJobDefinition faz referência à Definição de Trabalho Spark pelo ID do objeto, não pelo ID lógico, então ela permanece apontada para o item de origem após a implantação. Você precisa parametrizar esse valor para a implantação entre espaços de trabalho.
Lakehouse Yes
Modelo semântico Não A atividade PBISemanticModelRefresh faz referência ao modelo semântico pelo ID do item, não pelo ID lógico. Você precisa parametrizar esse valor para a implantação entre espaços de trabalho.
Armazém Não O warehouse artifactId é resolvido por meio do ID lógico e é reassociado, mas o linkedService também armazena o endpoint SQL do espaço de trabalho de origem, que não é reescrito. Parametrize o endpoint para implantação entre espaços de trabalho.

Modelos semânticos

Dependência Vinculação automática no Git Notes
Modelo semântico Parcial Referências de modelos encadeados ou compostos usam cadeias de conexão pelo nome.
SQL Analytics Endpoint (lakehouse) Não A cadeia de conexão do Direct Lake no TMDL expressions.tmdl contém uma URL de ponto de extremidade específica do workspace e um GUID do banco de dados. Você precisa substituir esses parâmetros para a implantação entre espaços de trabalho.
Banco de dados KQL Não A cadeia de conexão que contém um URI de cluster nas expressões TMDL contém valores específicos do espaço de trabalho.
banco de dados SQL Não A cadeia de conexão nas expressões TMDL contém valores específicos do workspace.
Armazém Não A conexão com o endpoint de análise SQL do warehouse usa uma URL específica do workspace.

Casas de lago

Dependência Vinculação automática no Git Notes
Casa do Lago (atalho) Yes Atalhos internos do OneLake que apontam para outro item do Fabric, como um lakehouse ou warehouse, são armazenados como um ID lógico e vinculados novamente ao item do workspace de destino. Atalhos para fontes externas, como Azure Data Lake Storage Gen2 ou Amazon S3, apontam para fora do Fabric e trazem uma referência de conexão; por isso, não estão sujeitos à vinculação a ID lógico. Para ver a lista completa de destinos de atalho, consulte atalhos do OneLake. Para o comportamento da implantação, veja Integração do Git ao Lakehouse e pipelines de implantação.

Fluxos de dados (Gen2)

Por padrão, o Dataflow Gen2 cria referências absolutas para itens Fabric: a consulta armazena o ID do workspace de origem e o ID do objeto do item, que não são reescritos na implantação. Uma referência de origem pode, em vez disso, usar uma referência relativa: quando você seleciona um item no nó !(Current Workspace) em um conector do Fabric, a consulta armazena o item pelo nome (sem GUIDs) e o resolve para o item correspondente no espaço de trabalho de destino durante a implantação. Os destinos de saída sempre usam referências absolutas e não são reatribuídos. Para destinos e para qualquer referência de fonte absoluta, parametrize os valores para implantação entre espaços de trabalho. Para mais informações, veja Referências relativas com conectores Fabric em Dataflow Gen2 e Dataflow Gen2 com integração CI/CD e Git.

Referências fonte:

Dependência Vinculação automática no Git Notes
Lakehouse Parcial É revinculado somente quando definido como uma referência relativa (!(Área de Trabalho Atual)); a referência absoluta padrão não é revinculada.
Armazém Parcial É revinculado somente quando definido como uma referência relativa (!(Área de Trabalho Atual)); a referência absoluta padrão não é revinculada.

Referências de destino:

Dependência Vinculação automática no Git Notes
Lakehouse Não
Armazém Não
Banco de Dados SQL Não

Definições de trabalho do Spark

Dependência Vinculação automática no Git Notes
Environment Yes
Lakehouse Não Ele defaultLakehouseArtifactId usa um ID de objeto.

Tarefas de Cópia

Dependência Vinculação automática no Git Notes
Lakehouse Yes
Armazém Não O warehouse artifactId é resolvido por meio do ID lógico e é reassociado, mas o linkedService também armazena o endPoint SQL do espaço de trabalho de origem, que não é reescrito. Parametrize o endPoint para implantação entre espaços de trabalho.
Banco de Dados SQL Yes

GraphQL APIs

Dependência Vinculação automática no Git Notes
Ponto de Extremidade do SQL Yes
Armazém Yes
Banco de Dados SQL Yes

Para todas as fontes de dados da API GraphQL, talvez seja necessário reconfigurar a conexão e as credenciais após a implantação.

Fluxos de eventos

Dependência Vinculação automática no Git Notes
Lakehouse Yes
Eventhouse Yes Todos os destinos são totalmente suportados para CI/CD quando os itens estão no mesmo espaço de trabalho. Para o Eventhouse com modo Ingestão Direta, talvez seja necessário reconfigurar manualmente a conexão após a implantação. Para mais informações, veja Eventstream CI/CD.
Ativador (Reflex) Yes Todos os destinos são totalmente suportados para CI/CD quando os itens estão no mesmo espaço de trabalho. Para mais informações, veja Eventstream CI/CD.

Itens de KQL

Dependência Vinculação automática no Git Notes
Banco de dados KQL para eventhouse Yes O parentEventhouseItemId in DatabaseProperties.json é um ID lógico e se vincula à casa de eventos alvo. Um banco de dados KQL é implantado como filho de seu eventohouse-mãe.
Conjunto de consultas KQL para o banco de dados KQL Parcial É resolvido por meio de clusterUri e databaseName, não pelo ID do item. A definição inclui um databaseItemId, mas é um ID de objeto que não é reassociado, portanto a resolução depende do URI nos diferentes ambientes.
Painel em tempo real para o banco de dados KQL Parcial Usa uma dataSources matriz contendo URIs de cluster. Mesmo padrão do query set KQL.

Depósitos

Dependência Vinculação automática no Git Notes
Armazém (referência cruzada) Não Referências a outros armazéns usam IDs de objetos.
Ponto de Extremidade do SQL Não Referências de endpoints SQL usam identificadores específicos de workspace.

Bibliotecas de variáveis

Dependência Vinculação automática no Git Notes
Itens de Fabric (Tipo ItemReference) Não O ItemReference tipo de variável armazena workspaceId e itemId como GUIDs brutos. Você deve atualizar ou sobrescrever manualmente esses valores por meio de conjuntos de valores por ambiente.

Itens sem dependências

Os seguintes itens não apresentam preocupações com vinculação de dependência entre espaços de trabalho:

  • Environment
  • Banco de Dados SQL
  • Eventhouse (item de contêiner; Bancos de dados KQL fazem referência a isso)
  • Banco de Dados Espelhado (somente para configuração de fonte externa)

Resumo

Quando você implanta itens do Fabric em diferentes espaços de trabalho, as dependências entre os itens podem ser interrompidas se as referências forem armazenadas como IDs de objeto específicos do espaço de trabalho, em vez de IDs lógicos portáteis. Nem todos os tipos de itens suportam vinculação de dependências por meio de IDs lógicos. Antes de configurar a implantação entre espaços de trabalho, revise as tabelas de compatibilidade neste artigo para identificar quais dependências se vinculam automaticamente e quais exigem parametrização manual.

Conteúdo relacionado

  • Last updated on