Suporte para payloads grandes com Durable Task Scheduler (Versão preliminar)

O suporte a grandes cargas úteis permite que a sua aplicação transmita entradas para orquestração e resultados de atividade que excedam o limite de tamanho das mensagens do Durable Task Scheduler. Quando uma carga útil ultrapassa o limiar configurado, o framework armazena a carga útil serializada no Armazenamento de Blobs do Azure e envia uma pequena referência através do Durable Task Scheduler.

Esta funcionalidade está disponível para:

Durable Functions com o trabalhador .NET isolado
.NET SDK de Tarefas Duráveis
Python SDK de Tarefas Duráveis

Se o seu fluxo de trabalho armazena dados no Armazenamento de Blobs e passa apenas um URI ou identificador, continue a usar esse padrão. Use suporte de carga útil grande quando a lógica de orquestração tiver de passar a carga útil entre operações duradouras. Para orientações gerais, veja persistência e serialização de dados em Durable Functions.

Estruturas suportadas

Esta tabela mostra o suporte a grandes volumes de dados por frameworks.

Framework	Estado do suporte	O que precisa
Durable Functions	Suportado em .NET isolado C#	Use o Durable Task Scheduler como fornecedor de armazenamento e utilize `AzureWebJobsStorage` para blobs de carga útil
SDKs de Tarefas Duráveis	Suportado em .NET e Python	Use a extensão Azure Blob payload específica da linguagem com Armazenamento de Blobs do Azure
JavaScript, PowerShell e Java	Não disponível	Use armazenamento externo e passe referências entre operações duráveis

Como funciona

Quando ativa o suporte a grandes cargas úteis, o tempo de execução segue o mesmo fluxo de alto nível em ambos os modelos de alojamento:

Serializa o input de orquestração ou o output da atividade.
Se o tamanho da carga útil exceder o seu limiar configurado, o tempo de execução comprime a carga útil com gzip.
Escreve o payload comprimido no Armazenamento de Blobs do Azure.
Envia uma referência de blob através do Durable Task Scheduler em vez da carga útil completa.
O tempo de execução resolve a referência automaticamente antes que o seu orquestrador ou o código de atividade leia o valor.

As amostras .NET atuais utilizam cargas úteis determinísticas e de baixa compressibilidade de 1,5 MiB. Isso mantém o tamanho do blob armazenado representativo, mesmo que o runtime escreva blobs com codificação de conteúdo gzip.

O suporte para grandes cargas úteis altera a forma como o processamento das cargas ocorre ao longo do tempo de execução. Isso não altera a recomendação de manter o estado durável tão pequeno quanto possível.

Escolhe o molde certo

Usa o padrão mais simples para o teu cenário.

Use este padrão	Quando Utilizar
Suporte de grandes cargas úteis	A sua orquestração passa a carga útil entre operações duradouras, e a carga útil ultrapassa o limite de mensagens do orquestrador
Armazenamento externo mais referências	As tuas atividades carregam dados diretamente do armazenamento e queres o menor estado de orquestração possível

Permitir suporte de grandes cargas úteis

O suporte a grandes cargas úteis em Durable Functions está disponível apenas para aplicações C# isoladas do .NET que utilizam o Durable Task Scheduler como provedor de armazenamento.

Antes de ativar a funcionalidade, certifique-se de que a sua aplicação:

Usa o trabalhador isolado .NET.
Referências Microsoft.Azure.Functions.Worker.Extensions.DurableTask e Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged.
Define AzureWebJobsStorage para a conta de armazenamento que contém cargas úteis externalizadas.
Sets DTS_CONNECTION_STRING e TASKHUB_NAME para o agendador de objetivo e o hub de tarefas.

Depois, ative o armazenamento de payloads grandes no host.json:

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

Configure largePayloadStorageThresholdBytes abaixo do limite de tamanho da mensagem do Durable Task Scheduler para que o runtime externalize as cargas úteis antes de alcançarem esse limite.

Use as APIs padrão das Durable Functions no seu orquestrador e código de atividade. O tempo de execução resolve automaticamente as referências de blob antes de context.GetInput<T>() e context.CallActivityAsync<T>() devolver os dados.

Por padrão, a extensão escreve cargas externalizadas no contentor durabletask-payloads na conta de armazenamento configurada por AzureWebJobsStorage.

Para exemplos de ponta a ponta, veja estes exemplos:

O suporte a grandes cargas de dados nos SDKs de Tarefas Duráveis está disponível para aplicações .NET e Python.

Instale o pacote de extensão de payload Azure Blob:

dotnet add package Microsoft.DurableTask.Extensions.AzureBlobPayloads

Instale os pacotes de cliente e de trabalhador geridos pelo Azure para o *Durable Task Scheduler*.

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

Registar um armazenamento de carga útil externalizada, escolher um limiar e ativar a resolução da carga útil tanto no cliente como no trabalhador:

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 usares Microsoft Entra ID em vez de uma cadeia de conexão de armazenamento, define options.AccountUri e options.Credential. A amostra utiliza DefaultAzureCredential e pode direcionar opcionalmente uma identidade gerida atribuída pelo utilizador.

Mantém ExternalizeThresholdBytes até ou abaixo de 1,048,576 bytes. A amostra utiliza 900,000 bytes para que as cargas úteis sejam descarregadas antes de se aproximarem da fronteira do agendador de mensagens de 1 MiB.

Para um exemplo de .NET de ponta a ponta, veja o exemplo de carga útil grande do Durable Task SDK.

Instale o SDK Python com a extensão de payload Azure Blob e o pacote de transporte gerenciado Azure:

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

Crie um BlobPayloadStore, escolha um limiar e passe o mesmo repositório tanto para o trabalhador como para o cliente:

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 utilizar o Microsoft Entra ID em vez de uma cadeia de ligação de armazenamento, configure account_url e credential em BlobPayloadStoreOptions. A amostra utiliza DefaultAzureCredential.

Mantém threshold_bytes até ou abaixo de 1,048,576 bytes. A amostra atual usa 1,024 bytes, por isso pode ver a externalização da carga útil durante uma execução local.

Para um exemplo completo em Python, veja o exemplo Python de grande capacidade do Durable Task SDK.

Configuração da variável de ambiente

Utilize estas definições locais ou da aplicação com os exemplos atuais do Durable Functions.

Configuração	Descrição	Exemplo padrão
`FUNCTIONS_WORKER_RUNTIME`	Funções do Azure runtime de trabalhador isolado	`dotnet-isolated`
`AzureWebJobsStorage`	Estado do host e blobs de carga útil do Storage for Functions	`UseDevelopmentStorage=true` Localmente
`DTS_CONNECTION_STRING`	Cadeia de conexão do Durable Task Scheduler	`Endpoint=http://localhost:8080;Authentication=None`
`TASKHUB_NAME`	Centro de tarefas alvo	`default`
`PAYLOAD_SIZE_BYTES`	Tamanho da carga útil utilizado pelo iniciador ou gerado por cada atividade	`1572864`
`ACTIVITY_COUNT`	Número de atividades paralelas na amostra do modelo fan-out/fan-in apenas	`3`

A ACTIVITY_COUNT configuração é usada apenas pela LargePayloadFanOutFanIn amostra. A LargePayload amostra de ida e volta não o lê.

Use estas variáveis de ambiente com as amostras atuais do SDK de Tarefas Duradouras.

Variable	Descrição	Exemplo padrão
`DURABLE_TASK_SCHEDULER_CONNECTION_STRING`	String de conexão do Durable Task Scheduler	`Endpoint=http://localhost:8080;TaskHub=default;Authentication=None`
`PAYLOAD_STORAGE_CONNECTION_STRING`	String de conexão para armazenamento de blobs para cargas úteis externalizadas	`UseDevelopmentStorage=true`
`PAYLOAD_STORAGE_ACCOUNT_URI`	URI da conta Blob para acesso ao armazenamento de carga útil com base em identidade	unset
`PAYLOAD_CONTAINER_NAME`	Contentor de blob para cargas úteis externalizadas	`durabletask-payloads`
`PAYLOAD_SIZE_BYTES`	Tamanho padrão da carga útil usado pelo endpoint de execução	`1572864`
`EXTERNALIZE_THRESHOLD_BYTES`	Limiar de descarga de blob	`900000`
`PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID`	ID de cliente de identidade gerida opcional atribuído pelo utilizador para acesso ao armazenamento	unset
`AZURE_CLIENT_ID`	Forma alternativa de selecionar uma identidade gerida atribuída pelo utilizador	unset
`ASPNETCORE_URLS`	URLs de escuta para o host HTTP do exemplo	padrão do framework

Se PAYLOAD_STORAGE_CONNECTION_STRING não for definido e PAYLOAD_STORAGE_ACCOUNT_URI for fornecido, a amostra usa DefaultAzureCredential. Se precisar de uma identidade específica atribuída pelo utilizador, defina PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID ou AZURE_CLIENT_ID.

Variable	Descrição	Exemplo padrão
`ENDPOINT`	Endpoint do Durable Task Scheduler	`http://localhost:8080`
`TASKHUB`	Centro de tarefas alvo	`default`
`STORAGE_CONNECTION_STRING`	String de conexão do armazenamento de blobs para cargas úteis externalizadas	`UseDevelopmentStorage=true`

Os exemplos em Python definem threshold_bytes no código com BlobPayloadStoreOptions.

Permissões do Azure

Quando usa recursos do Azure em vez de emuladores locais, a identidade da aplicação precisa de acesso ao Durable Task Scheduler e ao Armazenamento de Blobs:

Autorizar Durable Task Data Contributor no hub de tarefas da app.
Conceda Storage Blob Data Contributor na conta de armazenamento que armazena os blobs de dados.

Estas permissões aplicam-se a aplicações Durable Functions e aplicações Durable Task SDK que utilizam uma identidade gerida.

Verifica se o descarregamento da carga útil funciona

Depois de ativares o descarregamento do payload, executa uma orquestração com uma entrada ou saída superior ao teu limite configurado. Depois verifica ambos os sinais:

A orquestração é concluída com sucesso, mesmo que a carga útil exceda 1 MiB.
As entradas de Blob aparecem no contentor durabletask-payloads.

Para desenvolvimento local, execute este comando CLI do Azure para inspecionar o contentor:

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

As aplicações de exemplo também validam a viagem de ida e volta:

As amostras das Durable Functions retornam um pequeno objeto resumo que confirma os tamanhos de entrada e saída.
O exemplo do SDK de Tarefas Duráveis .NET imprime se a execução cria novos blobs de carga útil.
O exemplo do Python Durable Task SDK executa fluxos de carga inline e externalizados e imprime o resultado da orquestração em cada execução.

Como o runtime armazena cargas úteis externalizadas com codificação de conteúdo gzip, o Azure reporta o tamanho comprimido do blob no disco. Com as amostras atuais de cargas úteis de baixa compressibilidade, os tamanhos dos blobs devem permanecer razoavelmente próximos do tamanho lógico da carga útil.

Observação

Purgar instâncias de orquestração não apaga atualmente os blobs de payload externalizados correspondentes do Armazenamento de Blobs do Azure. Se precisares de remover esses payloads, apaga os blobs da conta de armazenamento separadamente.

Passos seguintes

Configure Durable Functions com o Durable Task Scheduler

Crie uma aplicação com os SDKs de Tarefas Duráveis

Comentários

Esta página foi útil?

Last updated on 2026-04-15