Risolvere gli errori di modulo Python in Funzioni di Azure

  • Articolo

Questo articolo fornisce informazioni utili per la risoluzione di errori con funzioni Python in Funzioni di Azure. Questo articolo supporta sia i modelli di programmazione v1 che v2. Scegliere il modello da usare dal selettore nella parte superiore dell'articolo.

Nota

Il modello di programmazione Python v2 è supportato solo nel runtime delle funzioni 4.x. Per altre informazioni, vedere Panoramica delle versioni del runtime per Funzioni di Azure.

Di seguito sono riportate le sezioni di risoluzione di problemi comuni in funzioni Python:

In particolare per il modello v2, ecco alcuni problemi noti e le relative soluzioni alternative:

Le guide generali alla risoluzione di problemi per funzioni Python includono:

Risoluzione del problema: ModuleNotFoundError

Questa sezione consente di risolvere gli errori relativi ai moduli nell'app per le funzioni Python. Questi errori generano di solito il messaggio di errore di Funzioni di Azure seguente:

Eccezione: ModuleNotFoundError: nessun modulo denominato 'module_name'.

Questo errore si verifica quando un'app per le funzioni Python non riesce a caricare un modulo Python. La causa principale di questo errore è rappresentata da uno dei problemi seguenti:

Visualizzazione dei file di progetto

Per identificare la causa effettiva del problema, è necessario ottenere i file di progetto Python eseguiti nell'app per le funzioni. Se non si dispone dei file di progetto nel computer locale, è possibile ottenerli in uno dei modi seguenti:

  • Se l'app per le funzioni ha un’impostazione dell'app WEBSITE_RUN_FROM_PACKAGE e il relativo valore è un URL, scaricare il file copiando e incollando l'URL nel browser.
  • Se l'app per le funzioni ha WEBSITE_RUN_FROM_PACKAGE impostato su 1, passare a https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages e scaricare il file dall'URL href più recente.
  • Se l'app per le funzioni non presenta una delle impostazioni dell'app precedenti, passare a https://<app-name>.scm.azurewebsites.net/api/settings e trovare l'URL in SCM_RUN_FROM_PACKAGE. Scaricare il file copiando e incollando l'URL nel browser.
  • Se i suggerimenti risolvono il problema, passare a https://<app-name>.scm.azurewebsites.net/DebugConsole e visualizzare il contenuto in /home/site/wwwroot.

Il resto dell'articolo consente di risolvere le possibili cause di questo errore esaminando il contenuto dell'app per le funzioni, identificando la causa radice e risolvendo il problema specifico.

Diagnosticare ModuleNotFoundError

In questa sezione vengono illustrate in dettaglio le potenziali cause radice degli errori correlati al modulo. Dopo aver individuato la causa radice probabile, è possibile passare alla mitigazione correlata.

Non è stato possibile trovare il pacchetto

Passare a .python_packages/lib/python3.6/site-packages/<package-name> o .python_packages/lib/site-packages/<package-name>. Se il percorso del file non esiste, il percorso mancante costituisce probabilmente la causa radice.

Questo problema può essere causato dall'uso di strumenti di terze parti o obsoleti durante la distribuzione.

Per mitigare questo problema, vedere Abilitare la compilazione remota o Compilare dipendenze native.

Il pacchetto non è risolto con la wheel Linux corretta

Passare a .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info o .python_packages/lib/site-packages/<package-name>-<version>-dist-info. Usare l'editor di testo preferito per aprire il file della wheel e controllare la sezione Tag:. Il problema potrebbe derivare dal fatto che il valore del tag non contiene linux.

Le funzioni Python vengono eseguite solo in Linux in Azure. Il runtime di funzioni V2.x viene eseguito in Debian stretch e il runtime V3.x in Debian Buster. L'artefatto dovrebbe contenere i file binari di Linux corretti. L’uso del flag --build local in Strumenti di base, strumenti di terze parti o obsoleti potrebbe causare l'utilizzo di file binari meno recenti.

Per mitigare il problema, vedere Abilitare la compilazione remota o Compilare dipendenze native.

Il pacchetto non è compatibile con la versione dell'interprete Python

Passare a .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info o .python_packages/lib/site-packages/<package-name>-<version>-dist-info. Nell'editor di testo, aprire il file METADATI e controllare la sezione Classificatori:. Se la sezione non contiene Python :: 3, Python :: 3.6, Python :: 3.7 Python :: 3.8, o Python :: 3.9, la versione del pacchetto è troppo vecchia o, più probabilmente, è già fuori manutenzione.

È possibile controllare la versione di Python dell'app per le funzioni dal portale di Azure. Passare alla pagina della risorsa Panoramica dell'app per le funzioni per trovare la versione di runtime. La versione di runtime supporta le versioni di Python come descritto nella panoramica delle versioni di runtime di Funzioni di Azure.

Per mitigare il problema, vedere Aggiornare il pacchetto alla versione più recente o Sostituire il pacchetto con altri equivalenti.

Il pacchetto è in conflitto con altri pacchetti

Se è stato verificato che il pacchetto è stato risolto correttamente con le wheel Linux adatte, si potrebbe star verificando un conflitto con altri pacchetti. In alcuni pacchetti, la documentazione PyPi può essere utile per chiarire quali moduli siano incompatibili. Ad esempio, in azure 4.0.0 è presente l'istruzione seguente:

Questo pacchetto non è compatibile con azure-storage. Se si è installato azure-storage o se si è installato azure 1.x/2.x senza disinstallare azure-storage, è prima necessario disinstallare azure-storage.

È possibile trovare la documentazione per la versione del pacchetto in https://pypi.org/project/<package-name>/<package-version>.

Per mitigare il problema, vedere Aggiornare il pacchetto alla versione più recente o Sostituire il pacchetto con altri equivalenti.

Il pacchetto supporta solo piattaforme Windows e macOS

Aprire requirements.txt con un editor di testo e verificare che il pacchetto sia in https://pypi.org/project/<package-name>. Alcuni pacchetti vengono eseguiti solo nelle piattaforme Windows e macOS. Ad esempio, pywin32 viene eseguito solo in Windows.

L'errore Module Not Found potrebbe non verificarsi quando si usano Windows o macOS per lo sviluppo locale. Tuttavia, il pacchetto non viene importato in Funzioni di Azure, che usa Linux in fase di esecuzione. Questo problema può essere causato dall'uso di pip freeze per esportare l'ambiente virtuale in requirements.txt dal computer Windows o macOS durante l'inizializzazione del progetto.

Per mitigare il problema, vedere Sostituire il pacchetto con equivalenti o Handcraft requirements.txt.

Attenuare il problema ModuleNotFoundError

Di seguito sono riportate possibili mitigazioni per i problemi relativi ai moduli. Usare le diagnosi indicate in precedenza per determinare quale tra queste soluzioni di mitigazione intentare.

Abilitare la compilazione remota

Assicurarsi che la compilazione remota sia abilitata. Il modo in cui si esegue questa operazione dipende dal metodo di distribuzione.

Controllare che sia installata la versione più recente dell'estensione Funzioni di Azure per Visual Studio Code. Verificare che il file vscode/settings.json esista e che contenga l'impostazione "azureFunctions.scmDoBuildDuringDeployment": true. In caso contrario, creare il file con l'impostazione azureFunctions.scmDoBuildDuringDeployment abilitata e quindi ridistribuire il progetto.

Creare dipendenze native

Assicurarsi che le versioni più recenti di Docker e di Azure Functions Core Tools siano installate. Passare alla cartella del progetto di funzione locale e usare func azure functionapp publish <app-name> --build-native-deps per la distribuzione.

Aggiornare il pacchetto alla versione più recente

Nella versione più recente del pacchetto in https://pypi.org/project/<package-name>, controllare la sezione Classificatori:. Il pacchetto deve essere OS Independent o compatibile con POSIX o POSIX :: Linux nel sistema operativo. Inoltre, il linguaggio di programmazione deve contenere: Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 o Python :: 3.9.

Se questi elementi del pacchetto sono corretti, è possibile aggiornare il pacchetto alla versione più recente modificando la riga <package-name>~=<latest-version> in requirements.txt.

File requirements.txt manuale

Alcuni sviluppatori usano pip freeze > requirements.txt per generare la lista di pacchetti Python per i loro ambienti di sviluppo. Anche se questa soluzione pratica dovrebbe funzionare nella maggior parte dei casi, è possibile che si verifichino problemi negli scenari di distribuzione multipiattaforma, ad esempio lo sviluppo di funzioni in locale in Windows o macOS, ma la pubblicazione in un'app per le funzioni, che viene eseguita in Linux. In questo scenario, è possibile che pip freeze introduca dipendenze impreviste specifiche del sistema operativo o dipendenze per l'ambiente di sviluppo locale. Queste dipendenze possono interrompere l'app per le funzioni Python durante l'esecuzione in Linux.

La procedura consigliata consiste nel controllare l'istruzione import da ogni file .py nel codice sorgente del progetto e quindi archiviare solo i moduli nel file requirements.txt. Questa procedura garantisce che la risoluzione dei pacchetti possa essere gestita correttamente in sistemi operativi diversi.

Sostituire il pacchetto con altri equivalenti

Prima di tutto, esaminare la versione più recente del pacchetto in https://pypi.org/project/<package-name>. Questo pacchetto ha in genere una propria pagina GitHub. Passare alla sezione Problemi in GitHub ed eseguire una ricerca per verificare se il problema sia stato risolto. Se è stato risolto, aggiornare il pacchetto alla versione più recente.

In alcuni casi è possibile che il pacchetto sia stato integrato nella libreria standard Python (ad esempio, pathlib). In tal caso, poiché in Funzioni di Azure viene fornita una certa distribuzione Python (Python 3,6, Python 3,7, Python 3,8 e Python 3.9), il pacchetto in requirements.txt deve essere rimosso.

Tuttavia, se si constata che il problema non è stato risolto e si ha una scadenza imminente, è consigliabile eseguire alcune ricerche per trovare un pacchetto simile per il progetto. In genere, la community di Python offre un'ampia gamma di librerie simili che è possibile usare.

Disabilitare il flag di isolamento delle dipendenze

Settare l'impostazione dell'applicazione PYTHON_ISOLATE_WORKER_DEPENDENCIES su un valore di 0.

Risoluzione del problema: impossibile importare 'cygrpc'

Questa sezione consente di risolvere gli errori correlati a "cygrpc" nell'app per le funzioni Python. Questi errori generano di solito il messaggio di errore di Funzioni di Azure seguente:

Impossibile importare il nome 'cygrpc' da 'grpc._cython'

Questo errore si verifica quando un'app per le funzioni Python non viene avviata con un interprete Python appropriato. La causa principale di questo errore è rappresentata da uno dei problemi seguenti:

Diagnosticare l'errore di riferimento "cygrpc"

Esistono diverse potenziali cause per gli errori che fanno riferimento a cygrpc, descritte in dettaglio in questa sezione.

L'interprete Python non corrisponde all'architettura del sistema operativo

Questa mancata corrispondenza è probabilmente causata da un interprete Python a 32 bit installato su un sistema operativo a 64 bit.

Se ci si trova in un sistema operativo x64, assicurarsi che l'interprete Python versione 3.6, 3.7, 3.8 o 3.9 sia disponibile anche in una versione a 64 bit.

È possibile controllare il livello di bit dell'interprete Python eseguendo i comandi seguenti:

Su Windows in PowerShell, eseguire py -c 'import platform; print(platform.architecture()[0])'.

In una shell simile a Unix, eseguire python3 -c 'import platform; print(platform.architecture()[0])'.

Se esiste una mancata corrispondenza tra bit dell'interprete Python e l'architettura del sistema operativo, scaricare un interprete Python appropriato da Python Software Foundation.

L'interprete Python non è supportato dal ruolo di lavoro Python di Funzioni di Azure

Il ruolo di lavoro Python di Funzioni di Azure supporta solo versioni di Python specifiche.

Verificare se l'interprete Python corrisponde alla versione prevista da py --version in Windows o python3 --version nei sistemi simili a Unix. Assicurarsi che il risultato restituito sia una delle versioni di Python supportate.

Se la versione dell'interprete Python non soddisfa i requisiti per Funzioni di Azure, scaricare invece una versione dell'interprete Python supportata da Funzioni di Python Software Foundation.

Risoluzione del problema: Python è stato chiuso con il codice 137

Gli errori di codice 137 sono in genere causati da problemi di memoria insufficiente nell'app per le funzioni Python. Di conseguenza, viene visualizzato il seguente messaggio di errore di Funzioni di Azure:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python chiuso con codice 137

Questo errore si verifica quando un'app per le funzioni Python subisce un arresto forzato da parte dal sistema operativo con un segnale SIGKILL. Questo segnale indica in genere un errore di memoria insufficiente nel processo Python. La piattaforma Funzioni di Azure presenta una limitazione del servizio che arresta tutte le app per le funzioni che superano questo limite.

Per analizzare il collo di bottiglia della memoria nell'app per le funzioni, vedere Profilare l'app per le funzioni Python nell'ambiente di sviluppo locale.

Risoluzione del problema: Python è stato chiuso con il codice 139

Questa sezione illustra come risolvere errori di segmentazione nell'app per le funzioni Python. Questi errori generano di solito il messaggio di errore di Funzioni di Azure seguente:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException : python chiuso con codice 139

Questo errore si verifica quando un'app per le funzioni Python subisce un arresto forzato da parte dal sistema operativo con un segnale SIGSEGV. Questo segnale indica una violazione della segmentazione della memoria, che può derivare da una lettura imprevista o dalla scrittura in un'area di memoria limitata. Nelle sezioni seguenti viene fornito un elenco delle fondamentali cause comuni.

Regressione da pacchetti di terze parti

Nel file di requirements.txt dell'app per le funzioni, un pacchetto non rimosso viene aggiornato alla versione più recente durante ogni distribuzione in Azure. Gli aggiornamenti dei pacchetti possono potenzialmente introdurre regressioni che influiscono sull'app. Per risolvere questi problemi, impostare le istruzioni import come commento, disabilitare i riferimenti al pacchetto o aggiungere il pacchetto a una versione precedente in requirements.txt.

Eseguire l’unpickling da un file .pkl non valido

Se l'app per le funzioni usa la libreria pickle di Python per caricare un oggetto Python da un file .pkl, è possibile che il file contenga una stringa di byte in formato non valido o un riferimento a un indirizzo non valido. Per risolvere il problema, provare a impostare la funzione pickle.load() come commento.

Collisione di connessione Pyodbc

Se l'app per le funzioni usa il diffuso driver di database ODBC pyodbc, è possibile che più connessioni siano aperte all'interno di una singola app per le funzioni. Per evitare questo problema, usare il modello singleton e assicurarsi che venga usata una sola connessione pyodbc nell'app per le funzioni.

Trigger di sincronizzazione non riusciti

L'errore Sync triggers failed può essere causato da diversi problemi. Una potenziale causa è un conflitto tra le dipendenze definite dal cliente e i moduli predefiniti di Python quando le funzioni vengono eseguite in un piano di servizio app. Per altre informazioni, vedere Gestione pacchetti.

Risoluzione del problema: impossibile caricare file o assembly

Questo errore può essere visualizzato quando si sta operando in locale usando il modello di programmazione v2. Questo errore è causato da un problema noto che sarà risolto in una versione futura.

Di seguito è riportato un messaggio di esempio per questo errore:

DurableTask.Netherite.AzureFunctions: impossibile caricare file o assembly 'Microsoft.Azure.WebJobs.Extensions.DurableTask, Version=2.0.0.0, Culture=neutral, PublicKeyToken=014045d636e89289'.
Non è possibile trovare il file specificato.

L'errore si verifica a causa di un problema relativo alla modalità di memorizzazione nella cache del bundle dell'estensione. Per risolvere il problema, eseguire questo comando con --verbose per visualizzare altri dettagli:

func host start --verbose

È probabile che questo problema di memorizzazione nella cache venga visualizzato quando è presente un log di caricamento dell'estensione come Loading startup extension <> che non è seguito da Loaded extension <>.

Per risolvere il problema:

  1. Trovare il percorso .azure-functions-core-tools eseguendo:

    func GetExtensionBundlePath

  2. Eliminare la directory .azure-functions-core-tools.

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

La directory della cache viene ricreata quando si esegue nuovamente Core Tools.

Risoluzione del problema: impossibile risolvere la connessione ad Archiviazione di Azure

Questo errore potrebbe essere visualizzato nell'output locale come il messaggio seguente:

Microsoft.Azure.WebJobs.Extensions.DurableTask: impossibile risolvere la connessione di Archiviazione di Azure denominata "Archiviazione".
Il valore non può essere Null. (Parametro 'provider')

Questo errore è il risultato del caricamento di estensioni dal bundle in locale. Per risolvere l'errore, eseguire una delle operazioni seguenti:

  • Usare un emulatore di archiviazione, ad esempio Azurite. Questa opzione è valida quando non si prevede di usare un account di archiviazione nell'applicazione per le funzioni.

  • Creare un account di archiviazione e aggiungere una stringa di connessione alla variabile di ambiente AzureWebJobsStorage nel file localsettings.json. Sfruttare questa opzione quando si sta usando un trigger di account di archiviazione o un’associazione con l’applicazione, o se si dispone di un account di archiviazione esistente. Per iniziare, vedere Creare un account di archiviazione.

Funzioni non trovate dopo la distribuzione

Esistono diversi problemi di compilazione comuni che possono causare la mancata individuazione di funzioni Python dall'host dopo una distribuzione apparentemente riuscita:

  • Il pool di agenti deve essere in esecuzione in Ubuntu per garantire che i pacchetti vengano ripristinati correttamente dal passaggio di compilazione. Assicurarsi che il modello di distribuzione richieda un ambiente Ubuntu per la compilazione e la distribuzione.

  • Quando l'app per le funzioni non si trova nella radice del repository di origine, assicurarsi che il passaggio pip install faccia riferimento al percorso corretto in cui creare la cartella .python_packages. Tenere presente che questa posizione fa distinzione tra maiuscole e minuscole, come illustrato in questo esempio di comando:

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

  • Il modello deve necessariamente generare un pacchetto di distribuzione che può essere caricato in /home/site/wwwroot. In Azure Pipelines, questa operazione viene eseguita dall'attività ArchiveFiles.

Problemi di sviluppo nel portale di Azure

Quando si usa il portale di Azure, tenere conto di questi problemi noti e delle relative soluzioni alternative:

  • Per eliminare una funzione da un'app per le funzioni nel portale, rimuovere il codice della funzione dal file stesso. Il pulsante Elimina non funziona per la rimozione della funzione quando si usa il modello di programmazione Python v2.
  • Quando si crea una funzione nel portale, potrebbe venir indicato di usare uno strumento diverso per lo sviluppo. Esistono diversi scenari in cui non è possibile modificare il codice nel portale, tra cui quando è stato rilevato un errore di sintassi. In questi scenari, usare Visual Studio Code o Azure Functions Core Tools per sviluppare e pubblicare il codice della funzione.

Passaggi successivi

Se non è possibile risolvere il problema, contattare il team di Funzioni di Azure:

Segnalare un problema non risolto