Supporto di payload di grandi dimensioni con Durable Task Scheduler (anteprima)

Il supporto per payload di grandi dimensioni consente alla tua app di passare input di orchestrazione e output di attività che superano il limite di dimensione dei messaggi del Durable Task Scheduler. Quando un payload supera la soglia configurata, il framework archivia il payload serializzato in Archiviazione BLOB di Azure e invia un piccolo riferimento tramite Durable Task Scheduler.

Questa funzionalità è disponibile per:

Durable Functions con il worker isolato .NET
.NET Durable Task SDK
Python Durable Task SDK

Se il flusso di lavoro archivia i dati in gestione rete virtuale di Azure e passa solo un URI o un identificatore, continuare a usare tale modello. Usare il supporto del payload di grandi dimensioni quando la logica di orchestrazione deve passare il payload tra operazioni durevoli. Per indicazioni generali, vedere Sistenza e serializzazione dei dati in Durable Functions.

Framework supportati

Questa tabella mostra il supporto di framework per payload di grandi dimensioni.

Struttura	Stato del supporto	Elementi necessari
Durable Functions	Supportato in .NET C# isolato	Usare il pianificatore di attività durevole come provider di archiviazione e usare `AzureWebJobsStorage` per i BLOB di payload
SDK per attività durevoli	Supportato in .NET e Python	Usare l'estensione del payload di Azure Blob specifica per linguaggio con Archiviazione BLOB di Azure
JavaScript, PowerShell e Java	Non disponibile	Utilizzare l'archiviazione esterna e passare riferimenti tra operazioni persistenti

Come funziona

Quando si abilita il supporto di payload di grandi dimensioni, il runtime segue lo stesso flusso di alto livello in entrambi i modelli di hosting:

Serializza l'input di orchestrazione o l'output dell'attività.
Se le dimensioni del payload superano la soglia configurata, il runtime comprime il payload con gzip.
Scrive il payload compresso in Archiviazione BLOB di Azure.
Invia un riferimento BLOB tramite il pianificatore di attività durevole anziché il payload completo.
Il runtime risolve automaticamente il riferimento prima che il codice dell'agente di orchestrazione o di attività legga il valore.

Gli esempi attuali di .NET utilizzano carichi deterministici di 1,5 MiB a bassa comprimibilità. Ciò mantiene la dimensione del BLOB archiviato rappresentativa, anche se il runtime scrive BLOB con codifica del contenuto gzip.

Il supporto di payload di grandi dimensioni cambia il modo in cui i payload si spostano nel runtime. Non modifica la raccomandazione di mantenere lo stato durevole il più piccolo possibile.

Scegliere il modello corretto

Usare il modello più semplice per lo scenario.

Usare questo modello	Quando usarlo
Supporto di payload di grandi dimensioni	L'orchestrazione passa il payload tra le operazioni durevole e il payload supera il limite di messaggi del pianificatore.
Archiviazione esterna e riferimenti	Le attività caricano i dati direttamente dall'archiviazione e si vuole lo stato di orchestrazione più piccolo possibile

Abilitare il supporto di payload di grandi dimensioni

Il supporto di payload di grandi dimensioni in Durable Functions è disponibile solo per .NET app C# isolate che usano Durable Task Scheduler come provider di archiviazione.

Prima di abilitare la funzionalità, assicurarsi che l'app:

Utilizza il worker isolato .NET.
Riferimenti Microsoft.Azure.Functions.Worker.Extensions.DurableTask e Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged.
Imposta AzureWebJobsStorage sull'account di archiviazione che contiene payload esternalizzati.
Imposta DTS_CONNECTION_STRING e TASKHUB_NAME per il scheduler di destinazione e l'hub delle attività.

Abilitare quindi l'archiviazione payload di grandi dimensioni in host.json:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DTS_CONNECTION_STRING",
        "largePayloadStorageEnabled": true,
        "largePayloadStorageThresholdBytes": 900000
      },
      "hubName": "%TASKHUB_NAME%"
    }
  }
}

Impostare largePayloadStorageThresholdBytes sotto il limite delle dimensioni del messaggio del pianificatore di attività durevole in modo che il runtime esternalizzi i payload prima di raggiungere il limite.

Usare le API standard di Durable Functions nel codice di orchestrazione e dell'attività. Il runtime risolve automaticamente i riferimenti ai BLOB prima che context.GetInput<T>() e context.CallActivityAsync<T>() restituiscano i dati.

Per impostazione predefinita, l'estensione scrive payload esternalizzati sul contenitore durabletask-payloads nell'account di archiviazione configurato da AzureWebJobsStorage.

Per esempi completi, vedere questi campioni:

Il supporto di payload di grandi dimensioni negli SDK di Durable Task è disponibile per le app .NET e Python.

Installare il pacchetto di estensione del payload Azure Blob:

dotnet add package Microsoft.DurableTask.Extensions.AzureBlobPayloads

Installare i pacchetti di lavoro e client gestiti Azure per Durable Task Scheduler:

dotnet add package Microsoft.DurableTask.Client.AzureManaged
dotnet add package Microsoft.DurableTask.Worker.AzureManaged

Registrare un archivio di payload esternalizzato, scegliere una soglia e abilitare la risoluzione del payload sia nel client che nel worker:

builder.Services.AddExternalizedPayloadStore(options =>
{
    options.ExternalizeThresholdBytes = 900_000;
    options.ConnectionString = builder.Configuration["PAYLOAD_STORAGE_CONNECTION_STRING"]
        ?? "UseDevelopmentStorage=true";
    options.ContainerName = "durabletask-payloads";
});

builder.Services.AddDurableTaskClient(client =>
{
    client.UseDurableTaskScheduler(schedulerConnectionString);
    client.UseExternalizedPayloads();
});

builder.Services.AddDurableTaskWorker(worker =>
{
    worker.UseDurableTaskScheduler(schedulerConnectionString);
    worker.UseExternalizedPayloads();
});

Se si usa Microsoft Entra ID anziché una stringa di connessione di archiviazione, impostare options.AccountUri e options.Credential. L'esempio usa DefaultAzureCredential e può facoltativamente scegliere come destinazione un'identità gestita assegnata dall'utente.

Mantenere ExternalizeThresholdBytes su un valore uguale o inferiore a 1,048,576 byte. L'esempio utilizza 900,000 byte affinché i payload vengano sottoposti a offload prima di avvicinarsi al limite di 1 MiB del messaggio del pianificatore.

Per un esempio di .NET end-to-end, vedere l'esempio Durable Task SDK per payload di grandi dimensioni.

Installare il Python SDK con l'estensione Azure Blob payload e il pacchetto di trasporto gestito di Azure.

pip install durabletask[azure-blob-payloads] durabletask-azuremanaged

Crea un BlobPayloadStore, scegli una soglia e passa lo stesso archivio sia al worker che al client.

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions

store = BlobPayloadStore(BlobPayloadStoreOptions(
    connection_string=storage_connection_string,
    container_name="durabletask-payloads",
    threshold_bytes=900_000,
))

with DurableTaskSchedulerWorker(
    host_address=endpoint,
    secure_channel=secure_channel,
    taskhub=taskhub_name,
    token_credential=credential,
    payload_store=store,
) as worker:
    worker.start()

    client = DurableTaskSchedulerClient(
        host_address=endpoint,
        secure_channel=secure_channel,
        taskhub=taskhub_name,
        token_credential=credential,
        payload_store=store,
    )

Se usi Microsoft Entra ID anziché una stringa di connessione di archiviazione, imposta account_url e credential in BlobPayloadStoreOptions. L'esempio usa DefaultAzureCredential.

Mantenere threshold_bytes su un valore uguale o inferiore a 1,048,576 byte. L'esempio corrente usa 1,024 byte per poter visualizzare l'esternalizzazione del payload durante un'esecuzione locale.

Per un esempio di Python end-to-end, vedere l'esempio Durable Task SDK di payload di grandi dimensioni per Python.

Configurazione delle variabili di ambiente

Usare queste impostazioni locali o le impostazioni dell'app con gli esempi attuali di Durable Functions.

Impostazione	Descrizione	Impostazione predefinita di esempio
`FUNCTIONS_WORKER_RUNTIME`	Funzioni di Azure runtime di lavoro isolato	`dotnet-isolated`
`AzureWebJobsStorage`	Archiviazione per i BLOB dello stato host e del payload di Funzioni	`UseDevelopmentStorage=true` Localmente
`DTS_CONNECTION_STRING`	Stringa di connessione del pianificatore di attività durevoli	`Endpoint=http://localhost:8080;Authentication=None`
`TASKHUB_NAME`	Hub attività di destinazione	`default`
`PAYLOAD_SIZE_BYTES`	Dimensioni del payload usate dallo starter o generate da ogni attività	`1572864`
`ACTIVITY_COUNT`	Numero di attività parallele solo nell'esempio fan-out/fan-in	`3`

L'impostazione ACTIVITY_COUNT viene utilizzata solo dall'esempio LargePayloadFanOutFanIn . L'esempio di andata e ritorno LargePayload non lo legge.

Usare queste variabili di ambiente con gli esempi correnti di Durable Task SDK.

Variable	Descrizione	Impostazione predefinita di esempio
`DURABLE_TASK_SCHEDULER_CONNECTION_STRING`	Stringa di connessione del pianificatore di attività durevoli	`Endpoint=http://localhost:8080;TaskHub=default;Authentication=None`
`PAYLOAD_STORAGE_CONNECTION_STRING`	Connection string di archiviazione blob per payload esternalizzati	`UseDevelopmentStorage=true`
`PAYLOAD_STORAGE_ACCOUNT_URI`	URI dell'account BLOB per l'accesso all'archiviazione del payload basato su identità	non impostato
`PAYLOAD_CONTAINER_NAME`	Contenitore BLOB per payload esternalizzati	`durabletask-payloads`
`PAYLOAD_SIZE_BYTES`	Dimensioni del payload predefinite usate dall'endpoint di esecuzione	`1572864`
`EXTERNALIZE_THRESHOLD_BYTES`	Soglia di scarico dei BLOB	`900000`
`PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID`	ID client dell'identità gestita assegnata dall'utente facoltativo per l'accesso all'archiviazione	non impostato
`AZURE_CLIENT_ID`	Modo alternativo per selezionare un'identità gestita assegnata dall'utente	non impostato
`ASPNETCORE_URLS`	URL di ascolto per l'host HTTP dell'esempio	framework predefinito

Se PAYLOAD_STORAGE_CONNECTION_STRING non è impostato e PAYLOAD_STORAGE_ACCOUNT_URI viene fornito , l'esempio usa DefaultAzureCredential. Se è necessaria un'identità assegnata dall'utente specifica, impostare PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID o AZURE_CLIENT_ID.

Variable	Descrizione	Impostazione predefinita di esempio
`ENDPOINT`	Endpoint del Task Scheduler durevole	`http://localhost:8080`
`TASKHUB`	Hub attività di destinazione	`default`
`STORAGE_CONNECTION_STRING`	Stringa di connessione di archiviazione Blob per payload esternalizzati	`UseDevelopmentStorage=true`

L'esempio di Python imposta threshold_bytes nel codice con BlobPayloadStoreOptions.

autorizzazioni Azure

Quando si usano risorse Azure anziché emulatori locali, l'identità dell'app deve accedere a Durable Task Scheduler e gestione rete virtuale di Azure:

Concedere il ruolo Durable Task Data Contributor nell'hub attività dell'app.
Concedere il ruolo Storage Blob Data Contributor nell'account di archiviazione che memorizza i BLOB di payload.

Queste autorizzazioni si applicano alle app Durable Functions e alle app Durable Task SDK che usano un'identità gestita.

Controllare che il funzionamento del payload offload sia corretto

Dopo aver abilitato l'offload del payload, eseguire un'orchestrazione con un input o un output superiore alla soglia configurata. Verificare quindi la presenza di entrambi i segnali:

L'orchestrazione viene completata con successo anche se il carico utile supera 1 MiB.
Le voci del BLOB vengono visualizzate nel contenitore durabletask-payloads.

Per lo sviluppo locale, eseguire questo comando interfaccia della riga di comando di Azure per esaminare il contenitore:

az storage blob list \
  --connection-string "UseDevelopmentStorage=true" \
  --container-name durabletask-payloads \
  --output table

Le app di esempio convalidano anche il round trip:

Gli esempi Durable Functions restituiscono un piccolo oggetto riepilogo che conferma le dimensioni di input e output.
L'esempio .NET Durable Task SDK indica se l'esecuzione crea nuovi blob di payload.
L'esempio Python Durable Task SDK esegue flussi di payload inline ed esterni e stampa il risultato dell'orchestrazione per ogni esecuzione.

Poiché il runtime archivia payload esterni con codifica del contenuto gzip, Azure segnala le dimensioni compresse del BLOB su disco. Con gli attuali campioni di payload a bassa comprimibilità, tali dimensioni del BLOB devono rimanere ragionevolmente vicine alle dimensioni logiche del payload.

Annotazioni

L'eliminazione delle istanze di orchestrazione non elimina attualmente i BLOB di payload esterni corrispondenti da Archiviazione BLOB di Azure. Se è necessario rimuovere questi payload, eliminare i BLOB dall'account di archiviazione separatamente.

Passaggi successivi

Configurare Durable Functions con Durable Task Scheduler

Creare un'app con gli SDK di Durable Task

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-15