Falha na Importação de Solução do Copilot Studio com Referência de Conexão Ausente: Correção

Ao importar uma solução no Copilot Studio, o processo pode falhar com um erro sobre uma referência de conexão ausente. Isso acontece porque a solução contém referências a conexões que não existem no ambiente de destino. O erro impede a conclusão da importação e bloqueia seu pipeline de implantação. Este artigo explica por que o erro ocorre e fornece as etapas exatas para corrigi-lo.

Por que a Importação de Solução do Copilot Studio Falha com Referência de Conexão Ausente

Uma solução do Copilot Studio é um pacote que contém configurações de copiloto, fluxos e conectores. Quando você exporta uma solução de um ambiente e a importa para outro, a solução espera que todas as referências de conexão usadas no ambiente de origem existam no ambiente de destino. Uma referência de conexão vincula um conector a uma instância de conexão específica. Se o ambiente de destino não tiver essa referência de conexão, o processo de importação não consegue resolver o vínculo e falha com o erro “Referência de conexão ausente”.

A causa raiz é que as referências de conexão são específicas do ambiente. Elas estão vinculadas ao ID da conexão e à instância de conexão criada no ambiente de origem. Quando você exporta a solução, a referência de conexão é incluída, mas a instância de conexão real não é. O ambiente de destino deve ter uma referência de conexão com o mesmo nome lógico e uma instância de conexão válida por trás dela.

Esse problema é comum ao mover soluções entre ambientes de desenvolvimento, teste e produção. Também ocorre quando você importa uma solução de outro locatário ou de uma solução gerenciada que foi exportada sem incluir referências de conexão.

Etapas para Corrigir o Erro de Referência de Conexão Ausente

1. Identifique a referência de conexão ausente
   Abra os detalhes do erro de importação. No Power Apps ou Copilot Studio, vá em Soluções e selecione a importação com falha. Clique em Exibir log. O log mostra o nome da referência de conexão ausente. Anote o nome lógico exatamente como aparece.
2. Crie a referência de conexão ausente no ambiente de destino
   No ambiente de destino, vá em Power Apps > Soluções. Abra a solução que falhou. Selecione Conexões na navegação à esquerda. Clique em Nova conexão e selecione o tipo de conector que corresponde à referência ausente. Por exemplo, se a referência ausente for para Microsoft Dataverse, crie uma conexão do Dataverse. Após criar a conexão, volte para a solução e adicione um componente de referência de conexão. Defina o nome lógico para corresponder à referência ausente do log. Selecione a conexão que você acabou de criar.
3. Reimporte a solução
   Após criar a referência de conexão, tente a importação novamente. No Power Apps, selecione Soluções > Importar. Escolha o arquivo de solução. Na página de configurações de importação, verifique se a referência de conexão está mapeada corretamente. O sistema agora deve mostrar a nova referência de conexão como disponível. Conclua a importação.
4. Se a importação ainda falhar, use a ferramenta Solution Packager
   Baixe e instale o Power Platform CLI. Abra um prompt de comando e execute pac solution unpack --zipfile "caminho-para-solucao.zip" --folder "caminho-para-pasta-saida". Isso descompacta a solução em arquivos XML. Navegue até a pasta e abra a pasta Other. Encontre o arquivo XML que contém a referência de conexão. Edite o arquivo para adicionar a referência de conexão ausente com o nome lógico correto. Em seguida, empacote a solução novamente usando pac solution pack --zipfile "caminho-para-nova-solucao.zip" --folder "caminho-para-pasta-saida". Importe a solução reempacotada.
5. Verifique as variáveis de ambiente
   Se a referência de conexão usar variáveis de ambiente, garanta que essas variáveis existam no ambiente de destino. Vá em Soluções > Variáveis de ambiente. Crie quaisquer variáveis ausentes com o mesmo nome de esquema e defina valores padrão. Em seguida, reimporte a solução.

Se a Importação Ainda Falhar Após Criar a Referência de Conexão

O nome lógico da referência de conexão não corresponde

O nome lógico no ambiente de destino deve corresponder exatamente ao nome lógico do ambiente de origem. Mesmo uma diferença de um único caractere faz a importação falhar. Copie o nome lógico do log de importação e cole-o ao criar a referência de conexão. Não digite manualmente.

A instância de conexão é inválida ou expirou

Uma referência de conexão aponta para uma instância de conexão. Se a instância de conexão expirou ou foi excluída, a importação falhará. Após criar uma nova conexão, verifique se ela está em estado ativo. Vá em Dados > Conexões no Power Apps e verifique o status. Se o status mostrar “Expirado”, reautentique a conexão.

A solução contém várias referências ausentes

O log de importação pode mostrar apenas a primeira referência ausente. Após corrigir essa, a próxima importação pode falhar com uma referência ausente diferente. Repita o processo para cada referência ausente listada no log. Para evitar isso, abra o XML da solução e pesquise todos os elementos connection-reference. Crie todas as referências ausentes antes de tentar a importação novamente.

Solução gerenciada não pode ser modificada

Se você estiver importando uma solução gerenciada, não é possível adicionar referências de conexão diretamente a ela. Em vez disso, crie as referências de conexão no ambiente de destino antes de importar. A solução gerenciada as detectará automaticamente se os nomes lógicos corresponderem. Se a solução gerenciada não as detectar, entre em contato com o editor da solução para fornecer uma versão atualizada com as referências de conexão incluídas.

Criação Manual de Referência de Conexão vs. Importação Automatizada

Item	Criação Manual	Importação Automatizada com Referências de Conexão
Tempo de configuração	Alto – requer criação manual de cada referência	Baixo – as referências são incluídas na solução
Risco de erro	Alto – incompatibilidades de nome lógico são comuns	Baixo – os nomes são pré-configurados
Melhor para	Ambientes de desenvolvimento e teste	Produção e pipelines de CI/CD
Manutenção	Requer atualizações manuais em cada importação	Resolvida automaticamente durante a importação

Agora você pode corrigir o erro de referência de conexão ausente em importações de solução do Copilot Studio criando as referências de conexão necessárias ou editando o XML da solução. Antes de implantar em produção, verifique se todas as referências de conexão estão presentes e se as variáveis de ambiente estão definidas corretamente. Como dica avançada, use o Power Platform CLI para criar scripts de criação de referências de conexão em vários ambientes para reduzir erros manuais.