Compartilhar via

Solucionar problemas de CI-CD, Azure DevOps e GitHub na análise de Azure Data Factory e Synapse Analytcs

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise completa para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!

Este artigo permite explorar métodos comuns de solução de problemas em CI-CD (Integração Contínua/Implantação Contínua), Azure DevOps e GitHub no Azure Data Factory and Synapse Analytics.

Se você tiver dúvidas ou problemas ao usar o controle do código-fonte ou as técnicas de DevOps, aqui estão alguns artigos que podem ser úteis:

  • Consulte Controle do código-fonte para saber como o controle do código-fonte é praticado no serviço.
  • Consulte CI-CD para saber mais sobre como o DevOps CI-CD é praticado no serviço.

Erros e mensagens comuns

Falha ao conectar-se ao repositório Git devido a um locatário diferente

Problema

Às vezes, você encontra problemas de autenticação como o status HTTP 401. Especialmente quando você tem vários locatários com a conta de convidado, as coisas podem se tornar mais complicadas.

Causa

O token foi obtido do locatário original, mas o serviço está no locatário convidado tentando usar o token para visitar o DevOps no locatário convidado. Esse tipo de acesso de token não é o comportamento esperado.

Recomendação

Você deve usar o token emitido pelo locatário do convidado. Por exemplo, você precisa atribuir o mesmo Microsoft Entra ID como o seu locatário convidado e o seu DevOps, para que ele possa definir corretamente o comportamento do token e usar o locatário correto.

Os parâmetros de modelo no arquivo de parâmetros não são válidos

Problema

Se excluirmos um gatilho no branch Dev, que já está disponível no branch Teste ou Produção com a mesma configuração (como frequência e intervalo), a implantação do pipeline de lançamento será realizada com sucesso e o gatilho correspondente será excluído nos respectivos ambientes. Mas se você tiver uma configuração diferente (como frequência e intervalo) para o gatilho em ambientes de teste/produção e se excluir o mesmo gatilho em Dev, a implantação falhará com um erro.

Causa

O pipeline CI/CD falha na execução com o seguinte erro:

2020-07-20T11:19:02.1276769Z ##[error]Deployment template validation failed: 'The template parameters 'Trigger_Salesforce_properties_typeProperties_recurrence_frequency, Trigger_Salesforce_properties_typeProperties_recurrence_interval, Trigger_Salesforce_properties_typeProperties_recurrence_startTime, Trigger_Salesforce_properties_typeProperties_recurrence_timeZone' in the parameters file are not valid; they are not present in the original template and can therefore not be provided at deployment time. The only supported parameters for this template are 'factoryName, PlanonDWH_connectionString, PlanonKeyVault_properties_typeProperties_baseUrl

Recomendação

O erro ocorre porque muitas vezes excluímos um gatilho, que é parametrizado, portanto, os parâmetros não estarão disponíveis no modelo do ARM (Azure Resource Manager) (porque o gatilho não existe mais). Como o parâmetro não está mais no modelo do ARM, precisamos atualizar os parâmetros substituídos no pipeline DevOps. Caso contrário, cada vez que os parâmetros no modelo do ARM forem alterados, eles deverão atualizar os parâmetros substituídos no pipeline DevOps (na tarefa de implantação).

A atualização do tipo de propriedade não é suportada

Problema

Falha no pipeline de liberação de CI/CD com o seguinte erro:

2020-07-06T09:50:50.8716614Z There were errors in your deployment. Error code: DeploymentFailed.
2020-07-06T09:50:50.8760242Z ##[error]At least one resource deployment operation failed. Please list deployment operations for details. Please see https://aka.ms/DeployOperations for usage details.
2020-07-06T09:50:50.8771655Z ##[error]Details:
2020-07-06T09:50:50.8772837Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8774148Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8775530Z ##[error]Check out the troubleshooting guide to see if your issue is addressed: https://learn.microsoft.com/azure/devops/pipelines/tasks/deploy/azure-resource-group-deployment#troubleshooting
2020-07-06T09:50:50.8776801Z ##[error]Task failed while creating or updating the template deployment.

Causa

Isso ocorre devido a um runtime de integração com o mesmo nome no alocador de destino, mas com um tipo diferente. O runtime de integração precisa ser do mesmo tipo durante a implantação.

Recomendação

  • Considere as Práticas recomendadas para CI/CD

  • Os runtimes de integração não são alterados com frequência e são semelhantes em todos os estágios em seu CI/CD, portanto o serviço espera que você tenha o mesmo nome e tipo de runtime de integração em todos os estágios de CI/CD. Se o nome e os tipos e propriedades forem diferentes, certifique-se de corresponder a configuração de runtime de integração de origem e destino e, em seguida, implante o pipeline de liberação.

  • Se desejar compartilhar runtimes de integração em todas as fases, considere usar um alocador ternário apenas para conter os runtimes de integração compartilhados. Você pode usar esse alocador compartilhado em todos os seus ambientes como um tipo de runtime de integração vinculado.

Falha na criação ou atualização do documento devido à referência inválida

Problema

Ao tentar publicar alterações, você receberá a seguinte mensagem de erro:

"error": { "code": "BadRequest", "message": "The document creation or update failed because of invalid reference '<entity>'.", "target": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/<rgname>/providers/Microsoft.DataFactory/factories/<datafactory>/pipelines/<pipeline>", "details": null }

Causa

Você desanexou a configuração do Git e a configurou novamente com o sinalizador "Importar recursos" selecionado, que define o serviço como "em sincronia". Isso significa que não será necessário fazer alterações durante a publicação.

Resolução

Desanexe a configuração do Git e configure-a novamente e certifique-se de NÃO marcar a caixa de seleção "Importar recursos existentes".

Falha na movimentação do Data Factory de um grupo de recursos para outro

Problema

Não é possível mover o data factory de um grupo de recursos para outro. Falha com o seguinte erro: { "code": "ResourceMoveProviderValidationFailed", "message": "Resource move validation failed. Please see details. Diagnostic information: timestamp 'xxxxxxxxxxxxZ', subscription id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', tracking id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', request correlation id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.", "details": [ { "code": "BadRequest", "target": "Microsoft.DataFactory/factories", "message": "One of the resources contain integration runtimes that are either SSIS-IRs in starting/started/stopping state, or Self-Hosted IRs which are shared with other resources. Resource move is not supported for those resources." } ] }

Resolução

Você pode excluir o SSIS-IR e os IRs compartilhados para permitir a operação de movimentação. Se você não quiser excluir os runtimes de integração, a melhor maneira é seguir o documento de cópia e clonagem para fazer a cópia e, após a conclusão, excluir o data factory antigo.

Não é possível exportar e importar o modelo do ARM

Problema

Não é possível exportar e importar o modelo do ARM. Não havia erro no Portal. No entanto, no rastreamento do navegador, você pode ver o seguinte erro:

Failed to load resource: the server responded with a status code of 401 (Unauthorized)

Causa

Você criou uma função de cliente como usuário e não tinha a permissão necessária. Quando a interface do usuário é carregada, uma série de valores de controle de exposição é verificada. Nesse caso, a função de acesso do usuário não tem permissão para acessar a API queryFeaturesValue. Para acessar essa API, o recurso de parâmetros globais é desativado. O caminho do código de exportação do modelo do ARM é parcialmente dependente do recurso de parâmetros globais.

Resolução

Para resolver o problema, você precisa adicionar a seguinte permissão à sua função: Microsoft.DataFactory/factories/queryFeaturesValue/action. Essa permissão é incluída por padrão na função Colaborador do Data Factory para o Data Factory e a função Colaborador no Synapse Analytics.

Não é possível automatizar a publicação para CI/CD

Causa

Até recentemente, era possível apenas publicar um pipeline para implantações clicando na interface do usuário no Portal. Agora, esse processo pode ser automatizado.

Resolução

O processo de CI/CD foi aprimorado. O recurso de publicação Automatizado pega, valida e exporta todos os recursos de modelo do ARM da UX da interface do usuário. Ele torna a lógica consumível por meio de um pacote npm @microsoft/azure-data-factory-utilities. Esse método permite que você dispare programaticamente essas ações em vez de ter que acessar a interface do usuário e selecionar um botão. Esse método fornece aos pipelines de CI/CD uma experiência de integração contínua verdadeira. Siga as melhorias de publicação de CI/CD para obter detalhes.

Não é possível publicar devido ao limite do modelo do ARM de 4 MB

Problema

Você não pode implantar porque atingiu o limite do Azure Resource Manager de 4 MB de tamanho total do modelo. Você precisa de uma solução para implantar depois de cruzar o limite.

Causa

O Azure Resource Manager restringe o tamanho do modelo a 4 MB. Limite o tamanho do modelo a 4 MB e cada arquivo de parâmetro a 64 KB. O limite de 4 MB se aplica ao estado final do modelo depois que ele foi expandido com definições de recurso iterativo e valores para variáveis e parâmetros. Mas, você ultrapassou o limite.

Resolução

Para pequenas e médias soluções, um único modelo é mais fácil de entender e manter. Você pode ver todos os recursos e valores em um único arquivo. Para cenários avançados, modelos vinculados permitem dividir a solução em componentes desejados. Siga a prática recomendada em Como usar modelos vinculados e aninhados.

O limite de API de DevOps de 20 MB faz com que o ADF dispare duas vezes ou mais, em vez de uma vez

Problema

Ao publicar recursos, o pipeline do Azure disparará duas vezes ou mais, não somente uma vez.

Causa

O Azure DevOps tem o limite de API Rest de 20 MB. Quando o modelo do ARM exceder esse tamanho, o ADF dividirá internamente o arquivo de modelo em vários arquivos com modelos vinculados para resolver esse problema. Como efeito colateral, essa divisão poderá fazer com que os gatilhos do cliente executem mais de uma vez.

Resolução

Use a Publicação automatizada do ADF (preferencial) ou o método de gatilho manual para disparar uma vez, em vez de duas ou mais.

Não é possível se conectar ao GIT Enterprise

Problema

Não é possível conectar o GIT Enterprise devido a problemas de permissão. Você pode ver um erro como 422 - Entidade não processável.

Causa

  • O OAuth não foi configurado para o serviço.
  • A URL está configurada incorretamente. O repoConfiguration deve ser do tipo FactoryGitHubConfiguration

Resolução

Você concede acesso OAuth ao serviço primeiro. Em seguida, você precisa usar a URL correta para se conectar ao GIT Enterprise. A configuração deve ser definida para a(s) organização(ões) do cliente. Por exemplo, o serviço tenta https://hostname/api/v3/search/repositories?q=user%3<customer credential>.... primeiro e falha. Em seguida, ele tenta https://hostname/api/v3/orgs/<org>/<repo>... e é bem-sucedido.

Não é possível recuperar uma instância excluída

Problema

Uma instância do serviço ou o grupo de recursos que a contém, foi excluído e precisa ser recuperado.

Causa

É possível recuperar a instância somente se o controle do código-fonte tiver sido configurado com DevOps ou Git. Esta ação traz todos os recursos publicados mais recentes, mas não restaurará pipelines, conjuntos de dados ou serviços vinculados não publicados. Se não houver controle do código-fonte, não será possível recuperar uma instância excluída do back-end do Azure porque, assim que o serviço receber o comando delete, a instância será excluída permanentemente sem nenhum backup.

Resolução

Para recuperar uma instância de serviço excluída que tem o controle do código-fonte configurado, consulte as etapas abaixo:

  • Crie uma nova instância do serviço.

  • Reconfigure o Git com as mesmas configurações, mas certifique-se de importar recursos existentes para o repositório está selecionado e escolha Novo branch.

  • Crie uma solicitação de pull para mesclar as alterações com o branch de colaboração e publique.

  • Se houver um runtime de integração auto-hospedada em um espaço de trabalho do Data Factory ou do Synapse excluído, uma nova instância do IR deverá ser criada em um novo alocador ou espaço de trabalho. A instância de IR do local ou da máquina virtual deve ser desinstalada e reinstalada e uma nova chave obtida. Depois que a configuração do novo IR for concluída, o serviço vinculado deverá ser atualizado para apontar para o novo IR e o conectado novamente, ou ele falhará com uma \referência inválida de erro.

Não é possível implantar em um estágio diferente usando o método de publicação automática

Problema

O cliente seguiu todas as etapas necessárias, como instalar o pacote NPM e configurar uma fase superior usando o Azure DevOps mas a implantação ainda falhou.

Causa

Embora os pacotes npm possam ser consumidos de várias maneiras, um dos principais benefícios é consumido por meio do Azure Pipeline. Em cada mesclagem em sua ramificação de colaboração, um pipeline pode ser disparado que primeiro valida todo o código e, em seguida, exporta o modelo do ARM para um artefato de build que pode ser consumido por um pipeline de lançamento. No pipeline Inicial, o arquivo YAML deve ser válido e estar completo.

Resolução

A seção a seguir não é válida porque a pasta package.json não é válida.

- task: Npm@1
  inputs:
    command: 'custom'
    workingDir: '$(Build.Repository.LocalPath)/<folder-of-the-package.json-file>' #replace with the package.json folder
    customCommand: 'run build validate $(Build.Repository.LocalPath) /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/yourFactoryName'
  displayName: 'Validate'

Ela deve ter o DataFactory incluído no customCommand desta maneira: 'run build validate $(Build.Repository.LocalPath)/DataFactory/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/yourFactoryName'. Verifique se o arquivo YAML gerado para a fase superior tenha os artefatos JSON necessários.

Extra [ à esquerda exibido no arquivo JSON publicado

Problema

Ao publicar com o DevOps, um [ extra será exibido. O serviço adiciona mais um [ em um modelo do ARM no DevOps automaticamente. Você verá uma expressão do tipo [[ no arquivo JSON.

Causa

Como [ é um caractere reservado para modelos do ARM, um [ extra é adicionado automaticamente para escapar [.

Resolução

Esse é o comportamento normal durante o processo de publicação para CI/CD.

Executar CI/CD durante o progresso/fila da execução de pipeline

Problema

Você deseja executar CI/CD durante o progresso ou a fila da execução do pipeline.

Causa

Quando o pipeline está em progresso/na fila, você precisa primeiro monitorar o pipeline e as atividades. Em seguida, você pode optar por aguardar até a conclusão do pipeline ou cancelar a executar o pipeline.

Resolução

É possível monitorar o pipeline usando o SDK, o Azure Monitor ou o Monitor. Em seguida, você pode seguir as Melhores práticas de CI/CD para continuar se orientando.

Executar o TESTE DE UNIDADE durante o desenvolvimento e a implantação

Problema

Você deseja executar testes de unidade durante o desenvolvimento e a implantação de pipelines.

Causa

Durante os ciclos de desenvolvimento e implantação, talvez você queira testar o pipeline de unidade antes de publicar manual ou automaticamente o pipeline. A automação de teste permite executar mais testes em menos tempo com capacidade de repetição garantida. Testar novamente e de modo automático todos os pipelines antes da implantação oferecerá alguma proteção contra falhas de regressão. O teste automatizado é um componente fundamental das abordagens de desenvolvimento de software de CI/CD: a inclusão de testes automatizados em pipelines de implantação de CI/CD pode melhorar significativamente a qualidade. No longo prazo, os artefatos de pipeline testados são reutilizados, economizando tempo e custos.

Resolução

Como os clientes podem ter requisitos de teste de unidade diferentes com conjuntos de habilidades diferentes, a prática comum é seguir as etapas abaixo:

  1. Configure o projeto de CI/CD no Azure DevOps ou desenvolva a estratégia de teste controlada pelo SDK do tipo .NET/PYTHON/REST.
  2. Para CI/CD, crie um artefato de compilação contendo todos os scripts e implante recursos no pipeline de lançamento. Na abordagem de SDK, desenvolva unidades de teste usando o PyTest em Python, Nunit em C# usando o SDK do .NET e assim por diante.
  3. Execute testes de unidade como parte do pipeline de lançamento ou independentemente com o SDK Python/PowerShell/.NET/REST do ADF.

Por exemplo, você deseja excluir duplicatas em um arquivo e, em seguida, armazenar o arquivo coletado como tabela em um banco de dados. Para testar o pipeline, configure um projeto de CI/CD usando o Azure DevOps. Configure um estágio de pipeline de TESTE em que você implantará o pipeline desenvolvido. Configure o estágio de TESTE para executar testes do Python e garantir que os dados da tabela sejam os esperados. Se você não usar CI/CD, use Nunit para disparar pipelines implantados com os testes que você desejar. Quando estiver satisfeito com os resultados, você poderá, por fim, publicar o pipeline em uma instância de produção.

O pipeline é executado temporariamente após a implantação de CI/CD ou atualizações de criação

Problema

Após algum tempo, as novas execuções de pipeline começarão a ter sucesso sem qualquer ação do usuário após falhas temporárias.

Causa

Há vários cenários que podem disparar esse comportamento, que envolvem uma nova versão de um recurso dependente sendo chamado pela versão antiga do recurso pai. Por exemplo, suponha que um pipeline filho existente chamado por "executar pipeline" seja atualizado para ter os parâmetros obrigatórios e que o pipeline pai existente seja atualizado para passar esses parâmetros. Se a implantação ocorrer durante a execução de um pipeline pai, mas antes da atividade Execute Pipeline, a versão antiga do pipeline chamará a nova versão do pipeline filho e os parâmetros esperados não serão transmitidos. Isso faz com que o pipeline falhe com um UserError. Isso também pode ocorrer com outros tipos de dependências, como se uma alteração significativa é feita ao serviço vinculado durante uma execução de pipeline que faz referência a ele.

Resolução

As novas execuções do pipeline pai iniciarão automaticamente o sucesso, portanto, normalmente, nenhuma ação é necessária. No entanto, para evitar esses erros, os clientes devem considerar as dependências durante a criação e o planejamento de implantações para evitar alterações significativas.

Não é possível parametrizar o tempo de execução de integração no serviço vinculado

Problema

Necessidade de parametrizar o tempo de execução de integração do serviço vinculado

Causa

Não há suporte para esse recurso.

Resolução

Você precisa selecionar manualmente e definir um runtime de integração. Você também pode usar a API do PowerShell para alterar. Essa alteração pode ter implicações downstream.

Atualizar/alterar o runtime de integração durante a integração contínua e entrega contínua.

Problema

Alterando o nome do runtime de integração durante a implantação da integração contínua e entrega contínua.

Causa

Não há suporte para parametrização de uma referência de entidade (Runtime de integração no serviço vinculado, Conjuntos de dados na atividade, Serviço Vinculado no conjunto de dados). Alterar o nome do runtime durante a implantação faz com que o recurso dependente (recurso referenciando o runtime de integração) se torne malformado com referência inválida.

Resolução

O Data Factory espera que você tenha o mesmo nome e tipo de runtime de integração em todas as fases do CI/CD.

Falha na implantação de modelo do ARM com o erro DataFactoryPropertyUpdateNotSupported

Problema

Falha na implantação de modelo do ARM com um erro como DataFactoryPropertyUpdateNotSupported: não há suporte para a atualização do tipo de propriedade.

Causa

A implantação de modelo do ARM está tentando alterar o tipo de um runtime de integração existente. Isso não é permitido e causará uma falha de implantação porque o data factory requer o mesmo nome e tipo de runtime de integração em todos os estágios de CI/CD.

Resolução

Se desejar compartilhar runtimes de integração em todas as fases, considere usar um alocador ternário apenas para conter os runtimes de integração compartilhados. Você pode usar esse alocador compartilhado em todos os seus ambientes como um tipo de runtime de integração vinculado. Para obter mais informações, confira Integração e entrega contínuas - Azure Data Factory

A publicação do GIT pode falhar devido a arquivos PartialTempTemplates

Problema

Quando houver 1000 s de arquivos json do modelo do ARM temporários antigos na pasta PartialTemplates, a publicação poderá falhar.

Causa

Na publicação, o ADF busca todos os arquivos dentro de cada pasta no branch de colaboração. No passado, a publicação gerava duas pastas no branch de publicação: PartialArmTemplates e LinkedTemplates. Arquivos PartialArmTemplates não são mais gerados. No entanto, como pode haver muitos arquivos antigos (milhares) na pasta PartialArmTemplates, isso pode fazer com que muitas solicitações sejam feitas para GitHub na publicação e o limite de taxa seja atingido.

Resolução

Exclua a pasta PartialTemplates e republique-a. Você também pode excluir os arquivos temporários nessa pasta.

Incluir parâmetros globais na opção modelo do ARM não funciona

Problema

Se você estiver usando o modelo de parametrização padrão antigo, a nova maneira de incluir parâmetros globais do Hub de Gerenciamento não funcionará.

Causa

O modelo de parametrização padrão deve incluir todos os valores da lista de parâmetros global.

Resolução

  • Use o modelo de parametrização padrão atualizado como uma migração única para o novo método de inclusão de parâmetros globais. Esse modelo faz referência a todos os valores na lista de parâmetros global. Você também precisará atualizar a tarefa de implantação no pipeline de lançamento se já estiver substituindo os parâmetros de modelo nesse pipeline.
  • Atualize os nomes do parâmetro de modelo no pipeline de CI/CD se você já está substituindo os parâmetros de modelo (para parâmetros globais).

Código de erro: InvalidTemplate

Problema

A mensagem diz que não é possível analisar a expressão. A expressão passada no conteúdo dinâmico de uma atividade não está sendo processada corretamente devido a um erro de sintaxe.

Causa

O conteúdo dinâmico não é escrito de acordo com os requisitos de linguagem de expressão.

Resolução

  • Para execução de depuração, verifique expressões no pipeline dentro da ramificação git atual.
  • Para Execução de gatilho, verifique expressões no pipeline no modo Dinâmico.

Conteúdo relacionado

Para obter mais ajuda com a solução de problemas, experimente os seguintes recursos: