Példányok kezelése a Durable Functionsben az Azure-ban

A Durable Functions vezénylései hosszú ideig futó állapotalapú függvények, amelyek a beépített felügyeleti API-k használatával elindíthatók, lekérdezhetők, felfüggeszthetők, folytathatók és megszüntethetők. A Durable Functions vezénylési ügyfélkötése számos más példánykezelési API-t is elérhetővé teszi, például külső eseményeket küld a példányoknak, törli a példányelőzményeket stb. Ez a cikk az összes támogatott példánykezelési művelet részleteit ismerteti.

Példányok indítása

A orchestrációs klienskötésúj indítás (vagy új ütemezés) metódusa új vezénylési példányt indít el. Ez a metódus belsőleg egy üzenetet ír a Durable Functions storage-szolgáltatón keresztül, majd visszaadja. Ez az üzenet aszinkron módon aktiválja egy vezénylési függvény indítását a megadott névvel.

Az új vezénylési példány indításának paraméterei a következők:

• Név: Az ütemezni kívánt vezénylő függvény neve.
• Bemenet: Minden olyan JSON-szerializálható adat, amelyet a vezénylő függvény bemeneteként kell átadni.
• InstanceId: (Nem kötelező) A példány egyedi azonosítója. Ha nem adja meg ezt a paramétert, a metódus véletlenszerű azonosítót használ.

Jótanács

Amikor csak lehetséges, használjon véletlenszerű azonosítót a példányazonosítóhoz. A véletlenszerű példányazonosítók segítenek biztosítani az egyenlő terheléselosztást, amikor az orchesztálófüggvények több virtuális gépre skálázódnak. A nem véletlenszerű példányazonosítók használatára akkor van szükség, amikor az azonosítónak külső forrásból kell származnia, vagy amikor a szinguleton orchestrator mintát valósít meg.

Az alábbi kód egy új orchestration példányt elindító példa függvény:

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

JavaScript

Ha másként nincs megadva, az ezen a lapon szereplő példák a HTTP-eseményindítót az alábbi function.jsonhasználják.

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
}

Megjegyzés:

Ez a példa a Durable Functions 2.x-es verzióját célozza meg. Használja az orchestrationClient-t a durableClient helyett az 1.x verzióban.

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}.`);
};

Piton

Hacsak másként nincs megadva, az ezen az oldalon szereplő példák az alábbi function.json-val használják a HTTP-eseményindítót.

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
}

Megjegyzés:

Ez a példa a Durable Functions 2.x-es verzióját célozza meg. Az 1.x verzióban használja a orchestrationClient-t durableClient helyett.

__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

Ha másként nincs megadva, az ezen a lapon szereplő példák az alábbi function.jsonHTTP-kiváltó okot használják.

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
}

Megjegyzés:

Ez a példa a Durable Functions 2.x-es verzióját célozza meg. Az 1.x verzióban a orchestrationClient helyett, használja durableClient-et.

run.ps1

param($Request, $TriggerMetadata)

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

Jáva

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

Ha azt szeretné, hogy az orkesztrátor elinduljon, mielőtt visszatér a függvényéből, használhatja a waitForInstanceStart() metódust is.

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

Azure Functions Core Tools (Azure-függvények Alapvető Eszközei)

Közvetlenül is elindíthat egy példányt a func durable start-new Core Tools parancsával , amely a következő paramétereket veszi igénybe:

• function-name (kötelező): Az elindítandó függvény neve.
• input (nem kötelező): Bemenet a függvénybe közvetlenül vagy JSON-fájlon keresztül. Fájlok esetén adjon hozzá egy előtagot a fájl @elérési útjára, például @path/to/file.json.
• id (nem kötelező): A vezénylési példány azonosítója. Ha nem adja meg ezt a paramétert, a parancs véletlenszerű GUID azonosítót használ.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték az AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. Ezt a host.json is beállíthatja a durableTask:HubName használatával.

Megjegyzés:

A Core Tools parancsai feltételezik, hogy egy függvényalkalmazás gyökérkönyvtárából futtatja őket. Ha kifejezetten megadja a connection-string-setting és a task-hub-name paramétereket, bármelyik könyvtárból futtathatja a parancsokat. Bár ezeket a parancsokat a függvényalkalmazás-gazdagép futtatása nélkül is végrehajthatja, előfordulhat, hogy nem tud megfigyelni bizonyos hatásokat, ha a gazdagép nem fut. start-new parancs például beilleszt egy kezdő üzenetet a cél feladatközpontba, de a vezénylés ténylegesen nem fut, hacsak nem fut egy olyan függvényalkalmazás-gazdagépfolyamat, amely feldolgozhatja az üzenetet.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A következő parancs elindítja a HelloWorld nevű függvényt, és átadja neki a fájl counter-data.json tartalmát:

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

Lekérdezéspéldányok

Az új orchestrációs példányok elindítása után valószínűleg le kell kérdeznie a futtatási állapotukat, hogy megtudja, futnak-e, befejeződtek-e, vagy sikertelenek voltak.

A vezénylési klienskötésget-status metódusa lekérdezi egy vezénylési példány állapotát.

Paraméterként egy instanceId (kötelező), showHistory (nem kötelező), showHistoryOutput (nem kötelező) és showInput (nem kötelező) paramétert használ.

• showHistory: Ha be van trueállítva, a válasz tartalmazza a végrehajtási előzményeket.
• showHistoryOutput: Ha be van trueállítva, a végrehajtási előzmények tevékenységkimeneteket tartalmaznak.
• showInput: Ha be van falseállítva, a válasz nem tartalmazza a függvény bemenetét. Az alapértelmezett érték a true.

A metódus a következő tulajdonságokkal rendelkező objektumot ad vissza:

• Név: A vezénylő függvény neve.
• InstanceId: A vezénylési példányazonosító (meg kell egyeznie a instanceId bemenet értékével).
• CreatedTime: Az az időpont, amikor a vezénylő függvény elindult.
• LastUpdatedTime: Az az időpont, amikor a koordináció utoljára ellenőrzőpontra került.
• Bemenet: A függvény bemenete JSON-értékként. Ez a mező nem lesz kitöltve, ha showInput hamis.
• CustomStatus: Egyéni orkesztáció állapota JSON formátumban.
• Kimenet: A függvény kimenete JSON-értékként (ha a függvény befejeződött). Ha a vezénylő függvény sikertelen volt, ez a tulajdonság tartalmazza a hiba részleteit. Ha a vezénylő funkciót felfüggesztették vagy leállították, ez a tulajdonság tartalmazza a felfüggesztés vagy a megszüntetés okát (ha van ilyen).
• RuntimeStatus: Az alábbi értékek egyike:
  • Függőben: A példány ütemezve van, de még nem indult el.
  • Fut: A példány fut.
  • Befejezve: A példány normálisan befejeződött.
  • ContinuedAsNew: A példány új előzménytörténettel indult újra. Ez az állapot átmeneti állapot.
  • Sikertelen: A példány hiba miatt meghiúsult.
  • Megszakítva: A példányt hirtelen leállították.
  • Felfüggesztve: A példány fel van függesztve, és később folytatható.
• Előzmények: A vezénylés végrehajtási története. Ezt a mezőt csak akkor tölti ki a rendszer, ha showHistory be truevan állítva.

Megjegyzés:

A vezénylő nem lesz megjelölve Completed addig, amíg az összes ütemezett feladata be nem fejeződik , és a vezénylő vissza nem tér. Más szóval, nem elegendő, hogy egy orchestrátor elérje a nyilatkozatátreturn, hogy meg legyen jelölveCompleted. Ez különösen releváns azokban az esetekben, amikor a WhenAny használata történik; ezek a vezénylők gyakran return az összes ütemezett feladat végrehajtása előtt.

Ez a metódus null (.NET és Java), undefined (JavaScript) vagy None (Python) értéket ad vissza, ha a példány nem létezik.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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') { ... }

Jáva

@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 (Azure-függvények Alapvető Eszközei)

Az orchestration példány állapotát közvetlenül is lekérdezheti a func durable get-runtime-status Core Tools parancsával.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable get-runtime-status parancs a következő paramétereket használja:

• id (kötelező): A vezénylési példány azonosítója.
• show-input (nem kötelező): Ha be van trueállítva, a válasz a függvény bemenetét tartalmazza. Az alapértelmezett érték a false.
• show-output (nem kötelező): Ha be van trueállítva, a válasz a függvény kimenetét tartalmazza. Az alapértelmezett érték a false.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A durableTask:HubName használatával host.jsonis beállítható.

A következő parancs egy 0ab8c55a66644d68a3a8b220b12d209c vezénylési példányazonosítójú példány állapotát kéri le (beleértve a bemenetet és a kimenetet is). Feltételezi, hogy a func függvényalkalmazás gyökérkönyvtárából futtatja a parancsot:

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

A durable get-history parancs segítségével lekérheti egy vezénylési példány előzményeit. A következő paramétereket veszi igénybe:

• id (kötelező): A vezénylési példány azonosítója.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A host.json-ban is beállítható a durableTask:HubName használatával.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Az összes példány lekérdezése

A nyelvi SDK API-kkal lekérdezheti a feladatközpont összes vezénylési példányának állapotát. Ez a "list-instances" vagy "get-status" API a lekérdezési paramétereknek megfelelő orchestration példányokat képviselő objektumok listáját adja vissza.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

A function.json konfigurációjának kezdőpéldányait lásd.

PowerShell

Megjegyzés:

Ez a funkció jelenleg nem támogatott a PowerShellben, de a Durable Functions HTTP API-val érhető el.

Jáva

@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 (Azure-függvények Alapvető Eszközei)

A példányokat közvetlenül is lekérdezheti a Core Tools func durable get-instances parancs használatával.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable get-instances parancs a következő paramétereket használja:

• top (nem kötelező): Ez a parancs támogatja a lapozást. Ez a paraméter a kérésenként lekért példányok számának felel meg. Az alapértelmezett érték 10.
• continuation-token (nem kötelező): Egy token, amely jelzi, hogy melyik példány oldalt vagy szakaszt kell lekérni. Minden get-instances végrehajtás egy tokent ad vissza a következő példányoknak.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A durableTask:HubName használatával host.jsonis beállítható.

func durable get-instances

Példányok lekérdezése szűrőkkel

Mi a teendő, ha nem igazán van szüksége az összes olyan információra, amelyet egy standard példány lekérdezése adhat meg? Mi a teendő például, ha csak a vezénylés létrehozási idejét vagy a vezénylési futás állapotát keresi? Szűrők alkalmazásával szűkítheti a lekérdezést.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Megjegyzés:

Ez a funkció jelenleg nem támogatott a PowerShellben, de a Durable Functions HTTP API-val érhető el.

Jáva

@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 (Azure-függvények Alapvető Eszközei)

Az Azure Functions Core Toolsban szűrőkkel is használhatja a durable get-instances parancsot. A fent említett top, , connection-string-settingcontinuation-tokenés task-hub-name paraméterek mellett három szűrőparamétert (created-afteréscreated-beforeruntime-status) is használhat.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A következők a durable get-instances parancs paraméterei.

• created-after (nem kötelező): A dátum/idő (UTC) után létrehozott példányok lekérése. Elfogadott ISO 8601 formátumú dátumok és időpontok.
• created-before (nem kötelező): A dátum/idő (UTC) előtt létrehozott példányok lekérése. Elfogadja az ISO 8601 formátumú dátum/idő értékeket.
• runtime-status (nem kötelező): Egy adott állapotú példányok lekérése (például futtatás vagy befejezett). Több (szóközzel elválasztott) állapotot is megadhat.
• top (nem kötelező): Kérésenként lekért példányok száma. Az alapértelmezett érték 10.
• continuation-token (nem kötelező): Egy token, amely jelzi, melyik oldal vagy szakasz példányait kell lekérni. Minden get-instances végrehajtás egy tokent ad vissza a következő példányok készletének.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A durableTask:HubName használatával host.jsonis beállítható.

Ha nem ad meg szűrőket (created-aftercreated-beforevagy runtime-status), a parancs egyszerűen lekéri top a példányokat, a futtatókörnyezet állapotára vagy a létrehozási időre való tekintet nélkül.

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

Példányok törlése

Ha van egy orchestration példánya, amely túl sokáig fut, vagy csak meg kell állítania valamilyen okból még a befejezése előtt, megszakíthatja azt.

A megszakítási API két paramétere egy példányazonosító és egy indoklószöveg, amelyek naplókban és a példány állapotán kerülnek rögzítésre.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Jáva

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

A leállított példány végül átáll a Terminated állapotba. Ez az áttűnés azonban nem történik meg azonnal. A leállítási művelet inkább a feladatközpontban lesz várólistára állítva az adott példány egyéb műveleteivel együtt. A példány lekérdezési API-kkal megtudhatja, hogy egy leállított példány mikor érte el ténylegesen az állapotot Terminated .

Megjegyzés:

A példánymegszüntetés jelenleg nem terjed tovább. A tevékenységfüggvények és az alvezénylések befejeződnek, függetlenül attól, hogy leállította-e az őket meghívó vezénylési példányt.

Példányok felfüggesztése és folytatása

Az orchestráció felfüggesztése lehetővé teszi a futó orchestráció megszakítását. A felmondással ellentétben lehetősége van egy felfüggesztett orchestrator újraindítására egy későbbi időpontban.

A felfüggesztési API két paramétere egy példányazonosító és egy indoklás szöveg, amelyeket a rendszer naplókba és a példány státuszába rögzít.

C#

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

JavaScript

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

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

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

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

Piton

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)

    # To suspend an orchestration
    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # To resume an orchestration
    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

# To suspend an orchestration
$SuspendReason = 'Need to pause workflow'
Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# To resume an orchestration
$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

Megjegyzés:

Ez a funkció csak az önálló Durable Functions PowerShell SDK-ban érhető el. A migrálási útmutatóval együtt megtekintheti az önálló SDK és az örökölt beépített SDK közötti különbséget.

Jáva

@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();  

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

A felfüggesztett példány végül átáll az Suspended állapotba. Ez az áttűnés azonban nem történik meg azonnal. Ehelyett a felfüggesztési művelet várólistára kerül a feladatközpontban az adott példány egyéb műveleteivel együtt. A példány lekérdezési API-kkal megtudhatja, hogy egy futó példány ténylegesen elérte-e a felfüggesztett állapotot.

A felfüggesztett vezénylő folytatásakor az állapota visszaáll Running-ra.

Azure Functions Core Tools (Azure-függvények Alapvető Eszközei)

Az orkesztrációs példányt közvetlenül is megszüntetheti a func durable terminate Core Tools parancsával.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable terminate parancs a következő paramétereket használja:

• id (kötelező): Az orchestration példány leállításához szükséges azonosító.
• reason (nem kötelező): A felmondás oka.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A durableTask:HubName használatával host.jsonis beállítható.

A következő parancs 0ab8c55a66644d68a3a8b220b12d209c azonosítójú vezénylési példányt szüntet meg:

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

Események küldése példányokra

Bizonyos esetekben a vezénylő függvényeknek várniuk és figyelniük kell a külső eseményeket. Példák azokra a forgatókönyvekre, amelyekben ez hasznos, például a monitorozási és az emberi interakciós forgatókönyvek.

Eseményértesítéseket küldhet a futó példányoknak az orchestrációs klienseseményindítási API-jának használatával. Az orchestrációk a külső esemény várakoztatása API használatával meghallgathatják és megválaszolhatják ezeket az eseményeket.

A emelési esemény paraméterei a következők:

• Példányazonosító: A példány egyedi azonosítója.
• Esemény neve: A küldendő esemény neve.
• Eseményadatok: JSON-szerializálható adatcsomag, amely a példánynak küldhető.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Jáva

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

Megjegyzés:

Ha nincs ilyen vezénylési példány a megadott példányazonosítóval, a rendszer elveti az eseményüzenetet. Ha egy példány létezik, de még nem várja meg az eseményt, az esemény a példány állapotában lesz tárolva, amíg készen nem áll a fogadásra és a feldolgozásra.

Azure Functions Core Tools (Azure-függvények Alapvető Eszközei)

Közvetlenül is indíthat eseményt egy vezénylési példány számára a func durable raise-event Core Tools parancsával.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable raise-event parancs a következő paramétereket használja:

• id (kötelező): A vezénylési példány azonosítója.
• event-name: Az esemény neve, amelyet indítani kell.
• event-data (nem kötelező): Az orkesztrációs példánynak küldendő adatok. Ez lehet egy JSON-fájl elérési útja, vagy közvetlenül a parancssorban is megadhatja az adatokat.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Az alapértelmezett érték a DurableFunctionsHub. A durableTask:HubName használatával host.jsonis beállítható.

func durable raise-event --id 0ab8c55a66644d68a3a8b220b12d209c --event-name MyEvent --event-data @eventdata.json

func durable raise-event --id 1234567 --event-name MyOtherEvent --event-data 3

Várakozás a vezénylés befejezésére

Hosszú ideig futó vezénylések esetén érdemes várni, és lekérni egy vezénylés eredményét. Ezekben az esetekben hasznos lehet egy időkorlátot meghatározni az orchestration során. Ha az időtúllépés bekövetkezik, a vezénylés állapotát kell visszaadni az eredmények helyett.

A "várakozás a befejezésre vagy az állapot ellenőrzése válasz létrehozása" API segítségével szinkron módon lekérheti az orchestration példány tényleges kimenetét. Ez a metódus alapértelmezés szerint 10 másodperces alapértelmezett időtúllépéssel és 1 másodperces lekérdezési intervallummal rendelkezik.

Íme egy példa HTTP-trigger függvényre, amely bemutatja, hogyan használhatja ezt az API-t:

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Megjegyzés:

A PowerShell jelenleg nem rendelkezik beépített paranccsal ehhez a forgatókönyvhöz.

Jáva

A Java jelenleg nem rendelkezik egyetlen metódussal ehhez a forgatókönyvhöz. Azonban néhány további kódsor használatával implementálható.

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

Hívja meg a függvényt a következő sor használatával. Az időtúllépéshez 2 másodpercet, az újrapróbálkozási időközhöz pedig 0,5 másodpercet használjon:

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

Megjegyzés:

A fenti cURL-parancs feltételezi, hogy van egy E1_HelloSequence elnevezésű vezénylő függvény a projektjében. Az HTTP-eseményindító függvény megírásának módja lehetővé teszi, hogy bármelyik vezénylő függvény nevét felhasználja a projektben.

A vezénylési példány válaszának lekéréséhez szükséges időtől függően két eset létezik:

• A vezénylési példányok a megadott időtúllépésen belül befejeződnek (ebben az esetben 2 másodperc), a válasz pedig a vezénylési példány tényleges kimenete, szinkron módon:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:14:29 GMT
Transfer-Encoding: chunked

[
    "Hello Tokyo!",
    "Hello Seattle!",
    "Hello London!"
]

• Az orkesztációs példányok nem fejezhetők be a megadott időtúllépésen belül, és a válasz a HTTP API URL felderítésben ismertetett alapértelmezett válasz.

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked

{
    "id": "d3b72dddefce4e758d92f4d411567177",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}

Megjegyzés:

A webhook URL-címeinek formátuma eltérhet attól függően, hogy az Azure Functions-gazdagép melyik verzióját futtatja. Az előző példa az Azure Functions 3.0-gazdagépre mutat.

HTTP-felügyeleti webhook URL-címek lekérése

Külső rendszer használatával figyelheti vagy vezénylésre állíthatja az eseményeket. A külső rendszerek a Webhook URL-címeinek használatával kommunikálhatnak a Durable Functions szolgáltatással, amelyek a HTTP API URL-felderítésben leírt alapértelmezett válasz részét képezik. A webhook URL-ek programozott módon is elérhetők az orchestration client binding használatával. A http-felügyeleti hasznos adatok létrehozása API-val egy szerializálható objektumot kaphat, amely ezeket a webhook URL-címeket tartalmazza.

Az HTTP felügyeleti terhelés létrehozása API egy paraméterrel rendelkezik:

• Példányazonosító: A példány egyedi azonosítója.

A metódusok a következő sztringtulajdonságokkal rendelkező objektumot adnak vissza:

• Azonosító: Az orkesztráció példányazonosítója (a bemenettel InstanceId megegyezőnek kell lennie).
• StatusQueryGetUri: Az orchestrációs példány állapot URL-címe.
• SendEventPostUri: A vezénylési példány "esemény létrehozása" URL-címe.
• TerminatePostUri: A vezénylési példány "befejezés" URL-címe.
• PurgeHistoryDeleteUri: Az orchestration példány "törlési előzményeinek" URL-címe.
• suspendPostUri: A vezénylési példány "felfüggesztés" URL-címe.
• resumePostUri: A vezénylési példány "folytatás" URL-je.

A függvények külső rendszereknek küldhetik ezen objektumok példányait, hogy monitorozzák vagy létrehozzák az eseményeket az adott orchestration-ökhöz kapcsolódóan, ahogyan az alábbi példákban is látható.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében a IDurableActivityContext helyett a DurableActivityContext-t kell használnia, a DurableClient attribútum helyett a OrchestrationClient attribútumot kell használnia, és a IDurableOrchestrationClient paramétertípus helyett a DurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Jáva

Megjegyzés:

Ez a funkció jelenleg nem támogatott a Java-ban.

Példányok visszatekerése (előzetes verzió)

Ha váratlan okból meghiúsul a vezénylés, az erre a célra létrehozott API-val visszatekerheti a példányt egy korábban kifogástalan állapotba.

Megjegyzés:

Ez az API nem helyettesíti a megfelelő hibakezelési és újrapróbálkozési szabályzatokat. Inkább csak olyan esetekben használható, amikor a vezénylési példányok váratlan okokból meghiúsulnak. Az olyan állapotban lévő vezérlések, amelyek nem Failed (pl. Running, Pending, Terminated, Completed), nem "visszatekerhetők". A hibakezelési és újrapróbálkozési szabályzatokkal kapcsolatos további információkért tekintse meg a hibakezelési cikket.

Az orchestrációs klienskötés RewindAsync (.NET) vagy rewind (JavaScript) metódusával visszaállíthatja az orchestrációt a Futó állapotba. Ez a módszer a vezénylési hibákat okozó tevékenység- vagy részvezénylési (alvezénylés) végrehajtási hibákat is újrafuttatja.

Tegyük fel például, hogy van egy munkafolyamata, amely emberi jóváhagyások sorozatát foglalja magában. Tegyük fel, hogy léteznek tevékenységi funkciók, amelyek figyelmeztetnek valakit, hogy jóváhagyásra van szükség, és várják meg a valós idejű választ. Miután az összes jóváhagyási tevékenység kapott választ vagy időtúllépést, feltételezzük, hogy egy másik tevékenység hibát okozhat egy alkalmazás helytelen konfigurációja miatt, például egy érvénytelen adatbázis-kapcsolati karakterlánc miatt. Az eredmény egy orchestrációs hiba a folyamat mélyén. RewindAsync A (.NET) vagy rewind a (JavaScript) API-val az alkalmazás rendszergazdája kijavíthatja a konfigurációs hibát, és visszatekerheti a sikertelen vezénylést közvetlenül a hiba előtt. Az emberi beavatkozás egyik lépését sem kell újra jóváhagyni, és a vezénylés sikeresen befejeződhet.

Megjegyzés:

A visszatekerés funkció nem támogatja a tartós időzítőket használó vezénylési példányok visszatekerését.

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

Megjegyzés:

Ez a funkció jelenleg nem támogatott a Pythonban.

PowerShell

Megjegyzés:

Ez a funkció jelenleg nem támogatott a PowerShellben.

Jáva

Megjegyzés:

Ez a funkció jelenleg nem támogatott a Java-ban.

Azure Functions Core Tools (Azure-függvények Alapvető Eszközei)

A vezénylési példányt közvetlenül visszatekerheti a Core Tools func durable rewind parancsával.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable rewind parancs a következő paramétereket használja:

• id (kötelező): A vezénylési példány azonosítója.
• reason (nem kötelező): Az orkestrációs példány visszatekerésének oka.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl tevékenységközpontjának nevét használja.

func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

Példányelőzmények törlése

Az orchestrationhoz társított összes adat eltávolításához törölheti a példányelőzményeket. Előfordulhat például, hogy törölni szeretné a befejezett példányhoz társított tárolási erőforrásokat. Ehhez használja a törlési példány API-t, amelyet az orchestrációs kliens definiált.

Ez az első példa bemutatja, hogyan törölhet egyetlen orchestration példányt.

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

A function.json konfigurációjának kezdőpéldányait lásd.

Piton

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

Megjegyzés:

Ez a funkció jelenleg nem támogatott a PowerShellben, de a Durable Functions HTTP API-val érhető el.

Jáva

@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();
    }
}

A következő példa egy időzítő által aktivált függvényt mutat be, amely törli a meghatározott időintervallum után befejeződött összes orkestrációs példány előzményeit. Ebben az esetben eltávolítja a 30 vagy több nappal ezelőtt befejezett összes példány adatait. Ez a példafüggvény naponta egyszer, UTC 12:00-kor lesz futtatva:

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

Megjegyzés:

Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében OrchestrationClient attribútum helyett DurableClient attribútumot kell használnia, és DurableOrchestrationClienthelyett IDurableOrchestrationClient paramétertípust kell használnia. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.

JavaScript

A purgeInstanceHistoryBy metódus több példány példányelőzményeinek feltételes törlésére használható.

function.json

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

Megjegyzés:

Ez a példa a Durable Functions 2.x-es verzióját célozza meg. Az 1.x verzióban a orchestrationClient helyett, használja durableClient-et.

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

Megjegyzés:

Ez a funkció jelenleg nem támogatott a PowerShellben, de a Durable Functions HTTP API-val érhető el.

Piton

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)

Jáva

@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()));
}

Megjegyzés:

Ahhoz, hogy a törlési előzményművelet sikeres legyen, a célpéldány futtatókörnyezeti állapotának befejezettnek, megszakítottnak vagy sikertelennek kell lennie.

Azure Functions Core Tools (Azure-függvények Alapvető Eszközei)

Az orchestration példány előzményeit a Core Tools func durable purge-history parancsával törölheti. Az előző szakaszban szereplő második C#-példához hasonlóan törli a megadott időintervallumban létrehozott összes vezénylési példány előzményeit. A kiürített példányokat futásidejű állapot szerint tovább szűrheti.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable purge-history parancs számos paramétert tartalmaz:

• created-after (nem kötelező): Törölje a dátum/idő (UTC) után létrehozott példányok előzményeit. Elfogadja az ISO 8601 formátumú dátum/idő értékeket.
• created-before (nem kötelező): Törölje a dátum/idő (UTC) előtt létrehozott példányok előzményeit. Elfogadja az ISO 8601 formátumú dátum/idő értékeket.
• runtime-status (nem kötelező): Törölje az adott állapotú példányok előzményeit (például fut vagy befejeződött). Több (szóközzel elválasztott) állapotot is megadhat.
• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl tevékenységközpontjának nevét használja.

A következő parancs törli azoknak a sikertelen példányoknak az előzményeit, amelyeket 2021. november 14. 19:35 (UTC) előtt hoztak létre.

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

Tevékenységközpont törlése

A Core Tools parancsával törölheti az func durable delete-task-hub adott feladatközponthoz társított összes tárolási összetevőt, beleértve az Azure Storage-táblákat, az üzenetsorokat és a blobokat.

Megjegyzés:

A Core Tools-parancsok jelenleg csak akkor támogatottak, ha az alapértelmezett Azure Storage-szolgáltatót használja a futtatókörnyezet állapotának megőrzéséhez.

A durable delete-task-hub parancs két paramétert tartalmaz:

• connection-string-setting (nem kötelező): A használni kívánt tárkapcsolati sztringet tartalmazó alkalmazásbeállítás neve. Az alapértelmezett érték a AzureWebJobsStorage.
• task-hub-name (nem kötelező): A használni kívánt Durable Functions-feladatközpont neve. Alapértelmezés szerint a rendszer a host.json fájl tevékenységközpontjának nevét használja.

Az alábbi parancs törli a UserTest feladatközponthoz társított összes Azure Storage-adatot.

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

Következő lépések

A verziószámozás kezelésének ismertetése

Beépített HTTP API-referencia példánykezeléshez