Solucionar erros de Python no Azure Functions

  • Artigo

Este artigo fornece informações para ajudar a solucionar erros com as funções do Python no Azure Functions. Este artigo dá suporte aos modelos de programação v1 e v2. Escolha o modelo que você deseja usar no seletor na parte superior do artigo.

Observação

O modelo de programação do Python v2 recebe suporte apenas no Functions Runtime 4.x. Para obter mais informações, consulte Visão geral de versões do Azure Functions runtime.

Aqui estão as seções de solução para problemas comuns em funções do Python:

Especificamente para o modelo v2, aqui estão alguns problemas conhecidos e suas soluções alternativas:

Os guias gerais de solução de problemas para funções do Python incluem:

Solução de problemas: ModuleNotFoundError

Esta seção ajuda a solucionar erros relacionados a módulos no seu aplicativo de funções do Python. Esses erros normalmente resultam na seguinte mensagem de erro do Azure Functions:

Exceção: ModuleNotFoundError: nenhum módulo chamado 'module_name'.

Esse erro ocorre quando um aplicativo de função do Python falha ao carregar um módulo do Python. A causa raiz desse erro é um dos seguintes problemas:

Exibir arquivos de projeto

Para identificar a causa real do problema, você precisa obter os arquivos de projeto do Python executados no seu aplicativo de funções. Se você não tiver os arquivos de projeto no computador local, poderá obtê-los de uma das seguintes maneiras:

  • Se o aplicativo de funções tiver uma configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE e seu valor for um URL, baixe o arquivo copiando e colando o URL em seu navegador.
  • Se o aplicativo de função estiver WEBSITE_RUN_FROM_PACKAGE definido como 1, acesse https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages e faça o download do arquivo usando a URL mais recente href.
  • Se o aplicativo de funções não tiver nenhuma das configurações de aplicativo anteriores, acesse o https://<app-name>.scm.azurewebsites.net/api/settings e localize o URL em SCM_RUN_FROM_PACKAGE. Baixe o arquivo copiando e colando o URL no seu navegador.
  • Se alguma sugestão resolver o problema, acesse https://<app-name>.scm.azurewebsites.net/DebugConsole e exiba o conteúdo em /home/site/wwwroot.

O restante deste artigo ajuda a solucionar possíveis causas desse erro com a inspeção do conteúdo do aplicativo de funções, a identificação da causa raiz e a resolução do problema específico.

Diagnosticar ModuleNotFoundError

Esta seção detalha possíveis causas raiz de erros relacionados a módulos. Depois de encontrar a causa raiz provável, você pode ir para a mitigação relacionada.

Não foi possível encontrar o pacote

Acesse .python_packages/lib/python3.6/site-packages/<package-name> ou .python_packages/lib/site-packages/<package-name>. Se o caminho do arquivo não existir, a falta desse caminho provavelmente será a causa raiz.

O uso de ferramentas de terceiros ou desatualizadas durante a implantação pode causar esse problema.

Para atenuar esse problema, consulte Habilitar compilação remota ou Dependências de compilação nativas.

O pacote não foi resolvido com o wheel apropriado do Linux

Acesse .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info ou .python_packages/lib/site-packages/<package-name>-<version>-dist-info. Use seu editor de texto favorito para abrir o arquivo do wheel e marque a seção Tag: . O problema pode ser que o valor da marca não contenha linux.

As funções do Python são executadas somente no Linux no Azure. O runtime v2.x do Functions é executado no Debian Stretch e o runtime v3.x é executado no Debian Buster. Espera-se que o artefato contenha os binários corretos do Linux. Ao usar o sinalizador --build local em ferramentas do Core Tools, de terceiros ou desatualizadas, ele pode fazer com que binários mais antigos sejam usados.

Para atenuar o problema, consulte Habilitar compilação remota ou Dependências de compilação nativas.

O pacote é incompatível com a versão do interpretador do Python

Acesse .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info ou .python_packages/lib/site-packages/<package-name>-<version>-dist-info. Em seu editor de texto, abra o arquivo METADATA e marque a seção Classificadores:. Se a seção não contiver Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 ou Python :: 3.9, a versão do pacote é muito antiga ou, mais provavelmente, já está fora de manutenção.

Você pode verificar a versão do Python do seu aplicativo de funções no portal do Azure. Navegue até a página de recursos Visão geral do aplicativo de funções para encontrar a versão de runtime. A versão de runtime dá suporte a versões do Python, conforme descrito na Visão geral das versões de runtime do Azure Functions.

Para atenuar o problema, consulte Atualizar o pacote para a versão mais recente ou Substituir o pacote por equivalentes.

O pacote está em conflito com outros pacotes

Se você verificou que o pacote foi resolvido corretamente com os wheels adequados do Linux, pode haver um conflito com outros pacotes. Em alguns pacotes, a documentação do PyPi pode esclarecer os módulos incompatíveis. Por exemplo, em azure 4.0.0, você encontra a seguinte declaração:

Esse pacote não é compatível com o azure-storage. Se você instalou o azure-storage ou o azure 1.x/2.x e não desinstalou o azure-storage, desinstale o azure-storage primeiro.

Você pode encontrar a documentação para a versão do seu pacote em https://pypi.org/project/<package-name>/<package-version>.

Para atenuar o problema, consulte Atualizar o pacote para a versão mais recente ou Substituir o pacote por equivalentes.

O pacote dá suporte apenas às plataformas Windows e macOS

Abra requirements.txt com um editor de texto e verifique o pacote em https://pypi.org/project/<package-name>. Alguns pacotes são executados somente em plataformas Windows e macOS. Por exemplo, pywin32 é executado apenas no Windows.

O erro Module Not Found pode não ocorrer quando você está usando o Windows ou o macOS para desenvolvimento local. No entanto, o pacote não é importado no Azure Functions, que usa o Linux no runtime. Esse problema provavelmente é causado pelo uso de pip freeze para exportar o ambiente virtual para requirements.txt, a partir do seu computador Windows ou macOS durante a inicialização do projeto.

Para atenuar o problema, consulte Substituir o pacote por equivalentes ou Criar requirements. txt.

Mitigar ModuleNotFoundError

Veja a seguir as possíveis mitigações para problemas relacionados a módulo. Use os diagnósticos mencionados anteriormente para determinar quais dessas mitigações tentar.

Habilitar a compilação remota

Verifique se a compilação remota está habilitada. A maneira como você se certifica depende do seu método de implantação.

Verifique se a versão mais recente da extensão do Azure Functions Visual Studio Code está instalada. Verifique se o arquivo .vscode/settings.json existe e se ele contém a configuração "azureFunctions.scmDoBuildDuringDeployment": true. Caso contrário, crie o arquivo com a configuração azureFunctions.scmDoBuildDuringDeployment habilitada e, em seguida, reimplante o projeto.

Compilar dependências nativas

Veja se as versões mais recentes do Docker e do Azure Functions Core Tools estão instaladas. Acesse a pasta do projeto de função local e use func azure functionapp publish <app-name> --build-native-deps para implantação.

Atualizar seu pacote para a versão mais recente

Na versão mais recente do pacote do https://pypi.org/project/<package-name>, marque a seção Classificadores:. O pacote deve ser OS Independent ou compatível com POSIX ou POSIX :: Linux no sistema operacional. Além disso, a linguagem de programação deve conter: Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 ou Python :: 3.9.

Se esses itens do pacote estiverem corretos, você poderá atualizar o pacote para a versão mais recente alterando a linha <package-name>~=<latest-version> em requirements.txt.

Criar requirements.txt

Alguns desenvolvedores usam pip freeze > requirements.txt para gerar a lista de pacotes do Python para seus ambientes de desenvolvimento. Embora essa conveniência funcione na maioria dos casos, pode haver problemas em cenários de implantação entre plataformas, por exemplo, ao desenvolver localmente funções no Windows ou no macOS, mas publicar em um aplicativo de funções executado no Linux. Nesse cenário, pip freeze pode introduzir dependências específicas do sistema operacional inesperadas ou dependências para seu ambiente de desenvolvimento local. Essas dependências podem interromper o aplicativo de funções do Python quando ele é executado no Linux.

A melhor prática é verificar a instrução de importação de cada arquivo .py no código-fonte do projeto e, em seguida, apenas fazer check-in apenas dos módulos no arquivo requirements.txt. Essa prática garante que a resolução de pacotes possa ser tratada corretamente em sistemas operacionais diferentes.

Substituir os pacotes por equivalentes

Primeiro, dê uma olhada na versão mais recente do pacote em https://pypi.org/project/<package-name>. Esse pacote geralmente tem sua própria página do GitHub. Acesse a seção Problemas no GitHub e pesquise para ver se o problema foi corrigido. Se tiver sido corrigido, atualize o pacote para a versão mais recente.

Às vezes, o pacote pode ter sido integrado na Biblioteca do Python Standard (como pathlib). Nesse caso, como fornecemos uma determinada distribuição do Python no Azure Functions (Python 3.6, Python 3.7, Python 3.8 e Python 3.9), o pacote no arquivo requirements.txt deve ser removido.

No entanto, se você está descobrindo que o problema não foi corrigido e estiver perto de um prazo final, aconselhamos fazer uma pesquisa para encontrar um pacote semelhante para seu projeto. Normalmente, a comunidade Python fornece uma grande variedade de bibliotecas semelhantes que você pode usar.

Desabilitar o sinalizador de isolamento de dependência

Defina a configuração de aplicativo PYTHON_ISOLATE_WORKER_DEPENDENCIES para um valor de 0.

Solução de problemas: não é possível importar 'cygrpc'

Esta seção ajuda a solucionar erros relacionados a 'cygrpc' no seu aplicativo de funções do Python. Esses erros normalmente resultam na seguinte mensagem de erro do Azure Functions:

Não é possível importar o nome 'cygrpc' de 'grpc._cython'

Esse erro ocorre quando um aplicativo de funções do Python não consegue ser iniciado com um interpretador de Python adequado. A causa raiz desse erro é um dos seguintes problemas:

Diagnosticar o erro de referência 'cygrpc'

Há várias causas possíveis para os erros que fazem referência a cygrpc, que são detalhadas nesta seção.

O interpretador do Python não corresponde à arquitetura do sistema operacional

Essa incompatibilidade é provavelmente causado por um interpretador do Python de 32 bits instalado em seu sistema operacional de 64 bits.

Se estiver executando em um sistema operacional x64, verifique se o interpretador do Python versão 3.6, 3.7, 3.8 ou 3.9 também está em uma versão de 64 bits.

Você pode verificar o número de bit do interpretador do Python executando os seguintes comandos:

No PowerShell do Windows, execute py -c 'import platform; print(platform.architecture()[0])'.

Em um shell semelhante ao Unix, execute python3 -c 'import platform; print(platform.architecture()[0])'.

Se houver uma incompatibilidade entre o número de bit do interpretador de Python e a arquitetura do sistema operacional, baixe um interpretador do Python adequado na Python Software Foundation.

O interpretador do Python não tem suporte na função de trabalho de Python do Azure Functions

O Python Worker do Azure Functions oferece suporte apenas às versões específicas do Python.

Verifique se o interpretador Python corresponde à sua versão esperada em py --version no Windows ou python3 --version em sistemas tipo Unix. Verifique se o resultado do retorno é uma das versões do Python com suporte.

Se a versão do interpretador do Python não atender aos requisitos do Azure Functions, baixe uma versão do interpretador do Python compatível com o Functions do Python Software Foundation.

Solução de problemas: o Python foi encerrado com o código 137

Erros de código 137 normalmente são causados por problemas de memória no aplicativo de funções do Python. Como resultado, você recebe a seguinte mensagem de erro do Azure Functions:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python encerrado com o código 137

Esse erro ocorre quando um aplicativo de funções do Python é forçado a terminar pelo sistema operacional com um sinal de SIGKILL. Esse sinal geralmente indica um erro de memória no processo do Python. A plataforma do Azure Functions tem uma limitação de serviço que encerra todos os aplicativos de funções que excederem esse limite.

Para analisar o gargalo de memória no seu aplicativo de funções, consulte Aplicativo de funções do Python de Perfil no ambiente de desenvolvimento local.

Solução de problemas: o Python foi encerrado com o código 139

Esta seção ajuda a solucionar erros relacionados a falhas de segmentação no seu aplicativo de funções do Python. Esses erros normalmente resultam na seguinte mensagem de erro do Azure Functions:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: o Python encerrado com o código 139

Esse erro ocorre quando um aplicativo de funções do Python é forçado a terminar pelo sistema operacional com um sinal de SIGSEGV. Este sinal indica violação da segmentação de memória, que pode resultar de uma leitura ou escrita inesperadas em uma região de memória restrita. Nas seções a seguir, fornecemos uma lista de causas raiz mais comuns.

Uma regressão de pacotes de terceiros

No arquivo requirements.txt do seu aplicativo de funções, um pacote desafixado é atualizado para a versão mais recente durante cada implantação para o Azure. Possivelmente, as atualizações de pacotes podem introduzir regressões que afetam seu aplicativo. Para recuperar esses problemas, comente as instruções de importação, desabilite as referências do pacote ou fixe o pacote em uma versão anterior no requirements.txt.

Desempacotando a partir de um arquivo .pkl malformado

Se o aplicativo de funções estiver usando a biblioteca de pickle do Python para carregar o objeto Python de um arquivo .pkl, é possível que o arquivo contenha uma cadeia de caracteres de bytes malformada ou uma referência de endereço inválida. Para contornar esse problema, tente comentar a função pickle.load().

Colisão de conexão pyodbc

Se seu aplicativo de funções estiver usando o popular driver de banco de dados ODBC pyodbc, é possível que várias conexões sejam abertas em um único aplicativo de funções. Para evitar esse problema, use o padrão singleton e verifique se apenas uma conexão pyodbc é usada em todo o aplicativo de funções.

Falha nos gatilhos de sincronização

O erro Sync triggers failed pode ser causado por vários problemas. Uma possível causa é um conflito entre dependências definidas pelo cliente e módulos internos do Python quando suas funções são executadas em um plano do Serviço de Aplicativo. Para obter mais informações, consulte Gerenciamento de pacotes.

Solução de problemas: não foi possível carregar o arquivo ou assembly

Você pode ver esse erro quando estiver executando localmente usando o modelo de programação v2. Esse erro é causado por um problema conhecido que será resolvido em uma próxima versão.

Esta é uma mensagem de exemplo desse erro:

DurableTask.Netherite.AzureFunctions: não foi possível carregar o arquivo ou assembly 'Microsoft.Azure.WebJobs.Extensions.DurableTask, Version=2.0.0.0, Culture=neutral, PublicKeyToken=014045d636e89289'.
O sistema não pode encontrar o arquivo especificado.

O erro ocorre por causa de um problema com a forma como o pacote de extensão foi armazenado em cache. Para solucionar o problema, execute este comando com --verbose para ver mais detalhes:

func host start --verbose

É provável que você esteja vendo esse problema de cache quando vir um log de carregamento de extensão como Loading startup extension <> que não é seguido por Loaded extension <>.

Para resolver o problema:

  1. Localize o caminho .azure-functions-core-tools executando:

    func GetExtensionBundlePath

  2. Exclua o diretório .azure-functions-core-tools.

    rm -r <insert path>/.azure-functions-core-tools

O diretório de cache é recriado quando você reexecuta o Core Tools.

Solução de problemas: não é possível resolver a conexão do Armazenamento do Azure

Você pode ver esse erro na saída local como a seguinte mensagem:

Microsoft.Azure.WebJobs.Extensions.DurableTask: não é possível resolver a conexão de Armazenamento do Azure chamada 'Armazenamento'.
O valor não pode ser nulo. (Parâmetro 'provider')"

Esse erro é resultado de como as extensões são carregadas no pacote localmente. Para resolver esse erro, execute uma das seguintes ações:

  • Use um emulador de armazenamento, como o Azurite. Essa opção é boa quando você não está planejando usar uma conta de armazenamento no aplicativo de funções.

  • Crie uma conta de armazenamento e adicione uma cadeia de conexão à variável de ambiente AzureWebJobsStorage no arquivo localsettings.json. Use essa opção quando estiver usando um gatilho ou associação de conta de armazenamento com o aplicativo ou se você tiver uma conta de armazenamento existente. Para usá-los, consulte Criar uma conta de armazenamento.

Funções não encontradas após a implantação

Há vários problemas comuns de build que podem fazer com que as funções do Python não sejam encontradas pelo host após uma implantação aparentemente bem-sucedida:

  • O pool de agentes deve estar em execução no Ubuntu para garantir que os pacotes sejam restaurados corretamente da etapa de build. Verifique se o modelo de implantação requer um ambiente Ubuntu para compilação e implantação.

  • Quando o aplicativo de funções não estiver na raiz do repositório de origem, verifique se a etapa pip install faz referência ao local correto para criar a pasta .python-packages. Tenha em mente que esse local diferencia maiúsculas de minúsculas, como neste exemplo de comando:

    pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt

  • O modelo deve gerar um pacote de implantação que possa ser carregado em /home/site/wwwroot. No Azure Pipelines, isso é feito pela tarefa ArchiveFiles.

Problemas de desenvolvimento no portal do Azure

Ao usar o portal do Azure, leve em conta esses problemas conhecidos e suas soluções alternativas:

  • Para excluir uma função de um aplicativo de funções no portal, remova o código da função do próprio arquivo. O botão Excluir não funciona para remover a função ao usar o modelo de programação Python v2.
  • Ao criar uma função no portal, você pode ser advertido a usar uma ferramenta diferente para desenvolvimento. Há vários cenários em que você não pode editar seu código no portal, incluindo quando um erro de sintaxe foi detectado. Nesses cenários, use Visual Studio Code ou Azure Functions Core Tools para desenvolver e publicar seu código de função.

Próximas etapas

Se não for possível resolver o problema, entre em contato com a equipe do Azure Functions:

Relatar um problema não resolvido