Condividi tramite

Guida di riferimento per gli sviluppatori di Funzioni di Azure per le app Python

Funzioni di Azure è un servizio di calcolo serverless che consente di eseguire codice basato su eventi senza effettuare il provisioning o la gestione dell'infrastruttura. Le esecuzioni di funzioni vengono attivate da eventi come richieste HTTP, messaggi di coda, timer o modifiche nell'archiviazione e scalabilità automatica in base alla richiesta.

Questa guida è incentrata in particolare sulla compilazione di Funzioni di Azure basate su Python e consente di:

  • Creare ed eseguire app per le funzioni in locale
  • Informazioni sul modello di programmazione Python
  • Organizzare e configurare l'applicazione
  • Distribuire e monitorare l'app in Azure
  • Applicare le procedure consigliate per il ridimensionamento e le prestazioni

Stai cercando una panoramica concettuale? Vedere Le informazioni di riferimento per gli sviluppatori di Funzioni di Azure.

Sei interessato a casi d'uso reali? Esplorare la pagina Scenari e esempi .

Come iniziare

Scegliere l'ambiente adatto al flusso di lavoro e passare a Funzioni di Azure per Python:

Creazione dell'app di funzione

Questa sezione illustra i componenti essenziali per la creazione e la strutturazione dell'app per le funzioni Python. Gli argomenti includono il modello di programmazione, la struttura del progetto, i trigger e le associazioni e la gestione delle dipendenze.

Modello di programmazione

Funzioni supporta due versioni del modello di programmazione Python:

Versione Descrizione
2.x Usare un approccio basato su decorator per definire trigger e associazioni direttamente nel file di codice Python. Ogni funzione viene implementata come metodo globale senza stato in un file function_app.py o un file di progetto a cui si fa riferimento. Questa versione del modello è consigliata per le nuove app Python.
1.x Si definiscono trigger e associazioni per ogni funzione in un file separato function.json . Ogni funzione viene implementata come metodo globale senza stato nel file di codice Python. Questa versione del modello supporta le app legacy.

Questo articolo è destinato a una versione specifica del modello Python. Scegliere la versione desiderata nella parte superiore dell'articolo.

Importante

Usare il modello di programmazione v2 per un approccio basato su decorator per definire trigger e associazioni direttamente nel codice.

Nel modello di programmazione Python v1 ogni funzione viene definita come metodo globale senza stato main() all'interno di un file denominato __init__.py. I trigger e le associazioni della funzione vengono configurati separatamente in un function.json file e i valori di associazione name vengono usati come parametri nel main() metodo.

Esempio

Ecco una funzione semplice che risponde a una richiesta HTTP:

# __init__.py
def main(req):
    user = req.params.get('user')
    return f'Hello, {user}!'

Ecco il file corrispondente function.json :

{
    "scriptFile": "__init__.py",
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

Concetti chiave

  • La funzione ha un singolo trigger HTTP.
  • L'oggetto HttpRequest contiene intestazioni di richiesta, parametri di query, parametri di route e corpo del messaggio. Questa funzione ottiene il valore del name parametro di query dal params parametro dell'oggetto HttpRequest .
  • Per inviare un nome in questo esempio, aggiungere ?name={name} all'URL della funzione esposta. Ad esempio, se eseguito localmente, l'URL completo potrebbe essere simile a http://localhost:7071/api/http_trigger?name=Test. Per esempi sull'uso di associazioni, vedere Trigger e associazioni.

Usare l'SDK azure-functions e includere le annotazioni dei tipi per migliorare il supporto per IntelliSense e l'editor.

# __init__.py
import azure.functions as func

def http_trigger(req: func.HttpRequest) -> str:

# requirements.txt
azure-functions

Libreria azure-functions

La azure-functions libreria Python fornisce i tipi di base usati per interagire con il runtime di Funzioni di Azure. Per visualizzare tutti i tipi e i metodi disponibili, visitare l'APIazure-functions. Il codice della funzione può usare azure-functions per:

  • Dati di input del trigger di accesso (ad esempio, HttpRequest, TimerRequest)
  • Creare valori di output ( ad esempio HttpResponse)
  • Interagire con il contesto fornito dal runtime e i dati di associazione

Se si usa azure-functions nell'app, deve essere inclusa nelle dipendenze del progetto.

Annotazioni

La azure-functions libreria definisce la superficie di programmazione per Funzioni di Azure python, ma non è un SDK per utilizzo generico. Usarlo in modo specifico per la creazione e l'esecuzione di funzioni all'interno del runtime di Funzioni di Azure.

Punto di ingresso alternativo

È possibile modificare il comportamento predefinito di una funzione specificando le scriptFile proprietà e entryPoint nel function.json file. Ad esempio, il file seguente function.json indica al runtime di usare il custom_entry() metodo nel main.py file come punto di ingresso per la funzione di Azure.

{
  "scriptFile": "main.py",
  "entryPoint": "custom_entry",
  "bindings": [
      ...
  ]
}

Struttura di cartelle

Usare la seguente struttura per un progetto di Azure Functions in Python:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── my_first_function/       # Function directory
│   └── __init__.py          # Function code file
│   └── function.json        # Function binding configuration file
│
├── my_second_function/
│   └── __init__.py  
│   └── function.json 
│
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

File e cartelle chiave

File/Cartella Descrizione Obbligatorio per l'esecuzione dell'app in Azure
my_first_function/ Directory per una singola funzione. ✅
__init__.py/ Script principale in cui è definito il codice della my_first_function funzione. ✅
function.json/ Contiene la configurazione di associazione per la funzione my_first_function. ✅
host.json Configurazione globale per tutte le funzioni nell'app. ✅
requirements.txt Dipendenze Python installate durante la pubblicazione quando si usa la compilazione remota. ❌ (consigliato per la gestione dei pacchetti)
local.settings.json Impostazioni e segreti dell'app locale (mai pubblicati). ❌ (obbligatorio per lo sviluppo locale)
.funcignore Specifica i file e le cartelle da escludere dalla distribuzione, .venv/ad esempio , tests/, local.settings.json. ❌ (scelta consigliata)
.venv/ Ambiente virtuale locale per Python (escluso dalla distribuzione). ❌
.vscode/ Configurazione dell'editor per Visual Studio Code. Non obbligatorio per la distribuzione. ❌
shared/ Contiene il codice helper condiviso nel progetto della Function App ❌
additional_functions/ Usato per l'organizzazione di codice modulare, in genere con planimetrie. ❌
tests/ Unit test per un'app per le funzioni. Non pubblicato in Azure. ❌
Dockerfile Definisce un contenitore personalizzato per la distribuzione. ❌

Nel modello di programmazione Python v2, Funzioni di Azure usa un approccio basato su decorator per definire trigger e associazioni direttamente nel codice. Ogni funzione viene implementata come metodo globale senza stato all'interno di un function_app.py file.

Esempio

Ecco una funzione semplice che risponde a una richiesta HTTP:

import azure.functions as func

app = func.FunctionApp()

@app.route("hello")
def http_trigger(req):
    user = req.params.get("user")
    return f"Hello, {user}!"

# requirements.txt
azure-functions

Concetti chiave

  • Il codice importa il pacchetto azure-functions e utilizza elementi Decorator e tipi per definire l'app per le funzioni.
  • La funzione ha un singolo trigger HTTP.
  • L'oggetto HttpRequest contiene intestazioni di richiesta, parametri di query, parametri di route e corpo del messaggio. Questa funzione ottiene il valore del name parametro di query dal params parametro dell'oggetto HttpRequest .
  • Per inviare un nome in questo esempio, aggiungere ?name={name} all'URL della funzione esposta. Ad esempio, se in esecuzione in locale, l'URL completo potrebbe essere simile a http://localhost:7071/api/http_trigger?name=Test. Per esempi sull'uso di associazioni, vedere Trigger e associazioni.

Libreria azure-functions

La azure-functions libreria Python è una parte fondamentale del modello di programmazione di Funzioni di Azure. Fornisce gli elementi Decorator, i tipi di trigger e di associazione e gli oggetti di richiesta/risposta usati per definire e interagire con le funzioni in fase di esecuzione. Per visualizzare tutti i tipi e i decoratori disponibili, visitare l'APIazure-functions. Il codice dell'app di funzioni dipende da questa libreria per:

  • Definire tutte le funzioni usando l'oggetto FunctionApp
  • Dichiarare trigger e associazioni (ad esempio, @app.route, @app.timer_trigger)
  • Accedi a input e output tipizzati (come HttpRequest e HttpResponse, e Out')

Deve azure-functions essere incluso nelle dipendenze del progetto. Per altre informazioni, vedere Gestione dei pacchetti.

Annotazioni

La azure-functions libreria definisce la superficie di programmazione per Funzioni di Azure python, ma non è un SDK per utilizzo generico. Usarlo in modo specifico per la creazione e l'esecuzione di funzioni all'interno del runtime di Funzioni di Azure.

Usare le annotazioni dei tipi per migliorare il supporto di IntelliSense e dell'editor:

def http_trigger(req: func.HttpRequest) -> str:

Organizzazione con i progetti tecnici

Per le app più grandi o modulari, usare i progetti per definire funzioni in file Python separati e registrarli con l'app principale. Questa separazione mantiene il codice organizzato e riutilizzabile.

Per definire e registrare un progetto:

  1. Definire un progetto in un altro file Python, ad esempio http_blueprint.py:

    import azure.functions as func

bp = func.Blueprint()

@bp.route(route="default_template")
def default_template(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello World!")

  2. Registrare il progetto nel file principale function_app.py :

    import azure.functions as func
from http_blueprint import bp

app = func.FunctionApp()
app.register_functions(bp)

Usando i progetti, è possibile:

  • Suddividere l'app in moduli riutilizzabili
  • Mantenere le funzioni correlate raggruppate per file o funzionalità
  • Estendere o condividere schemi tra progetti

Annotazioni

Durable Functions supporta anche i progetti usando azure-functions-durable. Visualizza esempio →

Struttura di cartelle

Usa la struttura seguente per un progetto di Funzioni di Azure in Python.

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── function_app.py          # Main function entry point (decorator model)
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

File e cartelle chiave

File/Cartella Descrizione Obbligatorio per l'esecuzione dell'app in Azure
function_app.py Script principale in cui le Funzioni e i trigger di Azure vengono definiti usando decoratori. ✅
host.json Configurazione globale per tutte le funzioni nell'app. ✅
requirements.txt Dipendenze Python installate durante la pubblicazione quando si usa la compilazione remota. ❌ (consigliato per la gestione dei pacchetti)
local.settings.json Impostazioni e segreti dell'app per uso locale (mai pubblicati). ❌ (obbligatorio per lo sviluppo locale)
.funcignore Specifica i file e le cartelle da escludere dalla distribuzione, .venv/ad esempio , tests/, local.settings.json. ❌ (scelta consigliata)
.venv/ Ambiente virtuale locale per Python (escluso dalla distribuzione). ❌
.vscode/ Configurazione dell'editor per Visual Studio Code. Non obbligatorio per la distribuzione. ❌
shared/ Contiene il codice helper condiviso nel progetto Funzione App ❌
additional_functions/ Usato per l'organizzazione modulare del codice, tipicamente con blueprint. ❌
tests/ Unit test per un'app per le funzioni. Non pubblicato in Azure. ❌
Dockerfile Definisce un contenitore personalizzato per la distribuzione. ❌

[NOTA!] Includere un requirements.txt file quando si esegue la distribuzione con compilazione remota. Se non si usa la compilazione remota o si vuole usare un altro file per definire le dipendenze dell'app, è possibile eseguire una compilazione locale e distribuire l'app con dipendenze predefinite.

Per indicazioni sugli unit test, vedere Unit Testing. Per le distribuzioni di contenitori, vedere Distribuire con contenitori personalizzati.

Trigger e associazioni

Funzioni di Azure usa trigger per avviare l'esecuzione delle funzioni e associazioni per connettere il codice ad altri servizi, ad esempio archiviazione, code e database. Nel modello di programmazione Python v2 si dichiarano associazioni usando decorator.

Esistono due tipi principali di associazioni:

  • Trigger (input che avvia la funzione)
  • Input e output (origini dati o destinazioni aggiuntive)

Per altre informazioni sui trigger e le associazioni disponibili, vedere Trigger e associazioni in Funzioni di Azure.

Esempio: trigger timer con input BLOB

Questa funzione:

  • Attiva ogni 10 minuti
  • Legge da un BLOB usando associazioni di tipi SDK
  • Memorizza nella cache i risultati e le scritture in un file temporaneo
import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
import logging
import tempfile

CACHED_BLOB_DATA = None

app = func.FunctionApp()

@app.function_name(name="TimerTriggerWithBlob")
@app.schedule(schedule="0 */10 * * * *", arg_name="mytimer")
@app.blob_input(arg_name="client",
                path="PATH/TO/BLOB",
                connection="BLOB_CONNECTION_SETTING")
def timer_trigger_with_blob(mytimer: func.TimerRequest,
                            client: blob.BlobClient,
                            context: func.Context) -> None:
    global CACHED_BLOB_DATA
    if CACHED_BLOB_DATA is None:
        # Download blob and save as a global variable
        CACHED_BLOB_DATA = client.download_blob().readall()

        # Create temp file prefix
        my_prefix = context.invocation_id
        temp_file = tempfile.NamedTemporaryFile(prefix=my_prefix)
        temp_file.write(CACHED_BLOB_DATA)
        logging.info(f"Cached data written to {temp_file.name}")

Concetti chiave

  • Usare le associazioni dei tipi di SDK per lavorare con tipi avanzati. Per altre informazioni, vedere Associazioni dei tipi di SDK.
  • È possibile usare variabili globali per memorizzare nella cache calcoli costosi, ma il relativo stato non è garantito per la persistenza tra le esecuzioni delle funzioni.
  • I file temporanei vengono archiviati in tmp/ e non è garantito che persistano tra invocazioni o durante le operazioni di scale-out.
  • È possibile accedere al contesto di chiamata di una funzione tramite la classe Context.

Esempio: Trigger HTTP con input di Cosmos DB e output di Event Hub

Questa funzione:

  • Si attiva su una richiesta HTTP
  • Legge da Cosmos DB
  • Scrive in un output di hub eventi
  • Restituisce una risposta HTTP
# __init__.py
import azure.functions as func

def main(req: func.HttpRequest,
         documents: func.DocumentList,
         event: func.Out[str]) -> func.HttpResponse:

    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get("body")
    doc_id = documents[0]["id"] if documents else "No documents found"

    event.set(f"HttpRequest content: {http_content} | CosmosDB ID: {doc_id}")

    return func.HttpResponse(
        "Function executed successfully.",
        status_code=200
    )

// function.json
{
  "scriptFile": "__init__.py",
  "entryPoint": "main",
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"],
      "route": "file"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "cosmosDB",
      "direction": "in",
      "name": "documents",
      "databaseName": "test",
      "containerName": "items",
      "id": "cosmosdb-input-test",
      "connection": "COSMOSDB_CONNECTION_SETTING"
    },
    {
      "type": "eventHub",
      "direction": "out",
      "name": "event",
      "eventHubName": "my-test-eventhub",
      "connection": "EVENTHUB_CONNECTION_SETTING"
    }
  ]
}

Concetti chiave

  • Ogni funzione ha un singolo trigger, ma può avere più associazioni.
  • Aggiunge input specificando direction come "in" in function.json. Gli output hanno un valore direction pari a out.
  • È possibile accedere ai dettagli delle richieste tramite l'oggetto HttpRequest e costruire un oggetto personalizzato HttpResponse con intestazioni, codice di stato e corpo.
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="HttpTriggerWithCosmosDB")
@app.route(route="file")
@app.cosmos_db_input(arg_name="documents",
                     database_name="test",
                     container_name="items",
                     connection="COSMOSDB_CONNECTION_SETTING")
@app.event_hub_output(arg_name="event",
                      event_hub_name="my-test-eventhub",
                      connection="EVENTHUB_CONNECTION_SETTING")
def http_trigger_with_cosmosdb(req: func.HttpRequest,
                               documents: func.DocumentList,
                               event: func.Out[str]) -> func.HttpResponse:
    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get('body')
    doc_id = documents[0]['id']

    event.set("HttpRequest content: " + http_content
              + " | CosmosDB ID: " + doc_id)

    return func.HttpResponse(
        f"Function executed successfully.",
        status_code=200
    )

Concetti chiave

  • Utilizza @route() o decoratori specifici del trigger (@timer_trigger, @queue_trigger e altri) per definire il modo in cui viene richiamata la tua funzione.
  • Aggiungere input usando decoratori come @blob_input, @queue_input e altri.
  • Gli output possono essere:
    • Restituito direttamente (se è presente un solo output)
    • Assegnato usando le associazioni Out e il metodo .set() per output multipli.
  • È possibile accedere ai dettagli delle richieste tramite l'oggetto HttpRequest e costruire un oggetto personalizzato HttpResponse con intestazioni, codice di stato e corpo.

Associazioni dei tipi di SDK

Per selezionare trigger e associazioni, è possibile usare i tipi di dati implementati dagli SDK e dai framework di Azure sottostanti. Usando questi binding di tipi SDK, puoi interagire con i dati di binding come se stessi utilizzando l'SDK del servizio sottostante. Per altre informazioni, vedere Associazioni di tipi di SDK supportate.

Importante

Il supporto delle associazioni dei tipi di SDK per Python è disponibile solo nel modello di programmazione Python v2.

Variabili di ambiente

Le variabili di ambiente in Funzioni di Azure consentono di gestire in modo sicuro i valori di configurazione, le stringhe di connessione e i segreti delle app senza codificarli nel codice della funzione.

È possibile definire le variabili di ambiente:

Accedere alle variabili direttamente nel codice usando os.environ o os.getenv.

setting_value = os.getenv("myAppSetting", "default_value")

Annotazioni

Funzioni di Azure riconosce anche le variabili di ambiente di sistema che configurano il runtime di Funzioni e il comportamento del ruolo di lavoro Python. Queste variabili non vengono usate in modo esplicito nel codice della funzione, ma influiscono sulla modalità di esecuzione dell'app. Per un elenco completo delle variabili di ambiente di sistema, vedere Informazioni di riferimento sulle impostazioni dell'app.

Gestione dei pacchetti

Per usare altri pacchetti Python nell'app Funzioni di Azure, elencarli in un requirements.txt file nella radice del progetto. Questi pacchetti vengono importati dal sistema di importazione di Python ed è quindi possibile fare riferimento a tali pacchetti come di consueto. Per altre informazioni sulla compilazione e sulle opzioni di distribuzione con dipendenze esterne, vedere Opzioni di compilazione per le app per le funzioni Python.

Ad esempio, l'esempio seguente mostra come il requests modulo viene incluso e usato nell'app per le funzioni.

<requirements.txt>
requests==2.31.0

Installare il pacchetto in locale con pip install -r requirements.txt.

Dopo aver installato il pacchetto, è possibile importarlo e usarlo nel codice della funzione:

import azure.functions as func
import requests

def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

import azure.functions as func
import requests

app = func.FunctionApp()

@app.function_name(name="HttpExample")
@app.route(route="call_api")
def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

Considerazioni

  • Conflitti con i moduli predefiniti:
    • Evitare di denominare le cartelle del progetto dopo le librerie standard python ( ad esempio email/, ). json/
    • Non includere librerie native Python (ad esempio logging, asyncioo uuid) in requirements.txt.
  • Distribuzione:
    • Per evitare ModuleNotFound errori, assicurarsi che tutte le dipendenze necessarie siano elencate in requirements.txt.
    • Se si aggiorna la versione python dell'app, ricompilare e ridistribuire l'app nella nuova versione di Python per evitare conflitti di dipendenza con i pacchetti compilati in precedenza.
  • Dipendenze extra-PyPI
    • È possibile includere dipendenze non disponibili in PyPI nell'app, ad esempio pacchetti locali, file con rotellina o feed privati. Per istruzioni sull'installazione, vedere Dipendenze personalizzate in Funzioni di Azure python.
  • Dipendenze del ruolo di lavoro Python per Funzioni di Azure:

Esecuzione e distribuzione

Questa sezione fornisce informazioni sull'esecuzione di funzioni in locale, sul supporto della versione python, sulle opzioni di compilazione e distribuzione e sulla configurazione di runtime. Usare queste informazioni per eseguire correttamente l'app per le funzioni in ambienti locali e di Azure.

Esecuzione in locale

È possibile eseguire e testare l'app per le funzioni Python nel computer locale prima di eseguire la distribuzione in Azure.

Uso di Azure Functions Core Tools

Installare Azure Functions Core Tools e avviare il runtime locale eseguendo il comando dalla radice del func start progetto:

func start

Quando si avvia l'applicazione delle funzioni in locale, Core Tools visualizza tutte le funzioni trovate per l'applicazione:

Functions:
        http_trigger:  http://localhost:7071/api/http_trigger

Per altre informazioni su come usare Core Tools, vedere Sviluppare Funzioni di Azure in locale con Core Tools.

Richiamo diretto della funzione

Usando azure-functions >= 1.21.0, è anche possibile chiamare le funzioni direttamente utilizzando l'interprete Python senza eseguire Core Tools. Questo approccio è utile per gli unit test rapidi:

# function_app.py
import azure.functions as func

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="http_trigger")
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    return "Hello, World!"

# Test the function directly
print(http_trigger(None))

Per visualizzare l'output, eseguire il file direttamente con Python:

> python function_app.py

Hello, World!

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello, World!")

# Test the function directly
print(main(None))

Per visualizzare l'output, eseguire il file direttamente con Python:

> python __init__.py

Hello, World!

Questo approccio non richiede pacchetti o configurazioni aggiuntivi ed è ideale per la convalida rapida durante lo sviluppo. Per altri test approfonditi, vedere Unit Testing

Versioni di Python supportate

Funzioni di Azure supporta le versioni di Python elencate in Linguaggi supportati in Funzioni di Azure. Per ulteriori informazioni generali, consultare i criteri di supporto del runtime di Azure Functions.

Importante

Se si modifica la versione di Python per l'app per le funzioni, è necessario ricompilare e ridistribuire l'app usando la nuova versione. Gli artefatti e le dipendenze di distribuzione esistenti non vengono ricompilati automaticamente quando cambia la versione di Python.

Compilazione e implementazione

Per altre informazioni sul meccanismo di compilazione consigliato per lo scenario, vedere Opzioni di compilazione. Per una panoramica generale della distribuzione, vedere Tecnologie di distribuzione in Funzioni di Azure.

Confronto rapido tra meccanismi di distribuzione

Strumento/piattaforma Comando/azione Caso d'uso migliore
Strumenti di base di Funzioni di Azure func azure functionapp publish <APP_NAME> Ideale per le esecuzioni CI, l'automazione locale o quando si lavora su più piattaforme.
Interfaccia della riga di comando AZ az functionapp deployment source config-zip Utile quando si esegue lo script delle distribuzioni all'esterno di Core Tools. Funziona bene nelle pipeline automatizzate o nei terminali basati sul cloud (Azure Cloud Shell).
Visual Studio Code (estensione Funzioni di Azure) Riquadro comandi → "Funzioni di Azure: Distribuire in Azure..." Ideale per principianti o distribuzioni interattive. Gestisce automaticamente i pacchetti e la compilazione.
GitHub Actions Azure/functions-action@v1 Ideale per CI/CD basato su GitHub. Abilita le distribuzioni automatizzate nei merge di richiesta push o pull.
Azure Pipelines AzureFunctionApp@2 Attività CI/CD aziendale con Azure DevOps. Ideale per flussi di lavoro di rilascio controllati, compilazioni controllate e pipeline a più fasi.
Distribuzione di contenitori personalizzati Push del contenitore → az functionapp create --image <container> Obbligatorio quando sono necessari pacchetti a livello di sistema operativo, compilazioni Python personalizzate, runtime aggiunti o dipendenze non supportate, ad esempio librerie di sistema, file binari locali.
Creazione di funzioni basate sul portale Creare una funzione nel portale di Azure → nell'editor in linea Usare solo per funzioni semplici senza dipendenze. Ideale per demo o apprendimento, ma non consigliato per le app che richiedono pacchetti di terze parti.

Annotazioni

La creazione di funzioni basate sul portale non supporta le dipendenze di terze parti e non è consigliata per la creazione di app di produzione. Non è possibile installare o fare riferimento a pacchetti all'esterno azure-functions e alla libreria standard Python predefinita.

Importante

Dopo il 30 settembre 2028, l'opzione di ospitare l'applicazione di funzioni su Linux in un piano a consumo sarà ritirata. Per evitare interruzioni, eseguire la migrazione delle app del piano a consumo esistenti eseguite in Linux al piano a consumo Flex prima di tale data. Le app in esecuzione in Windows in un piano a consumo non sono interessate da questa modifica. Per ulteriori informazioni, vedere l'avviso di eliminazione del piano di consumo di Linux.

Aggiornamenti di Python 3.13+

A partire da Python 3.13, Funzioni di Azure introduce diversi importanti miglioramenti di runtime e prestazioni che influiscono sulla compilazione ed esecuzione delle app. Le modifiche chiave includono:

  • Controllo della versione di runtime: è ora possibile opzionalmente fissare o aggiornare l'app a versioni specifiche del worker Python facendo riferimento al pacchetto azure-functions-runtime in requirements.txt.

    • Senza il controllo della versione abilitato, l'app viene eseguita in una versione predefinita del runtime Python, gestita da Funzioni. È necessario modificare il file requirements.txt per richiedere la versione rilasciata più recente, una versione non definitiva o aggiungere l'app a una versione specifica del runtime Python.

    • È possibile abilitare il controllo della versione di runtime aggiungendo un riferimento al pacchetto di runtime Python al file requirements.txt , in cui il valore assegnato al pacchetto determina la versione di runtime usata.

    • Evitare di bloccare qualsiasi app di produzione sulle versioni di runtime non definitive (alpha, beta o dev).

    • Per essere consapevoli delle modifiche, vedere regolarmente le note sulla versione del runtime di Python .

    • La tabella seguente indica il comportamento di controllo delle versioni in base al valore della versione di questa impostazione nel file requirements.txt :

      Versione Example Comportamento
      Nessun valore impostato azure-functions-runtime L'app Python 3.13+ viene eseguita nella versione più recente disponibile del runtime di Funzioni Python. Questa opzione è ideale per rimanere aggiornati con i miglioramenti e le funzionalità della piattaforma, poiché l'app riceve automaticamente gli aggiornamenti di runtime stabili più recenti.
      Aggiunta a una versione specifica azure-functions-runtime==1.2.0 L'app Python 3.13+ rimane sulla versione di runtime fissata e non riceve aggiornamenti automatici. È invece necessario aggiornare manualmente la versione bloccata per sfruttare le nuove funzionalità, le correzioni e i miglioramenti nell'ambiente di runtime. Il fissaggio è consigliato per carichi di lavoro di produzione critici in cui la stabilità e la prevedibilità sono essenziali. Il blocco consente anche di testare l'app su versioni di runtime non definitive in fase di sviluppo.
      Nessun riferimento al pacchetto non disponibile Non impostando il azure-functions-runtime, l'app Python 3.13+ viene eseguita su una versione predefinita del runtime di Python che è precedente rispetto all'ultima versione rilasciata. Gli aggiornamenti vengono eseguiti periodicamente da Funzioni. Questa opzione garantisce la stabilità e la compatibilità generale. Tuttavia, l'accesso alle funzionalità e alle correzioni più recenti viene ritardato fino a quando non viene aggiornata la versione predefinita.

  • Isolamento delle dipendenze: le dipendenze dell'app (ad esempio grpcio o protobuf) sono completamente isolate dalle dipendenze del ruolo di lavoro, evitando conflitti di versione. L'impostazione PYTHON_ISOLATE_WORKER_DEPENDENCIES dell'app non avrà alcun impatto sulle app in esecuzione in Python 3.13 o versione successiva.

  • Configurazione semplificata del flusso HTTP : non sono necessarie impostazioni speciali per le app.

  • Rimozione del supporto per le estensioni worker e le funzionalità di memoria condivisa.

  • Controllo della versione di runtime: è ora possibile opzionalmente fissare o aggiornare l'app a versioni specifiche del worker Python facendo riferimento al pacchetto azure-functions-runtime-v1 in requirements.txt.

    • Senza il controllo della versione abilitato, l'app viene eseguita in una versione predefinita del runtime Python, gestita da Funzioni. È necessario modificare il file requirements.txt per richiedere la versione rilasciata più recente, una versione non definitiva o aggiungere l'app a una versione specifica del runtime Python.

    • È possibile abilitare il controllo della versione di runtime aggiungendo un riferimento al pacchetto di runtime Python al file requirements.txt , in cui il valore assegnato al pacchetto determina la versione di runtime usata.

    • Evitare di bloccare qualsiasi app di produzione sulle versioni di runtime non definitive (alpha, beta o dev).

    • Per essere consapevoli delle modifiche, vedere regolarmente le note sulla versione del runtime di Python .

    • La tabella seguente indica il comportamento di controllo delle versioni in base al valore della versione di questa impostazione nel file requirements.txt :

      Versione Example Comportamento
      Nessun valore impostato azure-functions-runtime-v1 L'app Python 3.13+ viene eseguita nella versione più recente disponibile del runtime di Funzioni Python. Questa opzione è ideale per rimanere aggiornati con i miglioramenti e le funzionalità della piattaforma, poiché l'app riceve automaticamente gli aggiornamenti di runtime stabili più recenti.
      Aggiunta a una versione specifica azure-functions-runtime-v1==1.2.0 L'app Python 3.13+ rimane sulla versione di runtime bloccata e non riceve aggiornamenti automatici. È invece necessario aggiornare manualmente la versione bloccata per sfruttare le nuove funzionalità, le correzioni e i miglioramenti nell'ambiente di runtime. Si consiglia il fissaggio per carichi di lavoro produttivi critici, in cui stabilità e prevedibilità sono essenziali. Il blocco consente anche di testare l'app su versioni di runtime non definitive in fase di sviluppo.
      Nessun riferimento al pacchetto non disponibile Non impostando il azure-functions-runtime-v1, l'app Python 3.13+ viene eseguita su una versione predefinita del runtime Python, che è precedente rispetto all'ultima versione rilasciata. Gli aggiornamenti vengono eseguiti periodicamente da Funzioni. Questa opzione garantisce la stabilità e la compatibilità generale. Tuttavia, l'accesso alle funzionalità e alle correzioni più recenti viene ritardato fino a quando non viene aggiornata la versione predefinita.

  • Isolamento delle dipendenze: le dipendenze dell'app (ad esempio grpcio o protobuf) sono completamente isolate dalle dipendenze del lavoratore, impedendo conflitti di versione. L'impostazione PYTHON_ISOLATE_WORKER_DEPENDENCIES dell'app non avrà alcun impatto sulle app in esecuzione in Python 3.13 o versione successiva.

  • Rimozione del supporto per le estensioni degli operatori e le funzionalità di memoria condivisa.

Osservabilità e test

Questa sezione illustra le funzionalità di registrazione, monitoraggio e test per facilitare il debug dei problemi, tenere traccia delle prestazioni e garantire l'affidabilità delle app per le funzioni Python.

Registrazione e monitoraggio

Funzioni di Azure espone un logger radice che è possibile usare direttamente con il modulo predefinito logging di Python. Tutti i messaggi scritti con questo logger vengono inviati automaticamente ad Application Insights quando l'app è in esecuzione in Azure.

La registrazione consente di acquisire informazioni di runtime e diagnosticare i problemi senza dover eseguire altre operazioni di installazione.

Esempio di registrazione con un trigger HTTP

import logging
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

È possibile usare il set completo di livelli di registrazione (debug, info, warningerror, , critical) e vengono visualizzati nel portale di Azure in Log o Application Insights.

Per altre informazioni sul monitoraggio di Funzioni di Azure nel portale, vedere Monitorare Funzioni di Azure.

Annotazioni

Per visualizzare i log di debug in Application Insights, è necessaria un'ulteriore configurazione. È possibile abilitare questa funzionalità impostando PYTHON_ENABLE_DEBUG_LOGGING su 1 e impostando logLevel su trace o debug nel file host.json. Per impostazione predefinita, i log di debug non sono visibili in Application Insights.

Registrazione dei thread in background

Se la funzione avvia un nuovo thread e deve eseguire la registrazione da tale thread, assicurarsi di passare l'argomento context nel thread. L'elemento context contiene l'archiviazione locale al thread e l'oggetto corrente invocation_id, che deve essere impostato sul thread di lavoro affinché i log siano associati correttamente all'esecuzione della funzione.

import logging
import threading
import azure.functions as func

def main(req: func.HttpRequest, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

import azure.functions as func
import logging
import threading

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

Configurazione di logger personalizzati

È possibile configurare logger personalizzati in Python quando è necessario un maggiore controllo sul comportamento di registrazione, ad esempio formattazione personalizzata, filtro dei log o integrazioni di terze parti. Per configurare un logger personalizzato, usare Python logging.getLogger() con un nome personalizzato e aggiungere gestori o formattatori in base alle esigenze.

import logging

custom_logger = logging.getLogger('my_custom_logger')

Supporto di OpenTelemetry

Funzioni di Azure per Python supporta anche OpenTelemetry, che consente di generare tracce, metriche e log in un formato standardizzato. L'uso di OpenTelemetry è particolarmente utile per applicazioni distribuite o scenari in cui si vogliono esportare i dati di telemetria in strumenti esterni ad Application Insights, ad esempio Grafana o Jaeger.

Per istruzioni sull'installazione e codice di esempio, vedere la guida introduttiva a OpenTelemetry per Funzioni di Azure (Python ).

Testing unità

Scrivere ed eseguire unit test per le funzioni usando pytest. È possibile testare funzioni Python come altro codice Python usando framework di test standard. Per la maggior parte delle associazioni, è possibile creare un oggetto di input fittizio creando un'istanza di una classe appropriata dal azure.functions pacchetto.

my_function Usando come esempio, l'esempio seguente è un test fittizio di una funzione attivata tramite HTTP:

Creare prima di tutto il <file project_root>/function_app.py e implementare la my_function funzione come trigger HTTP.

# <project_root>/function_app.py
import azure.functions as func
import logging

app = func.FunctionApp()

# Define the HTTP trigger that accepts the ?value=<int> query parameter
# Double the value and return the result in HttpResponse
@app.function_name(name="my_function")
@app.route(route="hello")
def my_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Executing myfunction.')

    initial_value: int = int(req.params.get('value'))
    doubled_value: int = initial_value * 2

    return func.HttpResponse(
        body=f"{initial_value} * 2 = {doubled_value}",
        status_code=200
    )

È possibile iniziare a scrivere test case per il trigger HTTP.

# <project_root>/test_my_function.py
import unittest
import azure.functions as func

from function_app import my_function

class TestFunction(unittest.TestCase):
  def test_my_function(self):
    # Construct a mock HTTP request.
    req = func.HttpRequest(method='GET',
                           body=None,
                           url='/api/my_function',
                           params={'value': '21'})
    # Call the function.
    func_call = main.build().get_user_function()
    resp = func_call(req)
    # Check the output.
    self.assertEqual(
        resp.get_body(),
        b'21 * 2 = 42',
    )

All'interno della cartella dell'ambiente virtuale Python è possibile eseguire i comandi seguenti per testare l'app:

pip install pytest
pytest test_my_function.py

Vedi i risultati pytest nel terminale, come questo:

============================================================================================================ test session starts ============================================================================================================
collected 1 item                                                                                                                                                                                                                             

test_my_function.py .                                                                                                                                                                                                                  [100%] 
============================================================================================================= 1 passed in 0.24s =============================================================================================================

Ottimizzazione e argomenti avanzati

Per altre informazioni sull'ottimizzazione delle app per le funzioni Python, vedere questi articoli:

Per altre informazioni sulle funzioni, vedere gli articoli seguenti:

Problemi con l'uso di Python? Facci sapere e segnala un problema.

  • Last updated on