Exemplaren beheren in Durable Functions in Azure

Indelingen in Durable Functions zijn langlopende stateful functies 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.

Exemplaren starten

Met de methode start-new (of schedule-new) op de orchestration-clientbinding wordt een nieuw indelingsexemplaar gestart. Intern schrijft deze methode een bericht via de Durable Functions-opslagprovider en retourneert deze. Dit bericht activeert asynchroon het begin van een indelingsfunctie met de opgegeven naam.

De parameters voor het starten van een nieuw indelingsexemplaar 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: (optioneel) De unieke id van het exemplaar. Als u deze parameter niet opgeeft, gebruikt de methode een willekeurige id.

Tip

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 voorbeeldfunctie waarmee een nieuw indelingsexemplaar wordt gestart:

C#

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

Notitie

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.

JavaScript

Tenzij anders opgegeven, gebruiken de voorbeelden op deze pagina de HTTP-trigger met de volgende function.json.

function.json

{
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Notitie

Dit voorbeeld is gericht op Durable Functions versie 2.x. Gebruik in versie 1.x orchestrationClient in plaats van durableClient.

index.js

const df = require("durable-functions");

module.exports = async function(context, input) {
    const client = df.getClient(context);

    const instanceId = await client.startNew("HelloWorld", undefined, input);
    context.log(`Started orchestration with ID = ${instanceId}.`);
};

Python

Tenzij anders opgegeven, gebruiken de voorbeelden op deze pagina de HTTP-trigger met de volgende function.json.

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [    
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Notitie

Dit voorbeeld is gericht op Durable Functions versie 2.x. Gebruik in versie 1.x orchestrationClient in plaats van durableClient.

__init__.py

import logging
import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    
    instance_id = await client.start_new('HelloWorld', None, None)
    logging.log(f"Started orchestration with ID = ${instance_id}.")

PowerShell

Tenzij anders opgegeven, gebruiken de voorbeelden op deze pagina de HTTP-trigger met de volgende function.json.

function.json

{
  "bindings": [    
    {
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "Response",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Notitie

Dit voorbeeld is gericht op Durable Functions versie 2.x. Gebruik in versie 1.x orchestrationClient in plaats van durableClient.

run.ps1

param($Request, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld'
Write-Host "Started orchestration with ID = '$InstanceId'"

Java

@FunctionName("HelloWorldQueueTrigger")
public void helloWorldQueueTrigger(
        @QueueTrigger(name = "input", queueName = "start-queue", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    String instanceID = client.scheduleNewOrchestrationInstance("HelloWorld");
    context.getLogger().info("Scheduled orchestration with ID = " + instanceID);
}

Als u wilt wachten totdat de orchestrator begint voordat u terugkeert vanuit uw functie, kunt u ook de waitForInstanceStart() methode gebruiken.

// wait up to 30 seconds for the scheduled orchestration to enter the "Running" state
client.waitForInstanceStart(instanceID, Duration.ofSeconds(30));

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 het orchestration-exemplaar. Als u deze parameter niet opgeeft, gebruikt de opdracht een willekeurige GUID.
• connection-string-setting(optioneel): naam van de toepassingsinstelling met de opslag verbindingsreeks die u wilt gebruiken. 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.

Notitie

Core Tools-opdrachten gaan ervan uit dat u ze uitvoert vanuit de hoofdmap van een functie-app. Als u de en task-hub-name parameters expliciet opgeeftconnection-string-setting, kunt u de opdrachten uitvoeren vanuit elke 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.

Notitie

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-exemplaren

Nadat u nieuwe indelingsexemplaren hebt gestart, moet u waarschijnlijk een query uitvoeren op de runtimestatus om te zien of ze worden uitgevoerd, zijn voltooid of zijn mislukt.

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

Er wordt een instanceId (vereist), (optioneel) showHistory showHistoryOutput 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 exemplaar-id van de indeling (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 indelingsstatus in JSON-indeling.
• 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: het exemplaar is gepland, maar is nog niet gestart.
  • Wordt uitgevoerd: het exemplaar is gestart.
  • Voltooid: het exemplaar is normaal voltooid.
  • ContinueAsNew: 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.
  • Onderbroken: het exemplaar is onderbroken en kan later worden hervat.
• Geschiedenis: De uitvoeringsgeschiedenis van de indeling. Dit veld wordt alleen ingevuld als showHistory dit is ingesteld op true.

Notitie

Een orchestrator wordt pas gemarkeerd als Completed wanneer alle geplande taken zijn voltooid en de orchestrator is geretourneerd. 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; deze orchestrators vaak return voordat alle geplande taken zijn uitgevoerd.

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

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const status = await client.getStatus(instanceId);
    // do something based on the current status.
    // example: if status.runtimeStatus === df.OrchestrationRuntimeStatus.Running: ...
}

Zie Start-exemplaren voor de function.json-configuratie.

Python

import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    status = await client.get_status(instance_id)
    # do something based on the current status
    # example: if (existing_instance.runtime_status is df.OrchestrationRuntimeStatus.Running) { ...

PowerShell

param($Request, $TriggerMetadata)

# Get instanceid from body
$InstanceId = $Request.Body.InstanceId

$Status = Get-DurableStatus -InstanceId $InstanceId -ShowHistory -ShowHistoryOutput -ShowInput
Write-Host "Status: $($Status | ConvertTo-Json)"

# Do something based on status
# example: if ($Status.runtimeStatus -eq 'Running') { ... }

Java

@FunctionName("GetStatus")
public void getStatus(
        @QueueTrigger(name = "instanceID", queueName = "check-status-queue", connection = "Storage") String instanceID,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    OrchestrationMetadata metadata = client.getInstanceMetadata(instanceID, false);
    if (metadata != null) {
        OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
        switch (status) {
            // do something based on the current status
        }
    }
}

Azure Functions Core Tools

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

Notitie

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 met de opslag verbindingsreeks die u wilt gebruiken. 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 indelingsexemplaar-id van 0ab8c55a6644d68a3a8b220b12d209c. 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 met de opslag verbindingsreeks die u wilt gebruiken. 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's uitvoeren op alle exemplaren

U kunt API's in uw taal-SDK gebruiken om een query uit te voeren op de statussen van alle indelingsexemplaren in uw taakhub. Deze API 'list-instances' of 'get-status' retourneert een lijst met objecten die de orchestration-exemplaren vertegenwoordigen die overeenkomen met de queryparameters.

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const instances = await client.getStatusAll();
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import logging
import json
import azure.functions as func
import azure.durable_functions as df


async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    instances = await client.get_status_all()

    for instance in instances:
        logging.log(json.dumps(instance))

Zie Start-exemplaren voor de function.json-configuratie.

PowerShell

Notitie

Deze functie wordt momenteel niet ondersteund in PowerShell, maar kan worden bereikt met behulp van de HTTP-API van Durable Functions.

Java

@FunctionName("GetAllStatus")
public String getAllStatus(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery noFilter = new OrchestrationStatusQuery();
    OrchestrationStatusQueryResult result = client.queryInstances(noFilter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

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.

Notitie

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 met de opslag verbindingsreeks die u wilt gebruiken. 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

Wat gebeurt er als u niet alle informatie nodig hebt die een standaardexemplarenquery kan bieden? Wat gebeurt er bijvoorbeeld als u alleen op zoek bent naar de aanmaaktijd van de orchestration of de runtimestatus van de orchestration? U kunt uw query beperken door filters toe te passen.

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const runtimeStatus = [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Running,
    ];
    const instances = await client.getStatusBy(
        new Date(2021, 3, 10, 10, 1, 0),
        new Date(2021, 3, 10, 10, 23, 59),
        runtimeStatus
    );
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import logging
from datetime import datetime
import json
import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.OrchestrationRuntimeStatus import OrchestrationRuntimeStatus

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

    instances = await client.get_status_by(
        datetime(2021, 3, 10, 10, 1, 0),
        datetime(2021, 3, 10, 10, 23, 59),
        runtime_status
    )

    for instance in instances:
        logging.log(json.dumps(instance))

PowerShell

Notitie

Deze functie wordt momenteel niet ondersteund in PowerShell, maar kan worden bereikt met behulp van de HTTP-API van Durable Functions.

Java

@FunctionName("GetRunningInstances")
public String getRunningInstances(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery filter = new OrchestrationStatusQuery()
        .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.PENDING, OrchestrationRuntimeStatus.RUNNING))
        .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(7)))
        .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(1)));
    OrchestrationStatusQueryResult result = client.queryInstances(filter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

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.

Notitie

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 opgemaakte datum/tijd geaccepteerd.
• created-before (optioneel): haal de exemplaren op die vóór deze datum/tijd (UTC) zijn gemaakt. Iso 8601 opgemaakte datum/tijd 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 instanties 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 met de opslag verbindingsreeks die u wilt gebruiken. 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-beforeof runtime-status) opgeeft, haalt de opdracht eenvoudig exemplaren op top , 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

Exemplaren beëindigen

Als u een indelingsexemplaar hebt dat te lang duurt om uit te voeren, of u hoeft deze alleen te stoppen voordat het om welke reden dan ook is voltooid, 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.

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Found a bug";
    return client.terminate(instanceId, reason);
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    reason = "Found a bug"
    return await client.terminate(instance_id, reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$Reason = 'Found a bug'

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Java

@FunctionName("TerminateInstance")
public void terminateInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String reason = "Found a bug";
    durableContext.getClient().terminate(instanceID, reason);
}

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

Notitie

De beëindiging van het exemplaar wordt momenteel niet doorgegeven. Activiteitsfuncties en subindelingen worden uitgevoerd tot voltooiing, ongeacht of u het indelingsexemplaar met de naam ervan hebt beëindigd.

Instanties onderbreken en hervatten

Als u een indeling onderbreekt, kunt u een actieve indeling 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 exemplaar-id en een redentekenreeks, die naar logboeken en de status van het exemplaar worden geschreven.

C#

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

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const suspendReason = "Need to pause workflow";
    await client.suspend(instanceId, suspendReason);

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.  
    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ seconds: 30 });
    yield context.df.createTimer(deadline.toJSDate());

    const resumeReason = "Continue workflow";
    await client.resume(instanceId, resumeReason);
};

Python

import azure.functions as func
import azure.durable_functions as df
from datetime import timedelta

async def main(req: func.HttpRequest, starter: str, instance_id: str):
    client = df.DurableOrchestrationClient(starter)

    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    due_time = context.current_utc_datetime + timedelta(seconds=30)
    yield context.create_timer(due_time)

    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$SuspendReason = 'Need to pause workflow'

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.
$duration = New-TimeSpan -Seconds 30
Start-DurableTimer -Duration $duration

$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

Java

@FunctionName("SuspendResumeInstance")
public void suspendResumeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    DurableTaskClient client = durableContext.getClient();  
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    ctx.createTimer(Duration.ofSeconds(30)).await();

    String resumeReason = "Continue workflow";
    client.getClient().resumeInstance(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 exemplaar gebruiken om te weten wanneer een actief exemplaar de status Onderbroken heeft bereikt.

Wanneer een onderbroken orchestrator wordt hervat, wordt de status weer gewijzigd in Running.

Azure Functions Core Tools

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

Notitie

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 met de opslag verbindingsreeks die u wilt gebruiken. 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 indelingsexemplaar beëindigd met een id van 0ab8c55a66644d68a3a8b220b12d209c:

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

Gebeurtenissen verzenden naar exemplaren

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 actieve exemplaren met behulp van de gebeurtenis-API genereren van de orchestration-client. Orchestrations kunnen luisteren naar en reageren op deze gebeurtenissen met behulp van de wacht op de orchestrator-API voor externe gebeurtenissen .

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 nettolading die naar het exemplaar moet worden verzonden.

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const eventData = [ 1, 2, 3 ];
    return client.raiseEvent(instanceId, "MyEvent", eventData);
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    event_data = [1, 2 ,3]
    return await client.raise_event(instance_id, 'MyEvent', event_data)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$EventName = 'MyEvent'
$EventData = @(1,2,3)

Send-DurableExternalEvent -InstanceId $InstanceId -EventName $EventName -EventData $EventData

Java

@FunctionName("RaiseEvent")
public void raiseEvent(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String eventName = "MyEvent";
    int[] eventData = { 1, 2, 3 };
    durableContext.getClient().raiseEvent(instanceID, eventName, eventData);
}

Notitie

Als er geen indelingsexemplaar is met de opgegeven exemplaar-id, wordt het gebeurtenisbericht verwijderd. 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 ook rechtstreeks een gebeurtenis naar een orchestration-exemplaar genereren met behulp van de func durable raise-event opdracht in Core Tools.

Notitie

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 gegenereerd.
• event-data (optioneel): gegevens die naar het indelingsexemplaar 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 met de opslag verbindingsreeks die u wilt gebruiken. 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 indeling is voltooid

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

De API 'Wachten op voltooiing of controlestatusantwoord maken' kan worden gebruikt om de werkelijke uitvoer van een orchestration-exemplaar synchroon 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:

C#

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

JavaScript

const df = require("durable-functions");

const timeout = "timeout";
const retryInterval = "retryInterval";

module.exports = async function (context, req) {
    const client = df.getClient(context);
    const instanceId = await client.startNew(req.params.functionName, undefined, req.body);

    context.log(`Started orchestration with ID = '${instanceId}'.`);

    const timeoutInMilliseconds = getTimeInSeconds(req, timeout) || 30000;
    const retryIntervalInMilliseconds = getTimeInSeconds(req, retryInterval) || 1000;

    const response = client.waitForCompletionOrCreateCheckStatusResponse(
        context.bindingData.req,
        instanceId,
        timeoutInMilliseconds,
        retryIntervalInMilliseconds
    );
    return response;
};

function getTimeInSeconds(req, queryParameterName) {
    const queryValue = req.query[queryParameterName];
    return queryValue
        ? queryValue * 1000 // expected to be in seconds
        : undefined;
}

Zie Start-exemplaren voor de function.json-configuratie.

Python

import logging
import azure.functions as func
import azure.durable_functions as df

timeout = "timeout"
retry_interval = "retryInterval"

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    instance_id = await client.start_new(req.route_params['functionName'], None, req.get_body())
    logging.log(f"Started orchestration with ID = '${instance_id}'.")

    timeout_in_milliseconds = get_time_in_seconds(req, timeout)
    timeout_in_milliseconds = timeout_in_milliseconds if timeout_in_milliseconds != None else 30000
    retry_interval_in_milliseconds = get_time_in_seconds(req, retry_interval)
    retry_interval_in_milliseconds = retry_interval_in_milliseconds if retry_interval_in_milliseconds != None else 1000

    return await client.wait_for_completion_or_create_check_status_response(
        req,
        instance_id,
        timeout_in_milliseconds,
        retry_interval_in_milliseconds
    )

def get_time_in_seconds(req: func.HttpRequest, query_parameter_name: str):
    query_value = req.params.get(query_parameter_name)
    return query_value if query_value != None else 1000

PowerShell

Notitie

PowerShell heeft momenteel geen ingebouwde opdracht voor dit scenario.

Java

Java heeft momenteel geen enkele methode voor dit scenario. Het kan echter worden geïmplementeerd met behulp van een paar extra regels code.

@FunctionName("HttpStartAndWait")
public HttpResponseMessage httpStartAndWait(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}/wait", methods = {HttpMethod.POST}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("functionName") String functionName,
        final ExecutionContext context) {

    DurableTaskClient client = durableContext.getClient();
    String instanceId = client.scheduleNewOrchestrationInstance(functionName);
    context.getLogger().info("Created new Java orchestration with instance ID = " + instanceId);
    try {
        String timeoutString = req.getQueryParameters().get("timeout");
        Integer timeoutInSeconds = Integer.parseInt(timeoutString);
        OrchestrationMetadata orchestration = client.waitForInstanceCompletion(
                instanceId,
                Duration.ofSeconds(timeoutInSeconds),
                true /* getInputsAndOutputs */);
        return req.createResponseBuilder(HttpStatus.OK)
                .body(orchestration.getSerializedOutput())
                .header("Content-Type", "application/json")
                .build();
    } catch (TimeoutException timeoutEx) {
        // timeout expired - return a 202 response
        return durableContext.createCheckStatusResponse(req, instanceId);
    }
}

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"

Notitie

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 het orchestration-exemplaar op te halen, zijn er twee gevallen:

• De indelingsexemplaren zijn voltooid binnen de gedefinieerde time-out (in dit geval 2 seconden) en het antwoord is de werkelijke uitvoer van het indelingsexemplaar, 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 indelingsexemplaren kunnen niet worden voltooid binnen de gedefinieerde time-out en het antwoord is de standaardinstelling die 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}"
}

Notitie

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 indeling. 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 maken van http-beheerpayloads kan worden gebruikt om een serializeerbaar object op te halen 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 exemplaar-id van de indeling (moet hetzelfde zijn als de InstanceId invoer).
• StatusQueryGetUri: de status-URL van het orchestration-exemplaar.
• SendEventPostUri: de URL voor het genereren van gebeurtenissen van het orchestration-exemplaar.
• TerminatePostUri: de 'terminate'-URL van het orchestration-exemplaar.
• PurgeHistoryDeleteUri: de URL 'geschiedenis opschonen' van het orchestration-exemplaar.
• suspendPostUri: de URL 'suspend' van het orchestration-exemplaar.
• resumePostUri: de URL 'resume' van het orchestration-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:

C#

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

Notitie

De vorige C#-code is voor Durable Functions 2.x. Voor Durable Functions 1.x moet u in plaats van IDurableActivityContexthet kenmerk het OrchestrationClient kenmerk gebruiken DurableActivityContext 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.

JavaScript

const df = require("durable-functions");

modules.exports = async function(context, ctx) {
    const client = df.getClient(context);

    const payload = client.createHttpManagementPayload(ctx.instanceId);

    // send the payload to Azure Cosmos DB
    context.bindings.document = JSON.stringify({
        id: ctx.instanceId,
        payload,
    });
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.cosmosdb.cdb.Document:
    client = df.DurableOrchestrationClient(starter)

    payload = client.create_check_status_response(req, instance_id).get_body().decode()

    return func.cosmosdb.CosmosDBConverter.encode({
        id: instance_id,
        payload: payload
    })

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId
$Response = New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

Java

Notitie

Deze functie wordt momenteel niet ondersteund in Java.

Exemplaren terugspoelen (preview)

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

Notitie

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 indelingsexemplaren om onverwachte redenen mislukken. Indelingen in andere statussen dan Failed (bijvoorbeeld Running, , Pending, TerminatedCompleted) kunnen niet "opnieuw worden uitgevoerd". Zie het artikel Foutafhandeling voor meer informatie over foutafhandeling en beleid voor opnieuw proberen.

Gebruik de RewindAsync methode (.NET) of rewind (JavaScript) van de orchestration-clientbinding om de indeling weer in de status Actief te plaatsen. Met deze methode worden ook de uitvoeringsfouten van de activiteit of subindeling opnieuw uitgevoerd die de indelingsfout 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 database verbindingsreeks. Het resultaat is een indelingsfout diep in de werkstroom. 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 indeling kan nu worden voltooid.

Notitie

De functie voor terugspoelen biedt geen ondersteuning voor het terugspoelen van indelingsexemplaren die duurzame timers gebruiken.

C#

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

Notitie

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.

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Orchestrator failed and needs to be revived.";
    return client.rewind(instanceId, reason);
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

Notitie

Deze functie wordt momenteel niet ondersteund in Python.

PowerShell

Notitie

Deze functie wordt momenteel niet ondersteund in PowerShell.

Java

Notitie

Deze functie wordt momenteel niet ondersteund in Java.

Azure Functions Core Tools

U kunt een indelingsexemplaar ook rechtstreeks terugspoelen met behulp van de func durable rewind opdracht in Core Tools.

Notitie

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 terugspoelen van het orchestration-exemplaar.
• connection-string-setting(optioneel): naam van de toepassingsinstelling met de opslag verbindingsreeks die u wilt gebruiken. 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."

Exemplaargeschiedenis leegmaken

Als u alle gegevens wilt verwijderen die zijn gekoppeld aan een indeling, kunt u de exemplaargeschiedenis opschonen. U kunt bijvoorbeeld alle opslagbronnen verwijderen die zijn gekoppeld aan een voltooid exemplaar. Gebruik hiervoor de API voor het opschonen van exemplaren die is gedefinieerd door de orchestration-client.

In dit eerste voorbeeld ziet u hoe u één orchestration-exemplaar kunt opschonen.

C#

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

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);
    return client.purgeInstanceHistory(instanceId);
};

Zie Start-exemplaren voor de function.json-configuratie.

Python

import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    return await client.purge_instance_history(instance_id)

PowerShell

Notitie

Deze functie wordt momenteel niet ondersteund in PowerShell, maar kan worden bereikt met behulp van de HTTP-API van Durable Functions.

Java

@FunctionName("PurgeInstance")
public HttpResponseMessage purgeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, route = "purge/{instanceID}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("instanceID") String instanceID) {
    PurgeResult result = durableContext.getClient().purgeInstance(instanceID);
    if (result.getDeletedInstanceCount() == 0) {
        return req.createResponseBuilder(HttpStatus.NOT_FOUND)
                .body("No completed instance with ID '" + instanceID + "' was found!")
                .build();
    } else {
        return req.createResponseBuilder(HttpStatus.OK)
                .body("Successfully purged data for " + instanceID)
                .build();
    }
}

In het volgende voorbeeld ziet u een door timer geactiveerde functie waarmee de geschiedenis wordt opgeschoond voor alle indelingsexemplaren 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:

C#

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

Notitie

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.

JavaScript

De purgeInstanceHistoryBy methode kan worden gebruikt voor het voorwaardelijk opschonen van exemplaargeschiedenis voor meerdere exemplaren.

function.json

{
  "bindings": [
    {
      "schedule": "0 0 12 * * *",
      "name": "myTimer",
      "type": "timerTrigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Notitie

Dit voorbeeld is gericht op Durable Functions versie 2.x. Gebruik in versie 1.x orchestrationClient in plaats van durableClient.

index.js

const df = require("durable-functions");

module.exports = async function (context, myTimer) {
    const client = df.getClient(context);
    const createdTimeFrom = new Date(0);
    const createdTimeTo = new Date().setDate(today.getDate() - 30);
    const runtimeStatuses = [ df.OrchestrationRuntimeStatus.Completed ];
    return client.purgeInstanceHistoryBy(createdTimeFrom, createdTimeTo, runtimeStatuses);
};

PowerShell

Notitie

Deze functie wordt momenteel niet ondersteund in PowerShell, maar kan worden bereikt met behulp van de HTTP-API van Durable Functions.

Python

import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.DurableOrchestrationStatus import OrchestrationRuntimeStatus
from datetime import datetime, timedelta

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    created_time_from = datetime.min
    created_time_to = datetime.today() + timedelta(days = -30)
    runtime_statuses = [OrchestrationRuntimeStatus.Completed]

    return await client.purge_instance_history_by(created_time_from, created_time_to, runtime_statuses)

Java

@FunctionName("PurgeInstances")
public void purgeInstances(
        @TimerTrigger(name = "purgeTimer", schedule = "0 0 12 * * *") String timerInfo,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        ExecutionContext context) throws TimeoutException {
    PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
            .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(60)))
            .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
            .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));
    PurgeResult result = durableContext.getClient().purgeInstances(criteria);
    context.getLogger().info(String.format("Purged %d instance(s)", result.getDeletedInstanceCount()));
}

Notitie

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

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 verwijderd voor alle indelingsexemplaren die tijdens een opgegeven tijdsinterval zijn gemaakt. U kunt opgeschoonde exemplaren verder filteren op runtimestatus.

Notitie

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/tijd geaccepteerd.
• created-before (optioneel): verwijder de geschiedenis van exemplaren die vóór deze datum/tijd (UTC) zijn gemaakt. Iso 8601 opgemaakte datum/tijd 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 met de opslag verbindingsreeks die u wilt gebruiken. 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.

Notitie

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 met de opslag verbindingsreeks die u wilt gebruiken. 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

Meer informatie over het afhandelen van versiebeheer

Ingebouwde HTTP-API-verwijzing voor exemplaarbeheer