Delen via


Exemplaren beheren in Durable Functions in Azure

Orkestraties in Durable Functions zijn langlopende functies met status die kunnen worden gestart, opgevraagd, onderbroken, hervat en beëindigd met behulp van ingebouwde beheer-API's. Verschillende andere beheer-API's voor exemplaren worden ook weergegeven door de Durable Functions-orchestration-clientbinding, zoals het verzenden van externe gebeurtenissen naar exemplaren, het opschonen van exemplaargeschiedenis, enzovoort. In dit artikel worden alle ondersteunde exemplaarbeheerbewerkingen beschreven.

Instanties starten

Met de methode start-new (of schedule-new) op de orchestratieclientbinding wordt een nieuwe orchestratie-instantie gestart. Intern schrijft deze methode een bericht via de Durable Functions-opslagprovider en retourneert deze. Dit bericht activeert asynchroon het begin van een orkestratiefunctie met de opgegeven naam.

De parameters voor het starten van een nieuwe orkestratie-instantie zijn als volgt:

  • Naam: de naam van de orchestratorfunctie die moet worden gepland.
  • Invoer: Alle JSON-serialiseerbare gegevens die als invoer moeten worden doorgegeven aan de orchestratorfunctie.
  • InstanceId: (Optie) De unieke ID van het exemplaar. Als u deze parameter niet opgeeft, gebruikt de methode een willekeurige id.

Aanbeveling

Gebruik waar mogelijk een willekeurige id voor de exemplaar-id. Willekeurige exemplaar-id's zorgen voor een gelijke verdeling van de belasting wanneer u orchestratorfuncties schaalt op meerdere VM's. De juiste tijd voor het gebruik van niet-willekeurige exemplaar-id's is wanneer de id afkomstig moet zijn van een externe bron of wanneer u het singleton orchestrator-patroon implementeert.

De volgende code is een voorbeeld van een functie die een nieuwe orkestratie-instantie start:

[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}'.");
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Azure Functions Core Tools

U kunt een exemplaar ook rechtstreeks starten met behulp van de func durable start-new opdracht in Core Tools, waarbij de volgende parameters worden gebruikt:

  • function-name (vereist): naam van de functie die moet worden gestart.
  • input (optioneel): invoer voor de functie, inline of via een JSON-bestand. Voor bestanden voegt u een voorvoegsel toe aan het pad naar het bestand met @, zoals @path/to/file.json.
  • id (optioneel): ID van de orkestratie-exemplaar. Als u deze parameter niet opgeeft, gebruikt de opdracht een willekeurige GUID.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. U kunt dit ook instellen in host.json met behulp van durableTask:HubName.

Opmerking

Core Tools-opdrachten gaan ervan uit dat u ze uitvoert vanuit de hoofdmap van een functie-app. Als u de connection-string-setting en task-hub-name parameters expliciet opgeeft, kunt u de opdrachten uitvoeren vanuit iedere map. Hoewel u deze opdrachten kunt uitvoeren zonder dat een functie-app-host wordt uitgevoerd, is het mogelijk dat u bepaalde effecten niet kunt observeren, tenzij de host wordt uitgevoerd. De start-new opdracht voert bijvoorbeeld een beginbericht uit in de doeltaakhub, maar de indeling wordt niet daadwerkelijk uitgevoerd, tenzij er een hostproces voor de functie-app wordt uitgevoerd dat het bericht kan verwerken.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

Met de volgende opdracht wordt de functie HelloWorld gestart en wordt de inhoud van het bestand aan het bestand counter-data.json doorgegeven:

func durable start-new --function-name HelloWorld --input @counter-data.json --task-hub-name TestTaskHub

Query-instanties

Nadat u nieuwe orkestratie-instanties hebt gestart, moet u waarschijnlijk een query uitvoeren op de runtimestatus om te bepalen of ze actief zijn, voltooid zijn of zijn mislukt.

Met de get-status methode op de orchestration-clientbinding wordt de status van een orchestratie-exemplaar opgevraagd.

Er wordt een instanceId (vereist), (optioneel) showHistoryshowHistoryOutput en showInput (optioneel) als parameters gebruikt.

  • showHistory: Als dit is ingesteld true, bevat het antwoord de uitvoeringsgeschiedenis.
  • showHistoryOutput: Indien ingesteld op true, bevat de uitvoeringsgeschiedenis activiteitsuitvoer.
  • showInput: Als deze optie is ingesteld false, bevat het antwoord niet de invoer van de functie. De standaardwaarde is true.

De methode retourneert een object met de volgende eigenschappen:

  • Naam: De naam van de orchestratorfunctie.
  • InstanceId: de instance ID van de orkestratie (moet hetzelfde zijn als de instanceId invoer).
  • CreatedTime: het tijdstip waarop de orchestratorfunctie is gestart.
  • LastUpdatedTime: het tijdstip waarop de indeling het laatst is gecontroleerd.
  • Invoer: De invoer van de functie als een JSON-waarde. Dit veld wordt niet ingevuld als showInput dit onwaar is.
  • CustomStatus: Aangepaste orkestratiestatus in JSON-formaat.
  • Uitvoer: De uitvoer van de functie als een JSON-waarde (als de functie is voltooid). Als de orchestratorfunctie is mislukt, bevat deze eigenschap de foutdetails. Als de orchestratorfunctie is onderbroken of beëindigd, bevat deze eigenschap de reden voor de schorsing of beëindiging (indien van toepassing).
  • RuntimeStatus: een van de volgende waarden:
    • In behandeling: de instantie is gepland, maar is nog niet begonnen.
    • Uitvoering: het exemplaar is gestart met uitvoeren.
    • Voltooid: het exemplaar is normaal voltooid.
    • ContinuedAsNew: Het exemplaar is opnieuw opgestart met een nieuwe geschiedenis. Deze status is een tijdelijke status.
    • Mislukt: het exemplaar is mislukt met een fout.
    • Beëindigd: het exemplaar is plotseling gestopt.
    • Opgeschort: De instantie is opgeschort en kan op een later tijdstip worden hervat.
  • Geschiedenis: De executiegeschiedenis van de orchestratie. Dit veld wordt alleen ingevuld als showHistory dit is ingesteld op true.

Opmerking

Een orchestrator wordt pas gemarkeerd als Completed wanneer alle geplande taken zijn voltooid en de orchestrator is teruggekeerd. Met andere woorden, het is niet voldoende voor een orchestrator om zijn return verklaring te bereiken zodat deze wordt gemarkeerd als Completed. Dit is met name relevant voor gevallen waarin WhenAny wordt gebruikt; vaak handelen deze orchestrators return voordat alle geplande taken zijn uitgevoerd.

Deze methode retourneert null (.NET en Java), undefined (JavaScript) of None (Python) als het exemplaar niet bestaat.

[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.
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Azure Functions Core Tools

Het is ook mogelijk om de status van een orkestratie-instantie rechtstreeks op te halen met behulp van de func durable get-runtime-status opdracht in Core Tools.

Opmerking

Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable get-runtime-status opdracht gebruikt de volgende parameters:

  • id (vereist): id van het orchestration-exemplaar.
  • show-input (optioneel): indien ingesteld trueop, bevat het antwoord de invoer van de functie. De standaardwaarde is false.
  • show-output (optioneel): indien ingesteld trueop, bevat het antwoord de uitvoer van de functie. De standaardwaarde is false.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.

Met de volgende opdracht wordt de status (inclusief invoer en uitvoer) van een exemplaar opgehaald met een orkestratie-exemplaar-id van 0ab8c55a66644d68a3a8b220b12d209c. Hierbij wordt ervan uitgegaan dat u de func opdracht uitvoert vanuit de hoofdmap van de functie-app:

func durable get-runtime-status --id 0ab8c55a66644d68a3a8b220b12d209c --show-input true --show-output true

U kunt de durable get-history opdracht gebruiken om de geschiedenis van een orchestration-exemplaar op te halen. Hiervoor worden de volgende parameters gebruikt:

  • id (vereist): id van het orchestration-exemplaar.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.
func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Query uitvoeren op alle instanties

U kunt API's in uw SDK voor de programmeertaal gebruiken om de statussen van alle orchestration instances in uw task hub op te vragen. Deze API 'list-instances' of 'get-status' retourneert een lijst met objecten die de orchestration-exemplaren vertegenwoordigen die overeenkomen met de queryparameters.

[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.
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Azure Functions Core Tools

Het is ook mogelijk om rechtstreeks query's uit te voeren op exemplaren met behulp van de func durable get-instances opdracht in Core Tools.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable get-instances opdracht gebruikt de volgende parameters:

  • top (optioneel): deze opdracht ondersteunt paging. Deze parameter komt overeen met het aantal exemplaren dat per aanvraag is opgehaald. De standaardwaarde is 10.
  • continuation-token (optioneel): Een token om aan te geven welke pagina of sectie van exemplaren moet worden opgehaald. Elke get-instances uitvoering retourneert een token naar de volgende set exemplaren.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.
func durable get-instances

Query-exemplaren met filters

Stel dat u niet alle informatie nodig hebt die een standaard instance query kan bieden? Wat als u bijvoorbeeld alleen op zoek bent naar de aanmaaktijd van de orchestratie of de runtimestatus van de orchestratie? U kunt uw query beperken door filters toe te passen.

[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));
    }
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Azure Functions Core Tools

In de Azure Functions Core Tools kunt u ook de durable get-instances opdracht met filters gebruiken. Naast de bovenstaande top, continuation-token, en connection-string-settingtask-hub-name parameters kunt u drie filterparameters (created-after, created-beforeen ) runtime-statusgebruiken.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

Hier volgen de parameters voor de durable get-instances opdracht.

  • created-after (optioneel): haal de exemplaren op die na deze datum/tijd (UTC) zijn gemaakt. ISO 8601-geformatteerde data/tijden zijn geaccepteerd.
  • created-before (optioneel): haal de exemplaren op die vóór deze datum/tijd (UTC) zijn gemaakt. ISO 8601 opgemaakte datum/tijden geaccepteerd.
  • runtime-status (optioneel): haal de exemplaren op met een bepaalde status (bijvoorbeeld actief of voltooid). Kan meerdere (door spaties gescheiden) statussen bieden.
  • top (optioneel): het aantal exemplaren dat per aanvraag worden opgehaald. De standaardwaarde is 10.
  • continuation-token (optioneel): Een token om aan te geven welke pagina of sectie van exemplaren moet worden opgehaald. Elke get-instances uitvoering retourneert een token naar de volgende set exemplaren.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.

Als u geen filters (created-after, created-before, of runtime-status) opgeeft, haalt de opdracht eenvoudig top-exemplaren op, zonder rekening te houden met de runtimestatus of de aanmaaktijd.

func durable get-instances --created-after 2021-03-10T13:57:31Z --created-before  2021-03-10T23:59Z --top 15

Instances beëindigen

Als u een orchestratie-exemplaar hebt dat te lang duurt om uit te voeren, of als u het om welke reden dan ook moet stoppen voordat het voltooid is, kunt u het beëindigen.

De twee parameters voor de beëindigings-API zijn een exemplaar-id en een redentekenreeks die naar logboeken en de status van het exemplaar wordt geschreven.

[FunctionName("TerminateInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("terminate-queue")] string instanceId)
{
    string reason = "Found a bug";
    return client.TerminateAsync(instanceId, reason);
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Een beëindigd exemplaar verandert uiteindelijk in de Terminated status. Deze overgang vindt echter niet onmiddellijk plaats. In plaats daarvan wordt de beëindigingsbewerking samen met andere bewerkingen voor dat exemplaar in de taakhub in de wachtrij geplaatst. U kunt de instancequery API gebruiken om te bepalen wanneer een beëindigd exemplaar de Terminated status daadwerkelijk heeft bereikt.

Opmerking

De beëindiging van de instance wordt momenteel niet doorgegeven. Activiteitsfuncties en suborkestraties worden uitgevoerd tot ze voltooid zijn, ongeacht of u het orkestratie-exemplaar dat ze heeft aangeroepen, hebt beëindigd.

Instanties onderbreken en hervatten

Door een orkestratie te onderbreken, kunt u een actieve orkestratie stoppen. In tegenstelling tot beëindiging, hebt u de mogelijkheid om een onderbroken orchestrator op een later tijdstip te hervatten.

De twee parameters voor de Suspend API zijn een instance-id en een redenstring, die in de logboeken en de status van de instance worden opgenomen.

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

Een onderbroken instantie wordt uiteindelijk overgezet naar de Suspended status. Deze overgang vindt echter niet onmiddellijk plaats. In plaats daarvan wordt de onderbrekingsbewerking in de wachtrij geplaatst in de taakhub, samen met andere bewerkingen voor dat exemplaar. U kunt de query-API's van het draaiend exemplaar gebruiken om te bepalen wanneer een draaiend exemplaar daadwerkelijk de status Onderbroken heeft bereikt.

Wanneer een gepauzeerde orchestrator wordt hervat, wordt de status hersteld naar Running.

Azure Functions Core Tools

U kunt een orkestratie-instantie ook rechtstreeks beëindigen met behulp van de func durable terminate opdracht in Core Tools.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable terminate opdracht gebruikt de volgende parameters:

  • id (vereist): id van het orchestration-exemplaar dat moet worden beëindigd.
  • reason (optioneel): reden voor beëindiging.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.

Met de volgende opdracht wordt een orkestratie-instantie beëindigd met een ID van 0ab8c55a66644d68a3a8b220b12d209c:

func durable terminate --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Found a bug"

Gebeurtenissen verzenden naar instanties

In sommige scenario's moeten orchestratorfuncties wachten en luisteren naar externe gebeurtenissen. Voorbeelden van scenario's waarbij dit nuttig is, zijn onder andere de bewakings - en menselijke interactiescenario's .

U kunt gebeurtenismeldingen verzenden naar lopende exemplaren met behulp van de API raise event van de orchestratie-client. Orchestrations kunnen luisteren naar en reageren op deze gebeurtenissen met behulp van de wacht op externe gebeurtenis orchestrator-API.

De parameters voor het genereren van gebeurtenissen zijn als volgt:

  • Exemplaar-id: de unieke id van het exemplaar.
  • Gebeurtenisnaam: de naam van de gebeurtenis die moet worden verzonden.
  • Gebeurtenisgegevens: een JSON-serialiseerbare payload die naar het exemplaar moet worden verzonden.
[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);
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Opmerking

Als er geen orkestratie-exemplaar is met de opgegeven exemplaar-id, wordt het gebeurtenisbericht verworpen. Als een exemplaar bestaat, maar nog niet op de gebeurtenis wacht, wordt de gebeurtenis opgeslagen in de instantiestatus totdat deze gereed is om te worden ontvangen en verwerkt.

Azure Functions Core Tools

U kunt rechtstreeks een gebeurtenis naar een orkestratie-exemplaar genereren door de func durable raise-event opdracht in Core Tools te gebruiken.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable raise-event opdracht gebruikt de volgende parameters:

  • id (vereist): id van het orchestration-exemplaar.
  • event-name: Naam van de gebeurtenis die moet worden opgeroepen.
  • event-data (optioneel): gegevens die naar de orkestratie-instantie moeten worden verzonden. Dit kan het pad naar een JSON-bestand zijn of u kunt de gegevens rechtstreeks op de opdrachtregel opgeven.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. De standaardwaarde is DurableFunctionsHub. Het kan ook worden ingesteld in host.json, met behulp van durableTask:HubName.
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

Wachten tot de orkestratie is voltooid

In langlopende orkestraties wilt u misschien wachten en de resultaten van een orkestratie ophalen. In deze gevallen is het ook handig om een time-outperiode voor de orkestratie te definiëren. Als de time-out wordt overschreden, moet de status van de indeling worden geretourneerd in plaats van de resultaten.

De 'wacht op voltooiing of creëer controlestatusantwoord' API kan synchroon worden gebruikt om de werkelijke uitvoer van een orchestratie-instance op te halen. Deze methode heeft standaard een standaardtime-out van 10 seconden en een polling-interval van 1 seconde.

Hier volgt een voorbeeld van een HTTP-triggerfunctie die laat zien hoe u deze API gebruikt:

// 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));
        }
    }
}

Roep de functie aan met de volgende regel. Gebruik 2 seconden voor de time-out en 0,5 seconde voor het interval voor opnieuw proberen:

curl -X POST "http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5"

Opmerking

Bij de bovenstaande cURL-opdracht wordt ervan uitgegaan dat u een orchestratorfunctie hebt met de naam E1_HelloSequence in uw project. Vanwege de manier waarop de HTTP-triggerfunctie is geschreven, kunt u deze vervangen door de naam van elke orchestratorfunctie in uw project.

Afhankelijk van de tijd die nodig is om het antwoord van de orchestratie-instantie te verkrijgen, zijn er twee gevallen:

  • De orkestratie-instanties zijn voltooid binnen de gedefinieerde time-out (in dit geval 2 seconden) en het antwoord is de daadwerkelijke uitvoer van de orkestratie-instantie, die synchroon wordt geleverd.
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!"
]
  • De orchestratie-exemplaren kunnen niet worden voltooid binnen de gedefinieerde time-out en het antwoord is het standaardantwoord dat wordt beschreven in HTTP API URL-detectie:
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}"
}

Opmerking

De indeling van de webhook-URL's kan verschillen, afhankelijk van de versie van de Azure Functions-host die u uitvoert. Het voorgaande voorbeeld is voor de Azure Functions 3.0-host.

URL's voor HTTP-beheerwebhook ophalen

U kunt een extern systeem gebruiken om gebeurtenissen te bewaken of te genereren voor een orkestratie. Externe systemen kunnen communiceren met Durable Functions via de webhook-URL's die deel uitmaken van het standaardantwoord dat wordt beschreven in HTTP API-URL-detectie. De webhook-URL's kunnen ook programmatisch worden geopend met behulp van de orchestration-clientbinding. De API voor het aanmaken van HTTP-beheerpayloads kan worden gebruikt om een serialiseerbaar object te verkrijgen dat deze webhook-URL's bevat.

De PAYLOAD-API voor HTTP-beheer maken heeft één parameter:

  • Exemplaar-id: de unieke id van het exemplaar.

De methoden retourneren een object met de volgende tekenreekseigenschappen:

  • Id: De instantie-id van de orkestratie (moet hetzelfde zijn als de InstanceId invoer).
  • StatusQueryGetUri: de status-URL van het orkestratie-exemplaar.
  • SendEventPostUri: de URL voor het triggeren van een evenement van de orkestratie-instantie.
  • TerminatePostUri: de 'beëindigen'-URL van de orkestratie-instance.
  • PurgeHistoryDeleteUri: De URL 'geschiedenis opschonen' van het orkestratie-exemplaar.
  • suspendPostUri: de "suspend"-URL van de orchestratie-instantie.
  • resumePostUri: de URL "resume" van het orchestratie-exemplaar.

Functies kunnen exemplaren van deze objecten verzenden naar externe systemen om gebeurtenissen in de bijbehorende indelingen te bewaken of te genereren, zoals wordt weergegeven in de volgende voorbeelden:

[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 };
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u DurableActivityContext gebruiken in plaats van IDurableActivityContext, moet u het OrchestrationClient kenmerk gebruiken in plaats van het DurableClient kenmerk, en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Instanties terugspoelen (preview)

Als u om een onverwachte reden een orkestratiefout hebt, kunt u het exemplaar terugspoelen naar een eerder gezonde staat met behulp van een API die voor dat doel is gebouwd.

Opmerking

Deze API is niet bedoeld als vervanging voor de juiste foutafhandeling en beleid voor opnieuw proberen. In plaats daarvan is het bedoeld om alleen te worden gebruikt in gevallen waarin orchestratie-instanties om onverwachte redenen falen. Orchestrationen in andere statussen dan Failed (bijvoorbeeld Running, Pending, Terminated, Completed) kunnen niet "teruggedraaid" worden. Zie het artikel Foutafhandeling voor meer informatie over foutafhandeling en beleid voor opnieuw proberen.

Gebruik de RewindAsync methode (.NET) of rewind (JavaScript) van de orchestrationclientbinding om de orchestratie weer in de status 'Running' te plaatsen. Met deze methode worden ook de uitvoeringsfouten van de activiteit of sub-orkestratie opnieuw uitgevoerd die de orkestratiefout hebben veroorzaakt.

Stel dat u een werkstroom hebt met een reeks menselijke goedkeuringen. Stel dat er een reeks activiteitsfuncties zijn die iemand op de hoogte stellen dat hun goedkeuring nodig is en wachten op het realtime-antwoord. Nadat alle goedkeuringsactiviteiten antwoorden hebben ontvangen of een time-out hebben opgetreden, moet u aannemen dat een andere activiteit mislukt vanwege een onjuiste configuratie van een toepassing, zoals een ongeldige databaseverbindingsreeks. Het resultaat is een orkestratiefout diep in de workflow. Met de RewindAsync (.NET) of rewind (JavaScript)-API kan een toepassingsbeheerder de configuratiefout oplossen en de mislukte indeling terugspoelen naar de status direct vóór de fout. Geen van de stappen voor menselijke interactie hoeft opnieuw te worden goedgekeurd en de orkestratie kan nu succesvol worden voltooid.

Opmerking

De functie voor terugspoelen biedt geen ondersteuning voor het terugspoelen van orchestratie-instanties die duurzame timers gebruiken.

[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);
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Azure Functions Core Tools

U kunt een orkestratie-instantie ook rechtstreeks herstellen met behulp van de func durable rewind opdracht in Core Tools.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable rewind opdracht gebruikt de volgende parameters:

  • id (vereist): id van het orchestration-exemplaar.
  • reason (optioneel): reden voor het opnieuw starten van de orkestratie-instantie.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. Standaard wordt de naam van de taakhub in het host.json-bestand gebruikt.
func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

Instantiegeschiedenis leegmaken

Om alle gegevens te verwijderen die zijn gekoppeld aan een orkestratie, kunt u de exemplaargeschiedenis opschonen. U kunt bijvoorbeeld alle opslagbronnen verwijderen die zijn gekoppeld aan een voltooid exemplaar. Gebruik hiervoor de API voor het verwijderen van exemplaren, zoals gedefinieerd door de orchestratieclient.

In dit eerste voorbeeld ziet u hoe u één orchestratie-exemplaar kunt verwijderen.

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("purge-queue")] string instanceId)
{
    return client.PurgeInstanceHistoryAsync(instanceId);
}

In het volgende voorbeeld ziet u een timer-geactiveerde functie waarmee de geschiedenis wordt opgeschoond voor alle orchestratie-exemplaren die zijn voltooid na het opgegeven tijdsinterval. In dit geval worden gegevens verwijderd voor alle exemplaren die 30 of meer dagen geleden zijn voltooid. Deze voorbeeldfunctie wordt gepland om één keer per dag uit te voeren, om 12:00 UUR UTC:

[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
        });
}

Opmerking

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u het kenmerk gebruiken OrchestrationClient in plaats van het DurableClient kenmerk en moet u het DurableOrchestrationClient parametertype gebruiken in plaats van IDurableOrchestrationClient. Zie het artikel Over Durable Functions-versies voor meer informatie over de verschillen tussen versies.

Opmerking

De runtimestatus van het doelexemplaar moet voltooid, beëindigd of mislukt zijn om de bewerking voor het opschonen van de geschiedenis te laten slagen.

Azure Functions Core Tools

U kunt de geschiedenis van een orchestration-exemplaar opschonen met behulp van de func durable purge-history opdracht in Core Tools. Net als in het tweede C#-voorbeeld in de vorige sectie, wordt de geschiedenis gewist voor alle orkestratie-instanties die zijn gemaakt tijdens een opgegeven tijdsinterval. U kunt opgeschoonde exemplaren verder filteren op runtimestatus.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable purge-history opdracht heeft verschillende parameters:

  • created-after (optioneel): verwijder de geschiedenis van exemplaren die na deze datum/tijd (UTC) zijn gemaakt. ISO 8601 opgemaakte datum/tijden geaccepteerd.
  • created-before (optioneel): verwijder de geschiedenis van exemplaren die vóór deze datum/tijd (UTC) zijn gemaakt. ISO 8601 opgemaakte datum/tijden geaccepteerd.
  • runtime-status (optioneel): verwijder de geschiedenis van exemplaren met een bepaalde status (bijvoorbeeld actief of voltooid). Kan meerdere (door spaties gescheiden) statussen bieden.
  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. Standaard wordt de naam van de taakhub in het host.json-bestand gebruikt.

Met de volgende opdracht verwijdert u de geschiedenis van alle mislukte exemplaren die zijn gemaakt vóór 14 november 2021 om 17:35 uur (UTC).

func durable purge-history --created-before 2021-11-14T19:35:00.0000000Z --runtime-status failed

Een taakhub verwijderen

Met behulp van de func durable delete-task-hub opdracht in Core Tools kunt u alle opslagartefacten verwijderen die zijn gekoppeld aan een bepaalde taakhub, waaronder Azure-opslagtabellen, wachtrijen en blobs.

Opmerking

De Core Tools-opdrachten worden momenteel alleen ondersteund wanneer u de standaard Azure Storage-provider gebruikt om de runtimestatus te behouden.

De durable delete-task-hub opdracht heeft twee parameters:

  • connection-string-setting (optioneel): naam van de toepassingsinstelling die de opslagverbindingsreeks bevat die moet worden gebruikt. De standaardwaarde is AzureWebJobsStorage.
  • task-hub-name (optioneel): naam van de Durable Functions-taakhub die moet worden gebruikt. Standaard wordt de naam van de taakhub in het host.json-bestand gebruikt.

Met de volgende opdracht worden alle Azure-opslaggegevens verwijderd die zijn gekoppeld aan de UserTest taakhub.

func durable delete-task-hub --task-hub-name UserTest

Volgende stappen