Risolvere gli errori di modulo Python in Funzioni di Azure
Questo articolo fornisce informazioni utili per risolvere gli errori relativi alle 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 dei problemi comuni nelle funzioni Python:
In particolare con il modello v2, ecco alcuni problemi noti e le relative soluzioni alternative:
- Impossibile caricare il file o l'assembly
- Impossibile risolvere la connessione Archiviazione di Azure denominata Archiviazione
Le guide generali alla risoluzione dei problemi per Le funzioni Python includono:
Risoluzione dei problemi: ModuleNotFoundError
Questa sezione consente di risolvere gli errori correlati al modulo 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:
- Non è stato possibile trovare il pacchetto
- Il pacchetto non viene risolto con la wheel Linux corretta
- Il pacchetto non è compatibile con la versione dell'interprete Python
- Il pacchetto è in conflitto con altri pacchetti
- Il pacchetto supporta solo piattaforme Windows e macOS
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
WEBSITE_RUN_FROM_PACKAGE
dell'app e il relativo valore è un URL, scaricare il file copiando e incollando l'URL nel browser. - Se l'app per le funzioni è
WEBSITE_RUN_FROM_PACKAGE
impostata su1
, passare ahttps://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages
e scaricare il file dall'URL più recentehref
. - Se l'app per le funzioni non ha una delle impostazioni dell'app precedenti, passare a
https://<app-name>.scm.azurewebsites.net/api/settings
e trovare l'URL inSCM_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.
L'uso di strumenti di terze parti o obsoleti durante la distribuzione potrebbe causare questo problema.
Per attenuare questo problema, vedere Abilitare la compilazione remota o Compilare dipendenze native.
Il pacchetto non viene risolto con la rotellina Linux appropriata
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 essere 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 viene eseguito in Debian Buster. L'artefatto dovrebbe contenere i file binari di Linux corretti. Quando si usa il --build local
flag in Strumenti di base, strumenti di terze parti o strumenti obsoleti, potrebbe causare l'uso di file binari meno recenti.
Per attenuare 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 METADATA 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 attenuare il problema, vedere Aggiornare il pacchetto alla versione più recente o Sostituire il pacchetto con equivalenti.
Il pacchetto è in conflitto con altri pacchetti
Se si è verificato che il pacchetto viene risolto correttamente con le ruote Linux appropriate, potrebbe verificarsi un conflitto con altri pacchetti. In alcuni pacchetti, la documentazione di PyPi potrebbe chiarire i moduli incompatibili. Ad esempio, in azure 4.0.0
è possibile trovare l'istruzione seguente:
Questo pacchetto non è compatibile con azure-storage. Se azure-storage è stato installato o se azure 1.x/2.x è stato installato e non è stato disinstallato 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 attenuare il problema, vedere Aggiornare il pacchetto alla versione più recente o Sostituire il pacchetto con 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 usa 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 potrebbe essere causato dall'uso pip freeze
di per esportare l'ambiente virtuale in requirements.txt dal computer Windows o macOS durante l'inizializzazione del progetto.
Per attenuare 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 di queste mitigazioni provare.
Abilitare la compilazione remota
Assicurarsi che la compilazione remota sia abilitata. Il modo in cui si verifica 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 siano installate le versioni più recenti di Docker e Funzioni di Azure Core Tools. 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 di 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 quando è in 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 e cercare per verificare se il problema è stato risolto. Se è stato risolto, aggiornare il pacchetto alla versione più recente.
In alcuni casi, il pacchetto potrebbe essere stato integrato nella libreria standard Python ( ad esempio pathlib
). In tal caso, poiché viene fornita una determinata distribuzione python in Funzioni di Azure (Python 3.6, Python 3.7, Python 3.8 e Python 3.9), il pacchetto nel file requirements.txt deve essere rimosso.
Tuttavia, se si scopre che il problema non è stato risolto e si è in scadenza, è 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
Impostare l'impostazione dell'applicazione PYTHON_ISOLATE_WORKER_DEPENDENCIES su un valore di 0
.
Risoluzione dei problemi: 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:
- L'interprete Python non corrisponde all'architettura del sistema operativo
- L'interprete Python non è supportato da Funzioni di Azure ruolo di lavoro Python
Diagnosticare l'errore di riferimento "cygrpc"
Esistono diverse cause possibili per gli errori che fanno riferimento cygrpc
a , descritti 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 nel sistema operativo a 64 bit.
Se si esegue 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:
In 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 da Funzioni di Azure ruolo di lavoro Python
Il ruolo di lavoro Python Funzioni di Azure supporta solo versioni python specifiche.
Verificare se l'interprete Python corrisponde alla versione prevista in py --version
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 da Python Software Foundation.
Risolvere i problemi: 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 messaggio di errore seguente 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 viene forzata a terminare dal sistema operativo con un SIGKILL
segnale. Questo segnale indica in genere un errore di memoria insufficiente nel processo Python. La piattaforma Funzioni di Azure presenta una limitazione del servizio che termina 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 dei problemi: Python è stato chiuso con il codice 139
Questa sezione illustra come risolvere gli 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 viene forzata a terminare dal sistema operativo con un SIGSEGV
segnale. Questo segnale indica la 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 di cause radice comuni.
Regressione da pacchetti di terze parti
Nel file di requirements.txt dell'app per le funzioni, un pacchetto 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 come commento le istruzioni import, disabilitare i riferimenti al pacchetto o aggiungere il pacchetto a una versione precedente in requirements.txt.
Unpickling da un file con estensione pkl non valido
Se l'app per le funzioni usa la libreria pickle Python per caricare un oggetto Python da un file con estensione pkl , è possibile che il file contenga una stringa di byte in formato non valido o un riferimento indirizzo non valido. Per risolvere il problema, provare a impostare come commento la pickle.load()
funzione.
Collisione di connessione Pyodbc
Se l'app per le funzioni usa il popolare 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 possibile causa è un conflitto tra le dipendenze definite dal cliente e i moduli predefiniti python quando le funzioni vengono eseguite in un piano di servizio app. Per altre informazioni, vedere Gestione pacchetti.
Risoluzione dei problemi: impossibile caricare il file o l'assembly
Questo errore può essere visualizzato quando si esegue localmente usando il modello di programmazione v2. Questo errore è causato da un problema noto da risolvere in una versione futura.
Questo è un messaggio di esempio per questo errore:
DurableTask.Netherite.AzureFunctions: impossibile caricare il file o l'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 venga visualizzato questo problema di memorizzazione nella cache quando viene visualizzato un log di caricamento dell'estensione come Loading startup extension <>
questo non è seguito da Loaded extension <>
.
Per risolvere il problema:
Trovare il
.azure-functions-core-tools
percorso eseguendo:func GetExtensionBundlePath
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 dei problemi: impossibile risolvere la connessione Archiviazione di Azure
Questo errore potrebbe essere visualizzato nell'output locale come messaggio seguente:
Microsoft.Azure.WebJobs.Extensions.DurableTask: impossibile risolvere la connessione Archiviazione di Azure denominata "Archiviazione".
Il valore non può essere Null. (Parametro 'provider')
Questo errore è il risultato del caricamento delle estensioni dal bundle in locale. Per risolvere l'errore, eseguire una delle azioni 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 un stringa di connessione alla
AzureWebJobsStorage
variabile di ambiente nel file localsettings.json. Usare questa opzione quando si usa un trigger o un'associazione di account di archiviazione 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 delle 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
pip install
passaggio faccia riferimento al percorso corretto in cui creare la.python-packages
cartella. Tenere presente che questa posizione fa distinzione tra maiuscole e minuscole, ad esempio in questo esempio di comando:pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt
Il modello deve 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 nella portale di Azure
Quando si usa il portale di Azure, tenere conto di questi problemi noti e delle relative soluzioni alternative:
- Esistono limitazioni generali per la scrittura del codice della funzione nel portale. Per altre informazioni, vedere Limitazioni di sviluppo nella portale di Azure.
- 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 rimuovere la funzione quando si usa il modello di programmazione Python v2.
- Quando si crea una funzione nel portale, è possibile che venga 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 Funzioni di Azure Core Tools per sviluppare e pubblicare il codice della funzione.
Passaggi successivi
Se non è possibile risolvere il problema, contattare il team Funzioni di Azure: