Példányok kezelése a Durable Functionsben az Azure-ban
A Durable Functions vezénylései hosszú ideig futó állapotalapú függvények, amelyek a beépített felügyeleti API-k használatával elindíthatók, lekérdezhetők, felfüggeszthetők, folytathatók és megszüntethetők. A Durable Functions vezénylési ügyfélkötése számos más példánykezelési API-t is elérhetővé teszi, például külső eseményeket küld a példányoknak, törli a példányelőzményeket stb. Ez a cikk az összes támogatott példánykezelési művelet részleteit ismerteti.
Példányok indítása
A vezénylési ügyfélkötés indítási új (vagy ütemezési új) metódusa új vezénylési példányt indít el. Ez a metódus belsőleg egy üzenetet ír a Durable Functions storage-szolgáltatón keresztül, majd visszaadja. Ez az üzenet aszinkron módon aktiválja egy vezénylési függvény indítását a megadott névvel.
Az új vezénylési példány indításának paraméterei a következők:
- Név: Az ütemezni kívánt vezénylő függvény neve.
- Bemenet: Minden olyan JSON-szerializálható adat, amelyet a vezénylő függvény bemeneteként kell átadni.
- InstanceId: (Nem kötelező) A példány egyedi azonosítója. Ha nem adja meg ezt a paramétert, a metódus véletlenszerű azonosítót használ.
Tipp.
Amikor csak lehetséges, használjon véletlenszerű azonosítót a példányazonosítóhoz. A véletlenszerű példányazonosítók segítenek egyenlő terheléselosztást biztosítani a vezénylőfüggvények több virtuális gépen való skálázása során. A nem véletlenszerű példányazonosítók használatára az a megfelelő idő, amikor az azonosítónak külső forrásból kell származnia, vagy amikor a szimpla vezénylési mintát implementálja.
Az alábbi kód egy új vezénylési példányt elindító példafüggvény:
[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
[QueueTrigger("start-queue")] string input,
[DurableClient] IDurableOrchestrationClient starter,
ILogger log)
{
string instanceId = await starter.StartNewAsync("HelloWorld", input);
log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Azure Functions Core Tools
Közvetlenül is elindíthat egy példányt a func durable start-new
Core Tools parancsával , amely a következő paramétereket veszi igénybe:
function-name
(kötelező): Az elindítandó függvény neve.input
(nem kötelező): Bemenet a függvénybe beágyazott vagy JSON-fájlon keresztül. Fájlok esetén adjon hozzá egy előtagot a fájl@
elérési útjára, például@path/to/file.json
.id
(nem kötelező): A vezénylési példány azonosítója. Ha nem adja meg ezt a paramétert, a parancs véletlenszerű GUID azonosítót használ.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték az AzureWebJobsStorage.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. Ezt a host.json is beállíthatja a durableTask:HubName használatával.
Feljegyzés
A Core Tools parancsai feltételezik, hogy egy függvényalkalmazás gyökérkönyvtárából futtatja őket. Ha kifejezetten megadja a paramétereket és task-hub-name
a connection-string-setting
paramétereket, bármelyik könyvtárból futtathatja a parancsokat. Bár ezeket a parancsokat a függvényalkalmazás-gazdagép futtatása nélkül is futtathatja, előfordulhat, hogy nem figyelhet meg néhány effektust, kivéve, ha a gazdagép fut. A parancs például start-new
elindít egy indítási üzenetet a cél feladatközpontba, de a vezénylés valójában nem fut, hacsak nem fut egy függvényalkalmazás-gazdagépfolyamat, amely feldolgozhatja az üzenetet.
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A következő parancs elindítja a HelloWorld nevű függvényt, és átadja neki a fájl counter-data.json
tartalmát:
func durable start-new --function-name HelloWorld --input @counter-data.json --task-hub-name TestTaskHub
Lekérdezéspéldányok
Az új vezénylési példányok elindítása után nagy valószínűséggel le kell kérdeznie a futtatókörnyezet állapotát, hogy megtudja, futnak-e, befejezték-e vagy sikertelenek.
A vezénylési ügyfélkötés get-status metódusa lekérdezi egy vezénylési példány állapotát.
Paraméterként egy instanceId
(kötelező), showHistory
(nem kötelező), showHistoryOutput
(nem kötelező) és showInput
(nem kötelező) paramétert használ.
showHistory
: Ha be vantrue
állítva, a válasz tartalmazza a végrehajtási előzményeket.showHistoryOutput
: Ha be vantrue
állítva, a végrehajtási előzmények tevékenységkimeneteket tartalmaznak.showInput
: Ha be vanfalse
állítva, a válasz nem tartalmazza a függvény bemenetét. Az alapértelmezett értéktrue
.
A metódus a következő tulajdonságokkal rendelkező objektumot ad vissza:
- Név: A vezénylő függvény neve.
- InstanceId: A vezénylés példányazonosítója (meg kell egyeznie a
instanceId
bemenettel). - CreatedTime: Az az időpont, amikor a vezénylő függvény elindult.
- LastUpdatedTime: A vezénylés utolsó ellenőrzőpontjának időpontja.
- Bemenet: A függvény bemenete JSON-értékként. Ez a mező nem lesz kitöltve, ha
showInput
hamis. - CustomStatus: Egyéni vezénylés állapota JSON formátumban.
- Kimenet: A függvény kimenete JSON-értékként (ha a függvény befejeződött). Ha a vezénylő függvény sikertelen volt, ez a tulajdonság tartalmazza a hiba részleteit. Ha a vezénylő funkciót felfüggesztették vagy leállították, ez a tulajdonság tartalmazza a felfüggesztés vagy a megszüntetés okát (ha van ilyen).
- RuntimeStatus: Az alábbi értékek egyike:
- Függőben: A példány ütemezve van, de még nem indult el.
- Futtatás: A példány elindult.
- Befejezve: A példány megfelelően befejeződött.
- ContinuedAsNew: A példány új előzményekkel újraindult. Ez az állapot átmeneti állapot.
- Sikertelen: A példány hiba miatt meghiúsult.
- Leállt: A példányt hirtelen leállították.
- Felfüggesztve: A példány fel lett függesztve, és később folytatható.
- Előzmények: A vezénylés végrehajtási előzményei. Ezt a mezőt csak akkor tölti ki a rendszer, ha
showHistory
betrue
van állítva.
Feljegyzés
A vezénylő nincs megjelölve mindaddig, Completed
amíg az összes ütemezett feladata be nem fejeződik , és a vezénylő vissza nem tér. Más szóval, nem elegendő, hogy egy vezénylő elérje a nyilatkozatátreturn
, hogy meg kell jelölni.Completed
Ez különösen releváns a használatban lévő esetekben WhenAny
; ezek a vezénylők gyakran return
az összes ütemezett feladat végrehajtása előtt.
Ez a metódus (.NET és Java), undefined
(JavaScript) vagy None
(Python) értéket ad vissza null
, ha a példány nem létezik.
[FunctionName("GetStatus")]
public static async Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("check-status-queue")] string instanceId)
{
DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
// do something based on the current status.
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Azure Functions Core Tools
A vezénylési példány állapotát közvetlenül is lekérheti a func durable get-runtime-status
Core Tools parancsával .
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable get-runtime-status
parancs a következő paramétereket használja:
id
(kötelező): A vezénylési példány azonosítója.show-input
(nem kötelező): Ha be vantrue
állítva, a válasz a függvény bemenetét tartalmazza. Az alapértelmezett értékfalse
.show-output
(nem kötelező): Ha be vantrue
állítva, a válasz a függvény kimenetét tartalmazza. Az alapértelmezett értékfalse
.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
A következő parancs egy 0ab8c55a66644d68a3a8b220b12d209c vezénylési példányazonosítójú példány állapotát kéri le (beleértve a bemenetet és a kimenetet is). Feltételezi, hogy a func
függvényalkalmazás gyökérkönyvtárából futtatja a parancsot:
func durable get-runtime-status --id 0ab8c55a66644d68a3a8b220b12d209c --show-input true --show-output true
A parancs segítségével durable get-history
lekérheti egy vezénylési példány előzményeit. A következő paramétereket veszi igénybe:
id
(kötelező): A vezénylési példány azonosítója.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c
Az összes példány lekérdezése
A nyelvi SDK API-kkal lekérdezheti a feladatközpont összes vezénylési példányának állapotát. Ez a "list-instances" vagy "get-status" API a lekérdezési paramétereknek megfelelő vezénylési példányokat képviselő objektumok listáját adja vissza.
[FunctionName("GetAllStatus")]
public static async Task Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
[DurableClient] IDurableOrchestrationClient client,
ILogger log)
{
var noFilter = new OrchestrationStatusQueryCondition();
OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
noFilter,
CancellationToken.None);
foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
{
log.LogInformation(JsonConvert.SerializeObject(instance));
}
// Note: ListInstancesAsync only returns the first page of results.
// To request additional pages provide the result.ContinuationToken
// to the OrchestrationStatusQueryCondition's ContinuationToken property.
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Azure Functions Core Tools
A példányokat közvetlenül is lekérdezheti a func durable get-instances
Core Tools parancsával .
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable get-instances
parancs a következő paramétereket használja:
top
(nem kötelező): Ez a parancs támogatja a lapozást. Ez a paraméter a kérésenként lekért példányok számának felel meg. Az alapértelmezett érték 10.continuation-token
(nem kötelező): A lekérendő példányok lapját vagy szakaszát jelző jogkivonat. Mindenget-instances
végrehajtás egy jogkivonatot ad vissza a következő példánykészletnek.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
func durable get-instances
Példányok lekérdezése szűrőkkel
Mi a teendő, ha nem igazán van szüksége az összes olyan információra, amelyet egy standard példány lekérdezése adhat meg? Mi a teendő például, ha csak a vezénylés létrehozási idejét vagy a vezénylési futtatókörnyezet állapotát keresi? Szűrők alkalmazásával szűkítheti a lekérdezést.
[FunctionName("QueryStatus")]
public static async Task Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
[DurableClient] IDurableOrchestrationClient client,
ILogger log)
{
// Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
var queryFilter = new OrchestrationStatusQueryCondition
{
RuntimeStatus = new[]
{
OrchestrationRuntimeStatus.Pending,
OrchestrationRuntimeStatus.Running,
},
CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
PageSize = 100,
};
OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
queryFilter,
CancellationToken.None);
foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
{
log.LogInformation(JsonConvert.SerializeObject(instance));
}
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Azure Functions Core Tools
Az Azure Functions Core Toolsban szűrőkkel is használhatja a durable get-instances
parancsot. A fent említett top
, , connection-string-setting
continuation-token
és task-hub-name
paraméterek mellett három szűrőparamétert (created-after
éscreated-before
runtime-status
) is használhat.
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A parancs paraméterei a durable get-instances
következők.
created-after
(nem kötelező): A dátum/idő (UTC) után létrehozott példányok lekérése. Elfogadott ISO 8601 formátumú dátum/idő.created-before
(nem kötelező): A dátum/idő (UTC) előtt létrehozott példányok lekérése. Elfogadott ISO 8601 formátumú dátum/idő.runtime-status
(nem kötelező): Egy adott állapotú példányok lekérése (például futtatás vagy befejezett). Több (szóközzel elválasztott) állapotot is megadhat.top
(nem kötelező): Kérésenként lekért példányok száma. Az alapértelmezett érték 10.continuation-token
(nem kötelező): A lekérendő példányok lapját vagy szakaszát jelző jogkivonat. Mindenget-instances
végrehajtás egy jogkivonatot ad vissza a következő példánykészletnek.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
Ha nem ad meg szűrőket (created-after
created-before
vagy runtime-status
), a parancs egyszerűen lekéri top
a példányokat, a futtatókörnyezet állapotára vagy a létrehozási időre való tekintet nélkül.
func durable get-instances --created-after 2021-03-10T13:57:31Z --created-before 2021-03-10T23:59Z --top 15
Példányok leállása
Ha olyan vezénylési példánya van, amely túl sokáig tart a futtatáshoz, vagy csak le kell állítania, mielőtt bármilyen okból befejeződik, megszakíthatja azt.
A megszakítási API két paramétere egy példányazonosító és egy oksztring, amelyeket a rendszer naplókba és a példány állapotára ír.
[FunctionName("TerminateInstance")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("terminate-queue")] string instanceId)
{
string reason = "Found a bug";
return client.TerminateAsync(instanceId, reason);
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
A leállított példányok végül átállnak az állapotra Terminated
. Ez az áttűnés azonban nem történik meg azonnal. A leállítási művelet inkább a feladatközpontban lesz várólistára állítva az adott példány egyéb műveleteivel együtt. A példány lekérdezési API-kkal megtudhatja, hogy egy leállított példány mikor érte el ténylegesen az állapototTerminated
.
Feljegyzés
A példánymegszüntetés jelenleg nem propagálja. A tevékenységfüggvények és az alvezénylések befejeződnek, függetlenül attól, hogy leállította-e az őket meghívó vezénylési példányt.
Példányok felfüggesztése és folytatása
A vezénylés felfüggesztése lehetővé teszi a futó vezénylés leállítását. A felmondással ellentétben lehetősége van egy felfüggesztett vezénylőt egy későbbi időpontban folytatni.
A felfüggesztési API két paramétere egy példányazonosító és egy oksztring, amelyeket a rendszer naplókba és a példány állapotára ír.
[FunctionName("SuspendResumeInstance")]
public static async Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("suspend-resume-queue")] string instanceId)
{
string suspendReason = "Need to pause workflow";
await client.SuspendAsync(instanceId, suspendReason);
// Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.
DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
await context.CreateTimer(dueTime, CancellationToken.None);
string resumeReason = "Continue workflow";
await client.ResumeAsync(instanceId, resumeReason);
}
A felfüggesztett példányok végül átállnak az állapotra Suspended
. Ez az áttűnés azonban nem történik meg azonnal. Ehelyett a felfüggesztési művelet várólistára kerül a feladatközpontban az adott példány egyéb műveleteivel együtt. A példány lekérdezési API-kkal megtudhatja, hogy egy futó példány ténylegesen elérte-e a felfüggesztett állapotot.
A felfüggesztett vezénylő folytatásakor az állapota visszavált a következőre Running
: .
Azure Functions Core Tools
A vezénylési példányokat közvetlenül is megszüntetheti a func durable terminate
Core Tools parancsával .
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable terminate
parancs a következő paramétereket használja:
id
(kötelező): A megszakítandó vezénylési példány azonosítója.reason
(nem kötelező): A felmondás oka.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
A következő parancs 0ab8c55a666644d68a3a8b220b12d209c azonosítójú vezénylési példányt szüntet meg:
func durable terminate --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Found a bug"
Események küldése példányokra
Bizonyos esetekben a vezénylő függvényeknek várniuk kell és figyelnie kell a külső eseményeket. Példák azokra a forgatókönyvekre, amelyekben ez hasznos, például a monitorozási és az emberi interakciós forgatókönyvek.
Eseményértesítéseket küldhet a futó példányoknak a vezénylési ügyfél eseménybevonási API-jának használatával. A vezénylések meghallgathatják és megválaszolhatják ezeket az eseményeket a külső eseményvezénylő API várakozásával.
A emelési esemény paraméterei a következők:
- Példányazonosító: A példány egyedi azonosítója.
- Esemény neve: A küldendő esemény neve.
- Eseményadatok: JSON-szerializálható hasznos adat, amely a példánynak küldhető.
[FunctionName("RaiseEvent")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("event-queue")] string instanceId)
{
int[] eventData = new int[] { 1, 2, 3 };
return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Feljegyzés
Ha nincs vezénylési példány a megadott példányazonosítóval, a rendszer elveti az eseményüzenetet. Ha egy példány létezik, de még nem várja meg az eseményt, az esemény a példány állapotában lesz tárolva, amíg készen nem áll a fogadásra és a feldolgozásra.
Azure Functions Core Tools
Az eseményt közvetlenül is létrehozhatja egy vezénylési példányra a func durable raise-event
Core Tools parancsával .
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable raise-event
parancs a következő paramétereket használja:
id
(kötelező): A vezénylési példány azonosítója.event-name
: Az esemény neve.event-data
(nem kötelező): A vezénylési példánynak küldendő adatok. Ez lehet egy JSON-fájl elérési útja, vagy közvetlenül a parancssorban is megadhatja az adatokat.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett értékDurableFunctionsHub
. A durableTask:HubName használatával host.json is beállítható.
func durable raise-event --id 0ab8c55a66644d68a3a8b220b12d209c --event-name MyEvent --event-data @eventdata.json
func durable raise-event --id 1234567 --event-name MyOtherEvent --event-data 3
Várakozás a vezénylés befejezésére
Hosszú ideig futó vezénylések esetén érdemes várni, és lekérni egy vezénylés eredményét. Ezekben az esetekben hasznos lehet időtúllépési időszakot definiálni a vezénylésen. Ha túllépi az időtúllépést, a vezénylés állapotát kell visszaadni az eredmények helyett.
A "várakozás a befejezésre vagy az állapot-ellenőrzésre adott válasz létrehozása" API-val szinkron módon lekérheti a vezénylési példány tényleges kimenetét. Ez a metódus alapértelmezés szerint 10 másodperces alapértelmezett időtúllépéssel és 1 másodperces lekérdezési intervallummal rendelkezik.
Íme egy példa HTTP-trigger függvényre, amely bemutatja, hogyan használhatja ezt az API-t:
// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.
using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;
namespace VSSample
{
public static class HttpSyncStart
{
private const string Timeout = "timeout";
private const string RetryInterval = "retryInterval";
[FunctionName("HttpSyncStart")]
public static async Task<HttpResponseMessage> Run(
[HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
HttpRequestMessage req,
[DurableClient] IDurableOrchestrationClient starter,
string functionName,
ILogger log)
{
// Function input comes from the request content.
object eventData = await req.Content.ReadAsAsync<object>();
string instanceId = await starter.StartNewAsync(functionName, eventData);
log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
TimeSpan timeout = GetTimeSpan(req, Timeout) ?? TimeSpan.FromSeconds(30);
TimeSpan retryInterval = GetTimeSpan(req, RetryInterval) ?? TimeSpan.FromSeconds(1);
return await starter.WaitForCompletionOrCreateCheckStatusResponseAsync(
req,
instanceId,
timeout,
retryInterval);
}
private static TimeSpan? GetTimeSpan(HttpRequestMessage request, string queryParameterName)
{
string queryParameterStringValue = request.RequestUri.ParseQueryString()[queryParameterName];
if (string.IsNullOrEmpty(queryParameterStringValue))
{
return null;
}
return TimeSpan.FromSeconds(double.Parse(queryParameterStringValue));
}
}
}
Hívja meg a függvényt a következő sor használatával. Az időtúllépéshez 2 másodpercet, az újrapróbálkozási időközhöz pedig 0,5 másodpercet használjon:
curl -X POST "http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5"
Feljegyzés
A fenti cURL-parancs feltételezi, hogy rendelkezik a projektben elnevezett E1_HelloSequence
vezénylő függvénnyel. A HTTP-eseményindító függvény írása miatt lecserélheti a projektben lévő vezénylő függvények nevére.
A vezénylési példány válaszának lekéréséhez szükséges időtől függően két eset létezik:
- A vezénylési példányok a megadott időtúllépésen belül befejeződnek (ebben az esetben 2 másodperc), a válasz pedig a vezénylési példány tényleges kimenete, szinkron módon:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:14:29 GMT
Transfer-Encoding: chunked
[
"Hello Tokyo!",
"Hello Seattle!",
"Hello London!"
]
- A vezénylési példányok nem fejezhetők be a megadott időtúllépésen belül, és a VÁLASZ a HTTP API URL-felderítésében ismertetett alapértelmezett válasz:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked
{
"id": "d3b72dddefce4e758d92f4d411567177",
"sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
"statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
"terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
"suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
"resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}
Feljegyzés
A webhook URL-címeinek formátuma eltérhet attól függően, hogy az Azure Functions-gazdagép melyik verzióját futtatja. Az előző példa az Azure Functions 3.0-gazdagépre mutat.
HTTP-felügyeleti webhook URL-címek lekérése
Külső rendszer használatával figyelheti vagy vezénylésre állíthatja az eseményeket. A külső rendszerek a Webhook URL-címeinek használatával kommunikálhatnak a Durable Functions szolgáltatással, amelyek a HTTP API URL-felderítésben leírt alapértelmezett válasz részét képezik. A webhook URL-címei programozott módon is elérhetők a vezénylési ügyfélkötés használatával. A http-felügyeleti hasznos adatok létrehozása API-val egy szerializálható objektumot kaphat, amely ezeket a webhook URL-címeket tartalmazza.
A HTTP-felügyeleti hasznos adatok létrehozása API egy paramétert használ:
- Példányazonosító: A példány egyedi azonosítója.
A metódusok a következő sztringtulajdonságokkal rendelkező objektumot adnak vissza:
- Azonosító: A vezénylés példányazonosítója (a bemenettel
InstanceId
megegyezőnek kell lennie). - StatusQueryGetUri: A vezénylési példány állapot URL-címe.
- SendEventPostUri: A vezénylési példány "esemény létrehozása" URL-címe.
- TerminatePostUri: A vezénylési példány "megszakítás" URL-címe.
- PurgeHistoryDeleteUri: A vezénylési példány "törlési előzményei" URL-címe.
- suspendPostUri: A vezénylési példány "felfüggesztés" URL-címe.
- resumePostUri: A vezénylési példány "önéletrajz" URL-címe.
A függvények a megfelelő vezénylések eseményeinek monitorozásához vagy emeléséhez küldhetik az objektumok példányait külső rendszereknek, ahogyan az alábbi példákban is látható:
[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
[ActivityTrigger] IDurableActivityContext ctx,
[DurableClient] IDurableOrchestrationClient client,
[CosmosDB(
databaseName: "MonitorDB",
containerName: "HttpManagementPayloads",
Connection = "CosmosDBConnectionSetting")]out dynamic document)
{
HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);
// send the payload to Azure Cosmos DB
document = new { Payload = payload, id = ctx.InstanceId };
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében a helyett az attribútumot DurableClient
kell használnia OrchestrationClient
DurableActivityContext
, a paramétertípust IDurableOrchestrationClient
pedig a DurableOrchestrationClient
helyett.IDurableActivityContext
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Példányok visszatekerése (előzetes verzió)
Ha váratlan okból meghiúsul a vezénylés, az erre a célra létrehozott API-val visszatekerheti a példányt egy korábban kifogástalan állapotba.
Feljegyzés
Ez az API nem helyettesíti a megfelelő hibakezelési és újrapróbálkozési szabályzatokat. Inkább csak olyan esetekben használható, amikor a vezénylési példányok váratlan okokból meghiúsulnak. A nem Failed
(pl. , Running
, Pending
, Terminated
Completed
) állapotban lévő vezénylések nem "újrafelfedezhetők". A hibakezelési és újrapróbálkozési szabályzatokkal kapcsolatos további információkért tekintse meg a hibakezelési cikket.
A vezénylési RewindAsync
ügyfélkötés (.NET) vagy rewind
(JavaScript) metódusával visszaállíthatja a vezénylést a Futó állapotba. Ez a módszer a vezénylési hibát okozó tevékenység- vagy részvezénylés végrehajtási hibáit is újrafuttatja.
Tegyük fel például, hogy van egy munkafolyamata, amely emberi jóváhagyások sorozatát foglalja magában. Tegyük fel, hogy vannak olyan tevékenységfüggvények, amelyek értesítik valakit, hogy jóváhagyásra van szükség, és várja meg a valós idejű választ. Miután az összes jóváhagyási tevékenység kapott választ vagy időtúllépést, tegyük fel, hogy egy másik tevékenység meghiúsul egy alkalmazás helytelen konfigurációja, például egy érvénytelen adatbázis kapcsolati sztring miatt. Az eredmény egy vezénylési hiba a munkafolyamat mélyében. RewindAsync
A (.NET) vagy rewind
a (JavaScript) API-val az alkalmazás rendszergazdája kijavíthatja a konfigurációs hibát, és visszatekerheti a sikertelen vezénylést közvetlenül a hiba előtt. Az emberi beavatkozás egyik lépését sem kell újra jóváhagyni, és a vezénylés sikeresen befejeződhet.
Feljegyzés
A visszatekerés funkció nem támogatja a tartós időzítőket használó vezénylési példányok visszatekerését.
[FunctionName("RewindInstance")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("rewind-queue")] string instanceId)
{
string reason = "Orchestrator failed and needs to be revived.";
return client.RewindAsync(instanceId, reason);
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Azure Functions Core Tools
A vezénylési példányokat közvetlenül is visszatekerheti a func durable rewind
Core Tools parancsával .
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable rewind
parancs a következő paramétereket használja:
id
(kötelező): A vezénylési példány azonosítója.reason
(nem kötelező): A vezénylési példány visszatekerésének oka.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl feladatközpontjának nevét használja.
func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."
Példányelőzmények törlése
A vezényléshez társított összes adat eltávolításához törölheti a példányelőzményeket. Előfordulhat például, hogy törölni szeretné a befejezett példányhoz társított tárolási erőforrásokat. Ehhez használja a vezénylési ügyfél által definiált törlési példány API-t.
Ez az első példa bemutatja, hogyan törölhet egyetlen vezénylési példányt.
[FunctionName("PurgeInstanceHistory")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("purge-queue")] string instanceId)
{
return client.PurgeInstanceHistoryAsync(instanceId);
}
A következő példa egy időzítő által aktivált függvényt mutat be, amely törli a megadott időintervallum után befejezett összes vezénylési példány előzményeit. Ebben az esetben eltávolítja a 30 vagy több nappal ezelőtt befejezett összes példány adatait. Ez a példafüggvény naponta egyszer, UTC 12:00-kor lesz futtatva:
[FunctionName("PurgeInstanceHistory")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[TimerTrigger("0 0 12 * * *")] TimerInfo myTimer)
{
return client.PurgeInstanceHistoryAsync(
DateTime.MinValue,
DateTime.UtcNow.AddDays(-30),
new List<OrchestrationStatus>
{
OrchestrationStatus.Completed
});
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Feljegyzés
Ahhoz, hogy a törlési előzményművelet sikeres legyen, a célpéldány futtatókörnyezeti állapotának befejezettnek, megszakítottnak vagy sikertelennek kell lennie.
Azure Functions Core Tools
A vezénylési példányok előzményeit a func durable purge-history
Core Tools parancsával törölheti. Az előző szakaszban szereplő második C#-példához hasonlóan törli a megadott időintervallumban létrehozott összes vezénylési példány előzményeit. A kiürített példányokat futásidejű állapot szerint tovább szűrheti.
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable purge-history
parancs számos paramétert tartalmaz:
created-after
(nem kötelező): Törölje a dátum/idő (UTC) után létrehozott példányok előzményeit. Elfogadott ISO 8601 formátumú dátum/idő.created-before
(nem kötelező): Törölje a dátum/idő (UTC) előtt létrehozott példányok előzményeit. Elfogadott ISO 8601 formátumú dátum/idő.runtime-status
(nem kötelező): Törölje az adott állapotú példányok előzményeit (például fut vagy befejeződött). Több (szóközzel elválasztott) állapotot is megadhat.connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl feladatközpontjának nevét használja.
A következő parancs törli a 2021. november 14., 19:35 (UTC) időpontban létrehozott összes sikertelen példány előzményeit.
func durable purge-history --created-before 2021-11-14T19:35:00.0000000Z --runtime-status failed
Tevékenységközpont törlése
A Core Tools parancsával törölheti az func durable delete-task-hub
adott feladatközponthoz társított összes tárolási összetevőt, beleértve az Azure Storage-táblákat, az üzenetsorokat és a blobokat.
Feljegyzés
A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.
A durable delete-task-hub
parancs két paramétert tartalmaz:
connection-string-setting
(nem kötelező): A használni kívánt tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás neve. Az alapértelmezett értékAzureWebJobsStorage
.task-hub-name
(nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl feladatközpontjának nevét használja.
Az alábbi parancs törli a UserTest
feladatközponthoz társított összes Azure Storage-adatot.
func durable delete-task-hub --task-hub-name UserTest