Condividi tramite

Risolvere gli errori di modulo Python in Funzioni di Azure

Questo articolo contiene informazioni utili per la risoluzione di errori delle funzioni Python in Funzioni di Azure. L'articolo supporta i modelli di programmazione v1 e v2. Scegliere il modello da usare nel selettore nella parte superiore dell'articolo.

Note

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 per la risoluzione di problemi comuni nelle funzioni Python:

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

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 l'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, andare 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, andare 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 il problema è risolto, andare 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 attenuare il problema, vedere Abilitare la compilazione remota o Creare dipendenze native.

Il pacchetto non viene risolto con il gruppo wheel Linux corretto

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 wheel e controllare la sezione Tag:. Il problema può 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, mentre il runtime v3.x viene eseguito in Debian Buster. L'artefatto dovrebbe contenere i file binari di Linux corretti. L’uso del flag --build local in Core Tools oppure in strumenti obsoleti o di terze parti può causare l'utilizzo di file binari meno recenti.

Per attenuare il problema, vedere Abilitare la compilazione remota o Creare 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 di metadati e controllare la sezione Classificatori. Se la sezione non contiene Python :: 3, Python :: 3.6, Python :: 3.7Python :: 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. Andare alla pagina della risorsa Panoramica dell'app per le funzioni per trovare la versione del runtime. La versione del runtime supporta le versioni di Python come descritto nella panoramica delle versioni del runtime di Funzioni di Azure.

Per attenuare 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 i gruppi wheel Linux corretti, potrebbe verificarsi un conflitto con altri pacchetti. In alcuni pacchetti, la documentazione PyPi può essere utile per chiarire i moduli 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 attenuare 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 su piattaforme Windows e macOS. Ad esempio, pyWin32 viene eseguito solo in Windows.

È possibile che l'errore Module Not Found non si verifichi 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 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 attenuare il problema, vedere Sostituire il pacchetto con altri equivalenti o File requirements.txt manuale.

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 soluzione provare.

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, quindi ridistribuire il progetto.

Creare dipendenze native

Verificare che sia installata la versione più recente di Docker e Azure Functions 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. Il linguaggio di programmazione deve inoltre contenere Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 o Python :: 3.9.

Se questi elementi di 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 importare da ogni file con estensione py nel codice sorgente del progetto e archiviare solo tali moduli nel file requirements.txt. In questo modo si garantisce che la risoluzione dei pacchetti possa essere gestita correttamente in sistemi operativi diversi.

Sostituire il pacchetto con altri equivalenti

Innanzitutto, è opportuno esaminare la versione più recente del pacchetto in https://pypi.org/project/<package-name>. Questo pacchetto ha in genere una propria pagina GitHub. Andare alla sezione Problemi in GitHub ed eseguire una ricerca per verificare se il problema è stato risolto. In caso affermativo, 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 determinata distribuzione Python (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 nota 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

Per l'impostazione dell'applicazione PYTHON_ISOLATE_WORKER_DEPENDENCIES, specificare un valore 0.

Risoluzione del problema: impossibile importare "cygrpc"

Questa sezione consente di risolvere gli errori relativi 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"

Le cause potenziali degli errori che fanno riferimento a cygrpc sono diverse e vengono 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 il sistema operativo in esecuzione è x64, verificare 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 numero di bit dell'interprete Python con questi comandi:

In Windows 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 il numero di bit dell'interprete Python e l'architettura del sistema operativo non corrispondono, 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 da 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 una versione dell'interprete Python supportata da Funzioni di Azure da 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. Nella piattaforma Funzioni di Azure è presente 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 cause radice comuni.

Regressione da pacchetti di terze parti

Nel file 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 di importazione, disabilitare i riferimenti al pacchetto o aggiungere il pacchetto a una versione precedente in requirements.txt.

Deserializzare un file con estensione pkl non valido

Se l'app per le funzioni usa la libreria pickle di 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 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 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.

Suggerimento

Prendere in considerazione l'uso di mssql-python, il driver Python ufficiale di Microsoft per SQL Server, che fornisce il supporto predefinito per l'autenticazione di Microsoft Entra e non richiede la gestione manuale dei driver ODBC.

Trigger di sincronizzazione non riusciti

L'errore Sync triggers failed può essere causato da diversi problemi. Una causa potenziale è 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, consultare Gestione pacchetti.

Risoluzione del problema: impossibile caricare il file o l'assembly

Questo errore può essere visualizzato se si opera locale con 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 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 di 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 questo 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 ad Archiviazione di Azure denominata "Archiviazione".
Valore non può essere nullo. Parametro "provider"

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

  • 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. Usare questa opzione quando si usa 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

Possono verificarsi diversi problemi di compilazione comuni che possono causare la mancata individuazione di funzioni Python da parte dell'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. Verificare 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 il percorso 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 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:

  • 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, può essere indicato di usare uno strumento diverso per lo sviluppo. Esistono diversi scenari in cui non è possibile modificare il codice nel portale, ad esempio 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

  • Last updated on