Obsługa dużych ładunków za pomocą narzędzia Durable Task Scheduler (wersja zapoznawcza)

Obsługa dużych ładunków umożliwia aplikacji przekazywanie danych wejściowych orkiestracji i danych wyjściowych działań, które przekraczają limit rozmiaru komunikatów Durable Task Scheduler. Gdy ładunek przekroczy skonfigurowany próg, struktura przechowuje serializowany ładunek w Azure Blob Storage i wysyła małe odwołanie za pomocą narzędzia Durable Task Scheduler.

Ta funkcja jest dostępna dla:

Jeśli przepływ pracy przechowuje dane w Blob Storage i przekazuje tylko URI lub identyfikator, kontynuuj używanie tego wzorca. Użyj obsługi dużych ładunków, gdy logika aranżacji musi przekazać ładunek między operacjami trwałymi. Aby uzyskać ogólne wskazówki, zobacz Trwałość danych i serializacja w Durable Functions.

Obsługiwane platformy

W tej tabeli przedstawiono obsługę dużych ładunków według platformy.

Framework Status wsparcia Czego potrzebujesz
Durable Functions Obsługiwane w izolowanym języku C# .NET Użyj narzędzia Durable Task Scheduler jako dostawcy magazynu i użyj go AzureWebJobsStorage do ładowania obiektów blob
Trwałe zestawy SDK dla zadań Obsługiwane w .NET i Python Użyj rozszerzenia specyficznego dla języka dla ładunku Azure Blob z Azure Blob Storage
JavaScript, PowerShell i Java Niedostępne Używanie magazynu zewnętrznego i przekazywanie odwołań między operacjami trwałymi

Jak to działa

Po włączeniu obsługi dużych ładunków, środowisko uruchomieniowe śledzi ten sam przepływ wysokopoziomowy w obu modelach hostingu aplikacji.

  1. Serializuje dane wejściowe lub wyjściowe działania orkiestracji.
  2. Jeśli rozmiar ładunku przekracza skonfigurowany próg, środowisko uruchomieniowe kompresuje ładunek za pomocą narzędzia gzip.
  3. Zapisuje skompresowany ładunek do Azure Blob Storage.
  4. Wysyła odniesienie do obiektu blob za pomocą Trwałego Harmonogramu Zadań zamiast pełnej zawartości.
  5. Środowisko uruchomieniowe automatycznie rozpoznaje odwołanie, zanim orkiestrator lub kod działania odczyta wartość.

Bieżące przykłady .NET używają deterministycznych ładunków o niskiej kompresji, mających rozmiar 1,5 MiB. Dzięki temu przechowywany rozmiar obiektu blob jest reprezentatywny, mimo że środowisko uruchomieniowe zapisuje obiekty blob z kodowaniem zawartości gzip.

Duże wsparcie dla ładunków wpływa na sposób, w jaki ładunki są przenoszone w środowisku uruchomieniowym. Nie zmienia zalecenia, aby zachować stan trwały tak mały, jak to możliwe w praktyce.

Wybieranie odpowiedniego wzorca

Użyj najprostszego wzorca dla danego scenariusza.

Użyj tego wzorca Kiedy go użyć
Obsługa dużych pakietów danych Orkiestracja przekazuje ładunek między operacjami trwałymi, a ładunek przekracza limit komunikatów harmonogramu
Pamięć zewnętrzna i odwołania Działania ładują dane bezpośrednio z magazynu i chcesz uzyskać najmniejszy możliwy stan aranżacji

Włączanie obsługi dużych ładunków

Obsługa dużych ładunków w Durable Functions jest dostępna tylko dla .NET izolowanych aplikacji języka C#, które używają harmonogramu Durable Task Scheduler jako dostawcę przechowywania.

Przed włączeniem tej funkcji upewnij się, że aplikacja:

  • Używa izolowanego wykonawcy .NET.
  • Odwołania Microsoft.Azure.Functions.Worker.Extensions.DurableTask i Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged.
  • Ustawia AzureWebJobsStorage dla konta magazynu, które przechowuje zewnętrzne dane.
  • Ustawia DTS_CONNECTION_STRING i TASKHUB_NAME dla docelowego harmonogramu i centrum zadań.

Następnie włącz duży magazyn ładunku w host.json:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DTS_CONNECTION_STRING",
        "payloadStorageEnabled": true,
        "payloadStorageThresholdBytes": 262144
      },
      "hubName": "%TASKHUB_NAME%"
    }
  }
}

Ustaw payloadStorageThresholdBytes poniżej granicy rozmiaru wiadomości w Harmonogramie Trwałych Zadań, aby środowisko uruchomieniowe zewnętrzniało ładunki przed zbliżeniem się do limitu.

Użyj standardowych interfejsów API Durable Functions w kodzie orkiestratora i aktywności. Środowisko uruchomieniowe automatycznie rozpoznaje odwołania do obiektów blob przed context.GetInput<T>() i context.CallActivityAsync<T>() zwróceniem danych.

Domyślnie rozszerzenie zapisuje zewnętrzne ładunki do kontenera durabletask-payloads na koncie magazynu skonfigurowanym przez AzureWebJobsStorage.

Aby uzyskać kompleksowe przykłady od początku do końca, zobacz następujące próbki:

Wsparcie dla dużych ładunków w SDK Durable Task jest dostępne dla aplikacji .NET i Python.

Aby zainstalować pakiet rozszerzenia danych Azure Blob:

dotnet add package Microsoft.DurableTask.Extensions.AzureBlobPayloads

Zainstaluj pakiety klienta i pakiety robocze zarządzane przez Azure dla Durable Task Scheduler:

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

Zarejestruj zewnętrzny magazyn ładunków, wybierz próg i włącz rozpoznawanie ładunku zarówno na kliencie, jak i w ramach procesu roboczego:

builder.Services.AddExternalizedPayloadStore(options =>
{
    options.ThresholdBytes = 262_144;
    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();
});

Jeśli używasz Microsoft Entra ID zamiast ciągu połączenia magazynu, ustaw options.AccountUri i options.Credential. Przykład używa DefaultAzureCredential i opcjonalnie może kierować na tożsamość zarządzaną przypisaną przez użytkownika.

Utrzymuj ThresholdBytes na poziomie czy poniżej 1,048,576 bajtów. W przykładzie użyto 262,144 bajtów (256 KiB), co jest również domyślną wartością w pakiecie SDK, więc ładunki są odciążane, zanim zbliżą się do granicy 1 MiB dla komunikatu harmonogramu.

Aby zapoznać się z kompleksowym przykładem .NET, zobacz przykład Durable Task SDK — przykład dużego ładunku.

Konfiguracja zmiennej środowiskowej

Użyj tych ustawień lokalnych lub ustawień aplikacji z bieżącymi przykładami Durable Functions.

Setting Opis Przykładowa wartość domyślna
FUNCTIONS_WORKER_RUNTIME Azure Functions - izolowane środowisko uruchomieniowe aplikacji roboczej dotnet-isolated
AzureWebJobsStorage Przechowywanie stanu hosta i ładunku obiektów blob dla usługi Functions UseDevelopmentStorage=true Lokalnie
DTS_CONNECTION_STRING Ciąg połączenia do harmonogramu zadań trwałych Endpoint=http://localhost:8080;Authentication=None
TASKHUB_NAME Docelowe centrum zadań default
PAYLOAD_SIZE_BYTES Rozmiar ładunku używanego przez element inicjujący lub generowanego przez każde działanie 1572864
ACTIVITY_COUNT Liczba równoległych działań w przykładzie fan-out/fan-in tylko 3

To ACTIVITY_COUNT ustawienie jest używane tylko przez LargePayloadFanOutFanIn próbkę. Przykładowa LargePayload runda nie odczytuje jej.

Użyj tych zmiennych środowiskowych w bieżących przykładach zestawu SDK Durable Task.

Zmienna Opis Przykładowa wartość domyślna
DURABLE_TASK_SCHEDULER_CONNECTION_STRING Ciąg połączenia do harmonogramu zadań trwałych Endpoint=http://localhost:8080;TaskHub=default;Authentication=None
PAYLOAD_STORAGE_CONNECTION_STRING Connection string usługi Blob Storage dla ładunków zewnętrznych UseDevelopmentStorage=true
PAYLOAD_STORAGE_ACCOUNT_URI URI konta Blob na potrzeby dostępu do magazynu ładunku opartego na tożsamości Nieustawiony
PAYLOAD_CONTAINER_NAME Kontener obiektów blob dla ładunków zewnętrznych durabletask-payloads
PAYLOAD_SIZE_BYTES Domyślny rozmiar ładunku używany przez endpoint run 1572864
THRESHOLD_BYTES Próg odciążania dla bloba 262144
PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID Opcjonalny identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika na potrzeby dostępu do przechowywania danych Nieustawiony
AZURE_CLIENT_ID Alternatywny sposób wybierania tożsamości zarządzanej przypisanej przez użytkownika Nieustawiony
ASPNETCORE_URLS Adresy URL nasłuchiwania dla hosta HTTP próbki domyślna struktura

Jeśli PAYLOAD_STORAGE_CONNECTION_STRING nie jest ustawione i PAYLOAD_STORAGE_ACCOUNT_URI jest podane, próbka używa DefaultAzureCredential. Jeśli potrzebujesz określonej tożsamości przypisanej użytkownikowi, ustaw PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID albo AZURE_CLIENT_ID.

uprawnienia Azure

Jeśli używasz zasobów Azure zamiast lokalnych emulatorów, tożsamość aplikacji musi mieć dostęp do Durable Task Scheduler i Blob Storage.

  • Nadaj Durable Task Data Contributor w centrum zadań aplikacji.
  • Przyznaj Storage Blob Data Contributor na koncie magazynu przechowującym blob zawartości.

Te uprawnienia mają zastosowanie do aplikacji Durable Functions i aplikacji zestawu Durable Task SDK korzystających z tożsamości zarządzanej.

Sprawdzanie, czy odciążanie ładunku działa

Po włączeniu odciążania ładunku uruchom orkiestrację z danymi wejściowymi lub wyjściowymi, które są większe niż skonfigurowany próg. Następnie sprawdź oba sygnały:

  • Orkiestracja kończy się pomyślnie, mimo że ładunek przekracza 1 MiB.
  • Wpisy obiektów blob są wyświetlane w kontenerze durabletask-payloads.

W przypadku programowania lokalnego uruchom następujące polecenie Azure CLI, aby sprawdzić kontener:

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

Przykładowe aplikacje weryfikują również cykl zwrotny.

  • Przykłady Durable Functions zwracają mały obiekt podsumowania, który potwierdza rozmiary danych wejściowych i wyjściowych.
  • Przykładowy zestaw SDK .NET Durable Task wyświetla, czy uruchomienie tworzy nowe bloby ładunków.
  • Przykład SDK Durable Task dla Pythona uruchamia zarówno wbudowane, jak i zewnętrzne przepływy danych oraz wyświetla wynik orkiestracji dla każdego przebiegu.

Ponieważ środowisko uruchomieniowe przechowuje zewnętrzne ładunki danych z kodowaniem zawartości typu gzip, Azure raportuje skompresowany rozmiar blobu na dysku. W przypadku bieżących próbkowych ładunków o niskiej kompresji rozmiary blobów powinny pozostać rozsądnie zbliżone do rozmiaru ładunku logicznego.

Uwaga / Notatka

Przeczyszczanie wystąpień orkiestracji nie powoduje obecnie usunięcia odpowiednich zewnętrznych obiektów blob ładunku z Azure Blob Storage. Jeśli musisz usunąć te ładunki, usuń obiekty blob z konta magazynu oddzielnie.

Następne kroki

Konfiguruj Durable Functions z trwałym harmonogramem zadań

Utwórz aplikację przy użyciu Durable Task SDK

  • Last updated on