Vazby pro Durable Functions (Azure Functions)

Rozšíření Durable Functions zavádí tři aktivační vazby, které řídí provádění funkcí orchestrátoru, entity a aktivit. Zavádí také výstupní vazbu, která funguje jako klient pro modul runtime Durable Functions.

Trigger orchestrace

Trigger orchestrace umožňuje vytvářet trvalé funkce orchestrátoru. Tato aktivační událost se spustí, když je naplánována nová instance orchestrace a když existující instance orchestrace obdrží událost. Mezi příklady událostí, které mohou aktivovat funkce orchestrátoru, patří trvalé vypršení platnosti časovače, odpovědi na funkce aktivity a události vyvolané externími klienty.

Při vytváření funkcí v .NET je trigger orchestrace nakonfigurován pomocí atributu OrchestrationTriggerAttribute .NET. Pro Javu se @DurableOrchestrationTrigger používá poznámka.

Při psaní funkcí orchestrátoru ve skriptovacích jazycích, jako je JavaScript, Python nebo PowerShell, je trigger orchestrace definován následujícím objektem JSON v bindings poli souboru function.json :

{
    "name": "<Name of input parameter in function signature>",
    "orchestration": "<Optional - name of the orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}
  • orchestration je název orchestrace, kterou musí klienti použít, když chtějí spustit nové instance této funkce orchestrátoru. Tato vlastnost je nepovinná. Pokud není zadáno, použije se název funkce.

Tato vazba triggeru interně dotazuje nakonfigurované trvalé úložiště pro nové události orchestrace, jako jsou události zahájení orchestrace, události vypršení platnosti trvalých časovačů, události odezvy funkce aktivity a externí události vyvolané jinými funkcemi.

Chování aktivační události

Tady je několik poznámek k triggeru orchestrace:

  • Jednovláknové zpracování – jedno vlákno dispečeru se používá pro provádění všech funkcí orchestrátoru v jedné instanci hostitele. Z tohoto důvodu je důležité zajistit, aby kód funkce orchestrátoru byl efektivní a neprovádí žádné vstupně-výstupní operace. Je také důležité zajistit, aby toto vlákno neprovádí žádnou asynchronní práci s výjimkou čekání na typy úloh specifických pro Durable Functions.
  • Zpracování otrávných zpráv – v triggerech orchestrace neexistuje žádná podpora otrávných zpráv.
  • Viditelnost zpráv – Zprávy triggeru orchestrace jsou vyřazeny z fronty a po konfigurovatelnou dobu jsou neviditelné. Viditelnost těchto zpráv se obnoví automaticky, pokud je aplikace funkcí spuštěná a v pořádku.
  • Návratové hodnoty – Návratové hodnoty se serializují do FORMÁTU JSON a uchovávají se v tabulce historie orchestrace ve službě Azure Table Storage. Tyto návratové hodnoty mohou být dotazovány vazbou klienta orchestrace popsané později.

Upozornění

Funkce orchestratoru by nikdy neměly používat žádné vstupní nebo výstupní vazby, než je vazba triggeru orchestrace. To má potenciál způsobit problémy s rozšířením Durable Task, protože tyto vazby nemusí dodržovat pravidla pro jednovláknové a vstupně-výstupní operace. Pokud chcete použít jiné vazby, přidejte je do funkce aktivity volané z funkce orchestrátoru. Další informace o kódování omezení pro funkce orchestrátoru najdete v dokumentaci k omezením kódu funkce nástroje Orchestrator .

Upozornění

Funkce orchestrátoru JavaScriptu a Pythonu by nikdy neměly být deklarovány async.

Aktivace využití

Vazba triggeru orchestrace podporuje vstupy i výstupy. Tady je několik věcí, které je potřeba vědět o zpracování vstupu a výstupu:

  • vstupy – Triggery orchestrace lze vyvolat se vstupy, které jsou přístupné prostřednictvím kontextového vstupního objektu. Všechny vstupy musí být serializovatelné ve formátu JSON.
  • výstupy – Triggery orchestrace podporují výstupní hodnoty i vstupy. Návratová hodnota funkce se používá k přiřazení výstupní hodnoty a musí být serializovatelná ve formátu JSON.

Ukázka triggeru

Následující příklad kódu ukazuje, jak může vypadat nejjednodušší funkce orchestrátoru "Hello World". Všimněte si, že tento ukázkový orchestrátor ve skutečnosti neplánuje žádné úkoly.

[FunctionName("HelloWorld")]
public static string Run([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

Poznámka

Předchozí kód je pro Durable Functions 2.x. Pro Durable Functions 1.x je nutné místo DurableOrchestrationContextIDurableOrchestrationContext. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Většina funkcí orchestrátoru volá funkce aktivity, takže tady je příklad "Hello World", který ukazuje, jak volat funkci aktivity:

[FunctionName("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

Poznámka

Předchozí kód je pro Durable Functions 2.x. Pro Durable Functions 1.x je nutné místo DurableOrchestrationContextIDurableOrchestrationContext. Další informace o rozdílech mezi verzemi najdete v článku o Durable Functions verzích.

Trigger aktivity

Trigger aktivity umožňuje vytvářet funkce, které jsou volána funkcemi orchestrátoru, označované jako funkce aktivit.

Pokud v .NET pracujete s funkcemi, je trigger aktivity nakonfigurovaný pomocí atributu ActivityTriggerAttribute .NET. Pro Javu se @DurableActivityTrigger používá poznámka.

Pokud používáte JavaScript, Python nebo PowerShell, je aktivační událost aktivity definovaná následujícím objektem JSON v bindings poli function.json:

{
    "name": "<Name of input parameter in function signature>",
    "activity": "<Optional - name of the activity>",
    "type": "activityTrigger",
    "direction": "in"
}
  • activity je název aktivity. Tato hodnota je název, který funkce orchestrátoru používají k vyvolání této funkce aktivity. Tato vlastnost je nepovinná. Pokud není zadáno, použije se název funkce.

Interně se tato vazba triggeru dotazuje nakonfigurovaného odolného úložiště pro nové události provádění aktivit.

Chování aktivační události

Tady je několik poznámek k triggeru aktivity:

  • Threading – na rozdíl od triggeru orchestrace nemají triggery aktivit žádná omezení týkající se vláken nebo vstupně-výstupních operací. Mohou být považovány za běžné funkce.
  • Zpracování otrávných zpráv – v triggerech aktivit není žádná podpora otrávené zprávy.
  • Viditelnost zpráv – Zprávy aktivační události aktivity se odvolají a po konfigurovatelnou dobu jsou neviditelné. Viditelnost těchto zpráv se obnoví automaticky, pokud je aplikace funkcí spuštěná a v pořádku.
  • Návratové hodnoty – Návratové hodnoty se serializují do FORMÁTU JSON a uchovávají se v nakonfigurovaném odolném úložišti.

Aktivace využití

Vazba triggeru aktivity podporuje vstupy i výstupy stejně jako trigger orchestrace. Tady je několik věcí, které je potřeba vědět o zpracování vstupu a výstupu:

  • vstupy – Aktivační události aktivity lze vyvolat vstupy z funkce orchestrátoru. Všechny vstupy musí být serializovatelné ve formátu JSON.
  • výstupy – Funkce aktivity podporují výstupní hodnoty i vstupy. Návratová hodnota funkce se používá k přiřazení výstupní hodnoty a musí být serializovatelná ve formátu JSON.
  • metadata – funkce aktivit .NET můžou svázat s parametrem string instanceId , aby získaly ID instance volající orchestrace.

Ukázka triggeru

Následující ukázkový kód ukazuje, jak může vypadat jednoduchá SayHello funkce aktivity:

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] IDurableActivityContext helloContext)
{
    string name = helloContext.GetInput<string>();
    return $"Hello {name}!";
}

Výchozí typ parametru pro vazbu .NET ActivityTriggerAttribute je IDurableActivityContext (nebo DurableActivityContext pro Durable Functions v1). Triggery aktivit .NET ale podporují také vazbu přímo na typy serializovatelné ve formátu JSON (včetně primitivních typů), takže stejná funkce by mohla být zjednodušená takto:

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

Použití vstupních a výstupních vazeb

Kromě vazby triggeru aktivity můžete použít běžné vstupní a výstupní vazby. Můžete například převzít vstup do vazby aktivity a odeslat zprávu do EventHubu pomocí výstupní vazby EventHubu:

{
  "bindings": [
    {
      "name": "message",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "eventHub",
      "name": "outputEventHubMessage",
      "connection": "EventhubConnectionSetting",
      "eventHubName": "eh_messages",
      "direction": "out"
  }
  ]
}
module.exports = async function (context) {
    context.bindings.outputEventHubMessage = context.bindings.message;
};

Klient orchestrace

Vazba klienta orchestrace umožňuje psát funkce, které komunikují s funkcemi orchestrátoru. Tyto funkce se často označují jako klientské funkce. Například můžete pracovat s instancemi orchestrace následujícími způsoby:

  • Zahajte je.
  • Zadejte dotaz na jejich stav.
  • Ukončete je.
  • Posílejte jim události, když jsou spuštěné.
  • Vyprázdnění historie instancí

Pokud používáte .NET, můžete vytvořit vazbu na klienta orchestrace pomocí atributu DurableClientAttribute (OrchestrationClientAttribute v Durable Functions v1.x). Pro Javu použijte poznámku @DurableClientInput .

Pokud používáte skriptovací jazyky, jako je JavaScript, Python nebo PowerShell, je aktivační událost odolného klienta definovaná následujícím objektem JSON v bindings poli function.json:

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "orchestrationClient",
    "direction": "in"
}
  • taskHub – Používá se ve scénářích, kdy více aplikací funkcí sdílí stejný účet úložiště, ale musí být vzájemně izolované. Pokud není zadána, použije se výchozí hodnota z host.json . Tato hodnota musí odpovídat hodnotě používané funkcemi cílového orchestrátoru.
  • connectionName – Název nastavení aplikace, které obsahuje připojovací řetězec účtu úložiště. Účet úložiště reprezentovaný tímto připojovacím řetězcem musí být stejný jako účet úložiště používaný funkcemi cílového orchestrátoru. Pokud není zadaný, použije se výchozí připojovací řetězec účtu úložiště pro aplikaci funkcí.

Poznámka

Ve většině případů doporučujeme tyto vlastnosti vynechat a spoléhat se na výchozí chování.

Využití klienta

Ve funkcích .NET obvykle vytvoříte vazbu na IDurableClient (DurableOrchestrationClient v Durable Functions v1.x), která vám umožní úplný přístup ke všem klientským rozhraním API orchestrace podporovaným Durable Functions. Pro Javu se svážete s DurableClientContext třídou. V jiných jazycích musíte k získání přístupu k objektu klienta použít sadu SDK specifickou pro jazyk.

Tady je příklad funkce aktivované frontou, která spustí orchestraci "HelloWorld".

[FunctionName("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] IDurableOrchestrationClient starter)
{
    // Orchestration input comes from the queue message content.
    return starter.StartNewAsync("HelloWorld", input);
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo atributu DurableClient a musíte použít typ parametru DurableOrchestrationClient místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Další podrobnosti o spouštění instancí najdete ve správě instancí.

Trigger entity

Triggery entit umožňují vytvářet funkce entit. Tato aktivační událost podporuje zpracování událostí pro konkrétní instanci entity.

Poznámka

Triggery entit jsou k dispozici od Durable Functions 2.x.

Interně se tato vazba triggeru dotazuje nakonfigurovaného odolného úložiště pro nové operace entity, které je potřeba spustit.

Pokud v .NET pracujete s funkcemi, je trigger entity nakonfigurovaný pomocí atributu EntityTriggerAttribute .NET.

Pokud používáte JavaScript, Python nebo PowerShell, je trigger entity definovaný následujícím objektem JSON v bindings poli function.json:

{
    "name": "<Name of input parameter in function signature>",
    "entityName": "<Optional - name of the entity>",
    "type": "entityTrigger",
    "direction": "in"
}

Poznámka

Triggery entit se v Javě zatím nepodporují.

Ve výchozím nastavení je název entity názvem funkce.

Chování aktivační události

Tady je několik poznámek k triggeru entity:

  • Jednovláknové: Jedno vlákno dispečeru se používá ke zpracování operací pro konkrétní entitu. Pokud se současně do jedné entity odešle více zpráv, operace se zpracují jednorázově.
  • Zpracování otrávných zpráv – v triggerech entit není žádná podpora otrávené zprávy.
  • Viditelnost zpráv – Zprávy triggeru entity jsou vyřazeny z fronty a po konfigurovatelnou dobu trvání jsou neviditelné. Viditelnost těchto zpráv se obnoví automaticky, pokud je aplikace funkcí spuštěná a v pořádku.
  • Návratové hodnoty – Funkce entity nepodporují návratové hodnoty. Existují specifická rozhraní API, která je možné použít k uložení stavu nebo předání hodnot zpět do orchestrací.

Všechny změny stavu provedené v entitě během provádění se po dokončení provádění automaticky zachovají.

Další informace a příklady definování a interakce s triggery entit najdete v dokumentaci Durable Entities .

Klient entity

Vazba klienta entity umožňuje asynchronně aktivovat funkce entit. Tyto funkce se někdy označují jako klientské funkce.

Pokud používáte předkompilované funkce .NET, můžete svázat s klientem entity pomocí atributu DurableClientAttribute .NET.

Poznámka

[DurableClientAttribute] se také použít k vytvoření vazby k klientovi orchestrace.

Pokud pro vývoj používáte skriptovací jazyky (například skriptování jazyka C#, JavaScript nebo Python), je trigger entity definovaný následujícím objektem JSON v bindings poli function.json:

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "durableClient",
    "direction": "in"
}

Poznámka

Klienti entit se v Javě zatím nepodporují.

  • taskHub – Používá se ve scénářích, kdy více aplikací funkcí sdílí stejný účet úložiště, ale musí být vzájemně izolované. Pokud není zadána, použije se výchozí hodnota z host.json . Tato hodnota musí odpovídat hodnotě používané funkcemi cílové entity.
  • connectionName – Název nastavení aplikace, které obsahuje připojovací řetězec účtu úložiště. Účet úložiště reprezentovaný tímto připojovacím řetězcem musí být stejný jako účet úložiště používaný funkcemi cílové entity. Pokud není zadaný, použije se výchozí připojovací řetězec účtu úložiště pro aplikaci funkcí.

Poznámka

Ve většině případů doporučujeme vynechat volitelné vlastnosti a spoléhat se na výchozí chování.

Další informace a příklady interakce s entitami jako klienta najdete v dokumentaci Durable Entities .

Nastavení host.json

Nastavení konfigurace pro Durable Functions

Poznámka

Všechny hlavní verze Durable Functions jsou podporovány ve všech verzích modulu runtime Azure Functions. Schéma konfigurace host.json se ale mírně liší v závislosti na verzi modulu runtime Azure Functions a verzi rozšíření Durable Functions, kterou používáte. Následující příklady se používají s Azure Functions 2.0 a 3.0. V obou příkladech platí, že pokud používáte Azure Functions 1.0, jsou dostupná nastavení stejná, ale část DurableTask souboru host.json by měla být v kořenovém adresáři konfigurace host.json, nikoli jako pole v části Rozšíření.

{
 "extensions": {
  "durableTask": {
    "hubName": "MyTaskHub",
    "storageProvider": {
      "connectionStringName": "AzureWebJobsStorage",
      "controlQueueBatchSize": 32,
      "controlQueueBufferThreshold": 256,
      "controlQueueVisibilityTimeout": "00:05:00",
      "maxQueuePollingInterval": "00:00:30",
      "partitionCount": 4,
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "useLegacyPartitionManagement": true,
      "workItemQueueVisibilityTimeout": "00:05:00",
    },
    "tracing": {
      "traceInputsAndOutputs": false,
      "traceReplayEvents": false,
    },
    "notifications": {
      "eventGrid": {
        "topicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
        "keySettingName": "EventGridKey",
        "publishRetryCount": 3,
        "publishRetryInterval": "00:00:30",
        "publishEventTypes": [
          "Started",
          "Pending",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50
  }
 }
}

Názvy centra úkolů musí začínat písmenem a obsahovat pouze písmena a číslice. Pokud není zadaný, výchozí název centra úloh pro aplikaci funkcí je DurableFunctionsHub. Další informace najdete v tématu Centra úloh.

Vlastnost Výchozí Popis
hubName DurableFunctionsHub Názvy alternativních center úloh je možné použít k izolaci více Durable Functions aplikací mezi sebou, i když používají stejný back-end úložiště.
controlQueueBatchSize 32 Počet zpráv, které se mají načíst z řídicí fronty najednou
controlQueueBufferThreshold Plán Consumption pro Python: 32
Plán Consumption pro JavaScript a C#: 128
Vyhrazený/Premium plán: 256
Počet řídicích zpráv fronty, které lze ukládat do vyrovnávací paměti najednou, v tomto okamžiku bude dispečer čekat před vyřazením dalších zpráv.
partitionCount 4 Počet oddílů pro řídicí frontu Může být kladné celé číslo mezi 1 a 16.
controlQueueVisibilityTimeout 5 minut Časový limit viditelnosti zpráv fronty vyřazených ovládacích prvků
workItemQueueVisibilityTimeout 5 minut Časový limit viditelnosti zpráv fronty vyřazených pracovních položek
maxConcurrentActivityFunctions Plán Consumption: 10
Vyhrazený/Premium plán: 10X počet procesorů na aktuálním počítači
Maximální počet funkcí aktivity, které lze zpracovávat souběžně v jedné instanci hostitele.
maxConcurrentOrchestratorFunctions Plán Consumption: 5
Vyhrazený/Premium plán: 10X počet procesorů na aktuálním počítači
Maximální počet funkcí orchestrátoru, které lze zpracovávat souběžně v jedné instanci hostitele.
maxQueuePollingInterval 30 sekund Maximální interval dotazování fronty a pracovní položky ve formátu hh:mm:ss . Vyšší hodnoty můžou mít za následek vyšší latenci zpracování zpráv. Nižší hodnoty můžou mít za následek vyšší náklady na úložiště kvůli zvýšeným transakcím úložiště.
connectionName (2.7.0 a novější)
connectionStringName (2.x)
azureStorageConnectionStringName (1.x)
AzureWebJobsStorage Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k podkladovým Azure Storage prostředkům. Pokud je k dispozici nastavení jedné aplikace, mělo by se jednat o připojovací řetězec Azure Storage.
trackingStoreConnectionName (2.7.0 a novější)
trackingStoreConnectionStringName
Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k tabulkám Historie a Instance. Pokud je k dispozici nastavení jedné aplikace, mělo by se jednat o připojovací řetězec Azure Storage. Pokud není zadáno, connectionStringName použije se připojení (Durable 2.x) nebo azureStorageConnectionStringName (Durable 1.x).
trackingStoreNamePrefix Předpona, která se má použít pro tabulky Historie a Instance, pokud trackingStoreConnectionStringName je zadána. Pokud není nastavena, bude výchozí hodnota DurableTaskpředpony . Pokud trackingStoreConnectionStringName není zadána, budou tabulky Historie a Instance používat hodnotu jako předponu hubName a všechna nastavení pro trackingStoreNamePrefix budou ignorována.
traceInputsAndOutputs false (nepravda) Hodnota označující, zda se mají trasovat vstupy a výstupy volání funkce. Výchozím chováním při trasování událostí provádění funkce je zahrnout počet bajtů do serializovaných vstupů a výstupů pro volání funkce. Toto chování poskytuje minimální informace o tom, jak vypadají vstupy a výstupy bez bloudení protokolů nebo neúmyslného zveřejnění citlivých informací. Nastavení této vlastnosti na true způsobí, že výchozí protokolování funkce protokoluje celý obsah vstupů a výstupů funkce.
traceReplayEvents false (nepravda) Hodnota označující, jestli se mají události orchestrace přehrávat do Přehledy aplikace.
eventGridTopicEndpoint Adresa URL koncového bodu Azure Event Grid vlastního tématu Pokud je tato vlastnost nastavená, publikují se do tohoto koncového bodu události oznámení o životním cyklu orchestrace. Tato vlastnost podporuje řešení Nastavení aplikací.
eventGridKeySettingName Název nastavení aplikace obsahující klíč použitý k ověřování s Azure Event Grid vlastním tématem na adrese EventGridTopicEndpoint.
eventGridPublishRetryCount 0 Počet opakování, pokud publikování do tématu Event Grid selže.
eventGridPublishRetryInterval 5 minut Event Grid publikuje interval opakování ve formátu hh:mm:ss .
eventGridPublishEventTypes Seznam typů událostí, které se mají publikovat do Event Gridu. Pokud není zadáno, budou publikovány všechny typy událostí. Povolené hodnoty zahrnují Started, , FailedCompleted, Terminated.
useAppLease true Při nastavení truena hodnotu budou aplikace před zpracováním zpráv centra úloh vyžadovat získání zapůjčení objektů blob na úrovni aplikace. Další informace najdete v dokumentaci k zotavení po havárii a geografické distribuci . K dispozici od verze 2.3.0.
useLegacyPartitionManagement false (nepravda) Pokud je nastavená falsehodnota , používá algoritmus správy oddílů, který snižuje možnost duplicitního spuštění funkce při horizontálním navýšení kapacity. K dispozici od verze 2.3.0.
useGracefulShutdown false (nepravda) (Preview) Povolte řádné vypnutí, aby se snížila pravděpodobnost, že hostitelské vypnutí selhává při provádění funkcí v procesu.
maxEntityOperationBatchSize(2.6.1) Plán Consumption: 50
Vyhrazený/Premium plán: 5000
Maximální počet operací entit, které se zpracovávají jako dávka. Pokud je nastavená hodnota 1, je dávkování zakázané a každá zpráva operace se zpracuje samostatnou vyvoláním funkce.

Mnoho z těchto nastavení slouží k optimalizaci výkonu. Další informace najdete v tématu Výkon a škálování.

Další kroky