Mengelola instans orkestrasi

Gunakan API manajemen instans bawaan untuk memulai, memeriksa, menghentikan, menangguhkan, melanjutkan, dan menghapus instans orkestrasi dalam alur kerja tahan lama Anda. Dalam Durable Functions, pengikatan klien orchestration mengekspos API ini. Dalam Durable Task SDKs, operasi yang sama tersedia melalui kelas DurableTaskClient. Artikel ini menunjukkan cara melakukan setiap operasi manajemen instans dengan contoh kode untuk kedua platform.

Petunjuk / Saran

Azure Durable Task Scheduler adalah backend yang direkomendasikan untuk Durable Functions dan Durable Task SDK, memberikan pengalaman tanpa server yang dikelola sepenuhnya untuk menjalankan alur kerja yang tahan lama dalam skala besar.

Memulai instance

Metode start-new (atau schedule-new) pada klien orkestrasi memulai instans orkestrasi baru. Secara internal, metode ini menulis pesan ke backend yang dikonfigurasi (seperti Durable Task Scheduler atau Azure Storage) lalu mengembalikan. Pesan ini secara asinkron memicu dimulainya orkestrasi dengan nama yang ditentukan.

Berikut adalah parameter untuk memulai instans orkestrasi baru:

Nama: Nama fungsi orkestrator yang akan dijadwalkan.
Input: Setiap data yang dapat diserialisasikan JSON yang harus diteruskan sebagai input ke fungsi orkestrator.
InstanceId: (Opsional) ID unik instans. Jika Anda tidak menentukan parameter ini, metode menggunakan ID acak.

Petunjuk / Saran

Gunakan pengidentifikasi acak untuk ID instans jika memungkinkan. ID instans acak membantu memastikan distribusi beban yang sama saat Anda menskalakan fungsi orkestrator di beberapa VM. Waktu yang tepat untuk menggunakan ID instans nonrandom adalah ketika ID berasal dari sumber eksternal atau saat Anda menerapkan pola orkestrator singleton .

Nama: Nama orkestrasi yang akan dijadwalkan.
Input: Setiap data yang dapat diserialisasikan JSON yang harus diteruskan sebagai input ke orkestrasi.
InstanceId: (Opsional) ID unik instans. Jika Anda tidak menentukan parameter ini, metode menggunakan ID acak.

Petunjuk / Saran

Gunakan pengidentifikasi acak untuk ID instans jika memungkinkan. ID instans acak membantu memastikan distribusi beban yang sama saat Anda menskalakan orkestrasi di beberapa VM. Waktu yang tepat untuk menggunakan ID instans nonrandom adalah ketika ID berasal dari sumber eksternal atau saat Anda menerapkan pola orkestrator singleton .

Contoh fungsi berikut memulai instans orkestrasi baru:

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

Nota

Kode C# sebelumnya menggunakan model dalam proses dengan IDurableOrchestrationClient, yang ditandai sebagai usang dalam versi ekstensi Durable Functions yang lebih baru. Untuk proyek .NET baru, pertimbangkan untuk menggunakan model pekerja terisolasi .NET dengan DurableTaskClient. Untuk informasi selengkapnya, lihat artikel versi Durable Functions .

Kecuali ditentukan lain, contoh di halaman ini menggunakan pemicu HTTP dengan function.jsonberikut .

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
}

Nota

Contoh ini menargetkan Durable Functions versi 2.x. Di versi 1.x, gunakan orchestrationClient alih-alih 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}.`);
};

Kecuali ditentukan lain, contoh di halaman ini menggunakan pemicu HTTP dengan function.jsonberikut .

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
}

Nota

Contoh ini menargetkan Durable Functions versi 2.x. Di versi 1.x, gunakan orchestrationClient alih-alih 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}.")

Kecuali ditentukan lain, contoh di halaman ini menggunakan pemicu HTTP dengan function.jsonberikut .

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
}

Nota

Contoh ini menargetkan Durable Functions versi 2.x. Di versi 1.x, gunakan orchestrationClient alih-alih durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

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

Untuk menunggu orkestrator dimulai sebelum kembali dari fungsi Anda, gunakan metode waitForInstanceStart().

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

Penting

Saat ini, PowerShell Durable Task SDK tidak tersedia.

Kode berikut menunjukkan cara memulai instans orkestrasi baru dengan menggunakan SDK Tugas Tahan Lama:

using Microsoft.DurableTask.Client;

// Schedule a new orchestration instance
string instanceId = await client.ScheduleNewOrchestrationInstanceAsync("HelloWorld", input);
Console.WriteLine($"Started orchestration with ID = '{instanceId}'.");

// Optionally, wait for the orchestration to start
OrchestrationMetadata metadata = await client.WaitForInstanceStartAsync(instanceId, timeout: TimeSpan.FromSeconds(30));

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Schedule a new orchestration instance
instance_id = client.schedule_new_orchestration(hello_world, input=input_data)
print(f"Started orchestration with ID = '{instance_id}'.")

# Optionally, wait for the orchestration to start
state = client.wait_for_orchestration_start(instance_id, timeout=30)

import com.microsoft.durabletask.DurableTaskClient;

// Schedule a new orchestration instance
String instanceId = client.scheduleNewOrchestrationInstance("HelloWorld", input);
System.out.println("Started orchestration with ID = '" + instanceId + "'.");

// Optionally, wait for the orchestration to start
OrchestrationMetadata metadata = client.waitForInstanceStart(instanceId, Duration.ofSeconds(30), false);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Schedule a new orchestration instance
const instanceId = await client.scheduleNewOrchestration("HelloWorld", input);
console.log(`Started orchestration with ID = '${instanceId}'.`);

// Optionally, wait for the orchestration to start
const state = await client.waitForOrchestrationStart(instanceId, false, 30);

Instans kueri

Setelah memulai instans orkestrasi baru, Anda kemungkinan besar perlu mengkueri status runtime mereka untuk mempelajari apakah instans tersebut berjalan, selesai, atau gagal.

Metode get-status pada klien orkestrasi mengembalikan status instans orkestrasi.

instanceId Dibutuhkan (wajib), showHistory (opsional), showHistoryOutput (opsional), dan showInput (opsional) sebagai parameter.

showHistory: Jika diatur ke true, respons berisi riwayat eksekusi.
showHistoryOutput: Jika diatur ke true, riwayat eksekusi berisi output aktivitas.
showInput: Jika diatur ke false, respons tidak berisi input fungsi. Nilai defaultnya adalah true.

Metode mengembalikan objek dengan properti berikut:

Nama: Nama fungsi orkestrator.
InstanceId: ID instans orkestrasi (harus sama instanceId dengan input).
CreatedTime: Waktu saat fungsi orkestrator mulai berjalan.
LastUpdatedTime: Waktu saat orkestrasi terakhir melakukan checkpoint.
Input: Input fungsi sebagai nilai JSON. Bidang ini tidak diisi jika showInput adalah false.
CustomStatus: Status orkestrasi kustom dalam format JSON.
Output: Output fungsi sebagai nilai JSON (jika fungsi selesai). Jika fungsi orkestrator gagal, properti ini menyertakan detail kegagalan. Jika fungsi orkestrator ditangguhkan atau dihentikan, properti ini mencakup alasan penangguhan atau penghentian (jika ada).
RuntimeStatus: Salah satu nilai berikut:
- Tertunda: Instans dijadwalkan tetapi belum mulai berjalan.
- Berjalan: Instance sedang berjalan.
- Selesai: Instans selesai secara normal.
- ContinuedAsNew: Instans memulai ulang dirinya sendiri dengan riwayat baru. Status ini adalah status sementara.
- Gagal: Instans gagal dengan kesalahan.
- Dihentikan: Instans berhenti tiba-tiba.
- Ditangguhkan: Instans ditangguhkan dan dapat dilanjutkan pada titik waktu selanjutnya.
Riwayat: Riwayat pelaksanaan orkestrasi. Bidang ini hanya diisi jika showHistory diatur ke true.

showHistory: Jika diatur ke true, respons berisi riwayat eksekusi.
showHistoryOutput: Jika diatur ke true, riwayat eksekusi berisi output aktivitas.
showInput: Jika diatur ke false, respons tidak berisi input orkestrasi. Nilai defaultnya adalah true.

Metode mengembalikan objek dengan properti berikut:

Nama: Nama orkestrasi.
InstanceId: ID instans orkestrasi (harus sama instanceId dengan input).
CreatedTime: Waktu saat orkestrasi mulai berjalan.
LastUpdatedTime: Waktu saat orkestrasi terakhir melakukan checkpoint.
Input: Input orkestrasi sebagai nilai JSON. Bidang ini tidak diisi jika showInput adalah false.
CustomStatus: Status orkestrasi kustom dalam format JSON.
Output: Output orkestrasi sebagai nilai JSON (jika orkestrasi selesai). Jika orkestrasi gagal, properti ini menyertakan detail kegagalan. Jika orkestrasi ditangguhkan atau dihentikan, properti ini mencakup alasan penangguhan atau penghentian (jika ada).
RuntimeStatus: Salah satu nilai berikut:
- Tertunda: Instans dijadwalkan tetapi belum mulai berjalan.
- Berjalan: Instance sedang berjalan.
- Selesai: Instans selesai secara normal.
- ContinuedAsNew: Instans memulai ulang dirinya sendiri dengan riwayat baru. Status ini adalah status sementara.
- Gagal: Instans gagal dengan kesalahan.
- Dihentikan: Instans berhenti tiba-tiba.
- Ditangguhkan: Instans ditangguhkan dan dapat dilanjutkan pada titik waktu selanjutnya.
Riwayat: Riwayat pelaksanaan orkestrasi. Bidang ini hanya diisi jika showHistory diatur ke true.

Nota

Orkestrator tidak ditandai sebagai Completed sampai semua tugas terjadwal selesai dan orkestrator kembali. Dengan kata lain, tidaklah cukup bagi orkestrator untuk mencapai pernyataan return agar dapat ditandai sebagai Completed. Ini sangat relevan untuk kasus di mana WhenAny digunakan; sering kali orkestrator tersebut return sebelum semua tugas yang dijadwalkan selesai dijalankan.

Metode ini mengembalikan null (.NET dan Java), undefined (JavaScript), atau None (Python) jika instans tidak ada.

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

Nota

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

Untuk konfigurasi function.json, lihat Mengaktifkan instans.

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

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

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

using Microsoft.DurableTask.Client;

// Get the status of an orchestration instance
OrchestrationMetadata? metadata = await client.GetInstanceAsync(instanceId, getInputsAndOutputs: true);
if (metadata != null)
{
    OrchestrationRuntimeStatus status = metadata.RuntimeStatus;
    // do something based on the current status
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Get the status of an orchestration instance
state = client.get_orchestration_state(instance_id, fetch_payloads=True)
if state is not None:
    status = state.runtime_status
    # do something based on the current status

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationMetadata;

// Get the status of an orchestration instance
OrchestrationMetadata metadata = client.getInstanceMetadata(instanceId, true);
if (metadata != null) {
    OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
    // do something based on the current status
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Get the status of an orchestration instance
const state = await client.getOrchestrationState(instanceId, true);
if (state) {
    const status = state.runtimeStatus;
    // do something based on the current status
}

Mengkueri semua instans orkestrasi

Anda dapat menggunakan API dalam SDK bahasa Anda untuk mengkueri status semua instans orkestrasi di hub tugas Anda. API "list-instances" atau "get-status" ini mengembalikan daftar objek yang mewakili instans orkestrasi yang cocok dengan parameter kueri.

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

Nota

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

Untuk konfigurasi function.json, lihat Memulai instans.

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

Untuk konfigurasi function.json, lihat Memulai instans.

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

using Microsoft.DurableTask.Client;

// Query all orchestration instances
AsyncPageable<OrchestrationMetadata> instances = client.GetAllInstancesAsync(new OrchestrationQuery());

await foreach (OrchestrationMetadata instance in instances)
{
    Console.WriteLine(instance.InstanceId);
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Query all orchestration instances
instances = client.list_orchestrations()

for instance in instances:
    print(instance.instance_id)

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationStatusQuery;
import com.microsoft.durabletask.OrchestrationStatusQueryResult;

// Query all orchestration instances
OrchestrationStatusQuery query = new OrchestrationStatusQuery();
OrchestrationStatusQueryResult result = client.queryInstances(query);

for (OrchestrationMetadata instance : result.getOrchestrationState()) {
    System.out.println(instance.getInstanceId());
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Query all orchestration instances
const instances = client.getAllInstances();

for await (const instance of instances) {
    console.log(instance.instanceId);
}

Instans orkestrasi kueri dengan filter

Bagaimana jika Anda tidak memerlukan semua informasi yang disediakan kueri instans standar? Misalnya, bagaimana jika yang Anda cari hanya waktu pembuatan orkestrasi atau status waktu jalan orkestrasi? Persempit kueri Anda dengan menerapkan filter.

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

Nota

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

Lihat Memulai instans untuk konfigurasi function.json.

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

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

using Microsoft.DurableTask.Client;

// Get running or pending instances created in the last 7 days
var query = new OrchestrationQuery
{
    Statuses = new[] { OrchestrationRuntimeStatus.Running, OrchestrationRuntimeStatus.Pending },
    CreatedFrom = DateTime.UtcNow.AddDays(-7),
    CreatedTo = DateTime.UtcNow.AddDays(-1),
    PageSize = 100
};

AsyncPageable<OrchestrationMetadata> instances = client.GetAllInstancesAsync(query);

await foreach (OrchestrationMetadata instance in instances)
{
    Console.WriteLine($"{instance.InstanceId}: {instance.RuntimeStatus}");
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from datetime import datetime, timedelta

# Get running or pending instances created in the last 7 days
instances = client.list_orchestrations(
    created_time_from=datetime.utcnow() - timedelta(days=7),
    created_time_to=datetime.utcnow() - timedelta(days=1),
    runtime_status=['RUNNING', 'PENDING']
)

for instance in instances:
    print(f"{instance.instance_id}: {instance.runtime_status}")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationStatusQuery;
import com.microsoft.durabletask.OrchestrationRuntimeStatus;
import java.time.Duration;
import java.time.Instant;
import java.util.List;

// Get running or pending instances created in the last 7 days
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);

for (OrchestrationMetadata instance : result.getOrchestrationState()) {
    System.out.println(instance.getInstanceId() + ": " + instance.getRuntimeStatus());
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Get running or pending instances created in the last 7 days
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);

const instances = client.getAllInstances({
    statuses: [OrchestrationStatus.RUNNING, OrchestrationStatus.PENDING],
    createdFrom: sevenDaysAgo,
    createdTo: oneDayAgo,
});

for await (const instance of instances) {
    console.log(`${instance.instanceId}: ${instance.runtimeStatus}`);
}

Menghentikan instans orkestrasi

Jika Anda memiliki instans orkestrasi yang membutuhkan waktu terlalu lama untuk dijalankan, atau Anda perlu menghentikannya sebelum selesai karena alasan apa pun, Anda dapat mengakhirinya.

Dua parameter untuk API yang dihentikan adalah ID instans dan string alasan , yang menulis ke log dan ke status instans.

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

Nota

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

Lihat Memulai instans untuk konfigurasi function.json.

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)

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

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

using Microsoft.DurableTask.Client;

string reason = "Found a bug";
await client.TerminateInstanceAsync(instanceId, reason);

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

reason = "Found a bug"
client.terminate_orchestration(instance_id, reason=reason)

import com.microsoft.durabletask.DurableTaskClient;

String reason = "Found a bug";
client.terminate(instanceId, reason);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const reason = "Found a bug";
await client.terminateOrchestration(instanceId, reason);

Instans yang dihentikan pada akhirnya beralih ke status Terminated . Tapi transisi ini tidak segera terjadi. Sebaliknya, operasi penghentian diantrekan di hub tugas bersama dengan operasi lain untuk instans tersebut. Anda dapat menggunakan API kueri instans untuk mengetahui kapan instans yang dihentikan benar-benar telah mencapai status Terminated .

Nota

Penghentian instans saat ini tidak mengalami propagasi. Fungsi aktivitas dan sub-orkestrasi berjalan hingga selesai, terlepas dari apakah Anda mengakhiri instans orkestrasi yang memanggilnya.

Menangguhkan dan melanjutkan instans orkestrasi

Menangguhkan orkestrasi memungkinkan Anda menghentikan orkestrasi yang sedang berjalan. Tidak seperti mengakhiri suatu orkestrasi, Anda dapat melanjutkan proses orkestrasi yang ditangguhkan nanti.

Dua parameter untuk API suspend adalah ID instance dan string alasan, yang ditulis ke log dan ke status instance.

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

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

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)

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

Nota

Fitur ini hanya tersedia dalam SDK mandiri PowerShell Durable Functions. Lihat perbedaan antara SDK mandiri dan SDK bawaan warisan bersama dengan panduan migrasi.

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

using Microsoft.DurableTask.Client;

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

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

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

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

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

import com.microsoft.durabletask.DurableTaskClient;

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

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// To suspend an orchestration
await client.suspendOrchestration(instanceId);

// To resume an orchestration
await client.resumeOrchestration(instanceId);

Instans yang ditangguhkan pada akhirnya beralih ke status Suspended . Namun, transisi ini tidak segera terjadi. Sebaliknya, operasi penangguhan diantri di hub tugas bersama dengan operasi lain untuk instans tersebut. Gunakan API kueri instans untuk mengetahui kapan instans yang sedang berjalan benar-benar telah mencapai status Suspended .

Saat orkestrator yang ditangguhkan dilanjutkan, statusnya akan berubah kembali menjadi Running.

Mengirim event ke instans

Dalam beberapa skenario, fungsi orkestrator perlu menunggu dan mendengarkan peristiwa eksternal. Contoh di mana pendekatan ini berguna termasuk skenario pemantauan dan interaksi manusia .

Dalam beberapa skenario, orkestrasi perlu menunggu dan mendengarkan peristiwa eksternal. Contoh di mana pendekatan ini berguna termasuk skenario pemantauan dan interaksi manusia .

Anda dapat mengirim pemberitahuan peristiwa ke instans yang sedang berjalan dengan menggunakan API ajukan peristiwa klien orkestrasi. Orkestrasi dapat mendengarkan dan merespons peristiwa ini menggunakan API orkestrator menunggu peristiwa eksternal.

Parameter untuk peristiwa kenaikan adalah:

ID Instans: ID unik instans.
Nama peristiwa: Nama peristiwa yang akan dikirim.
Data peristiwa: Muatan yang dapat diserialkan JSON untuk dikirim ke instance.

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

Nota

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

Lihat Memulai instans untuk konfigurasi function.json.

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)

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

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

using Microsoft.DurableTask.Client;

int[] eventData = new int[] { 1, 2, 3 };
await client.RaiseEventAsync(instanceId, "MyEvent", eventData);

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

event_data = [1, 2, 3]
client.raise_orchestration_event(instance_id, "MyEvent", event_data)

import com.microsoft.durabletask.DurableTaskClient;

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

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const eventData = [1, 2, 3];
await client.raiseOrchestrationEvent(instanceId, "MyEvent", eventData);

Nota

Jika tidak ada instans orkestrasi dengan ID instans yang ditentukan, pesan peristiwa akan dibuang. Jika instans ada tetapi belum menunggu peristiwa, peristiwa disimpan dalam status instans hingga siap diterima dan diproses.

Tunggu penyelesaian orkestrasi

Dalam orkestrasi yang berlangsung lama, Anda mungkin ingin menunggu dan mendapatkan hasil dari sebuah orkestrasi. Dalam kasus ini, juga berguna untuk menentukan jangka waktu batas pada proses orkestrasi. Jika batas waktu terlampaui, status orkestrasi dikembalikan alih-alih hasilnya.

Gunakan API "tunggu penyelesaian atau buat respons status pemeriksaan" untuk mendapatkan output aktual dari instans orkestrasi secara sinkron. Secara default, metode ini memiliki batas waktu sepuluh detik dan interval polling satu detik.

Berikut adalah contoh fungsi pemicu HTTP yang menunjukkan cara menggunakan API ini:

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

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

Lihat Memulai instans untuk konfigurasi function.json.

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

Java saat ini tidak memiliki satu metode untuk skenario ini, tetapi Anda dapat menerapkannya dengan beberapa baris kode tambahan.

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

SDK Tugas Tahan Lama menyediakan metode untuk menunggu orkestrasi selesai secara sinkron.

using Microsoft.DurableTask.Client;

// Wait for orchestration to complete with a timeout
OrchestrationMetadata metadata = await client.WaitForInstanceCompletionAsync(
    instanceId,
    timeout: TimeSpan.FromSeconds(30),
    getInputsAndOutputs: true);

if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
{
    Console.WriteLine($"Output: {metadata.SerializedOutput}");
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Wait for orchestration to complete with a timeout
state = client.wait_for_orchestration_completion(
    instance_id,
    timeout=30,
    fetch_payloads=True)

if state.runtime_status == 'COMPLETED':
    print(f"Output: {state.serialized_output}")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationMetadata;
import java.time.Duration;
import java.util.concurrent.TimeoutException;

// Wait for orchestration to complete with a timeout
try {
    OrchestrationMetadata metadata = client.waitForInstanceCompletion(
            instanceId,
            Duration.ofSeconds(30),
            true /* getInputsAndOutputs */);
    System.out.println("Output: " + metadata.getSerializedOutput());
} catch (TimeoutException e) {
    System.out.println("Orchestration did not complete within timeout");
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Wait for orchestration to complete with a timeout
const state = await client.waitForOrchestrationCompletion(instanceId, true, 30);

if (state?.runtimeStatus === OrchestrationStatus.COMPLETED) {
    console.log(`Output: ${state.serializedOutput}`);
}

Panggil fungsi dengan baris berikut. Gunakan dua detik untuk batas waktu dan 0,5 detik untuk interval coba lagi:

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

Nota

Perintah cURL di atas mengasumsikan Anda memiliki fungsi orkestrator bernama E1_HelloSequence dalam proyek Anda. Karena bagaimana fungsi pemicu HTTP ditulis, Anda dapat menggantinya dengan nama fungsi orkestrator apa pun dalam proyek Anda.

Tergantung pada waktu yang diperlukan untuk mendapatkan respons dari instans orkestrasi, ada dua kasus:

Instans orkestrasi selesai dalam batas waktu yang ditentukan (dalam hal ini dua detik), dan responsnya adalah output instans orkestrasi aktual, dikirimkan secara sinkron:

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!"
]

Instans orkestrasi tidak dapat diselesaikan dalam batas waktu yang ditentukan, dan responsnya adalah default yang dijelaskan dalam penemuan URL API HTTP:

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

Nota

Format URL webhook mungkin berbeda, tergantung pada versi host Azure Functions mana yang Anda jalankan. Contoh sebelumnya adalah untuk host Azure Functions 3.0.

Mengambil URL webhook manajemen HTTP untuk instans orkestrasi

Gunakan sistem eksternal untuk memantau atau menaikkan peristiwa ke orkestrasi. Sistem eksternal berkomunikasi dengan Durable Functions melalui URL webhook yang merupakan bagian dari respons default yang dijelaskan dalam penemuan URL API HTTP. URL webhook dapat diakses secara terprogram menggunakan pengikatan klien orkestrasi. Secara khusus, API payload buat manajemen HTTP mendapatkan objek yang dapat diserialisasikan yang berisi URL webhook ini.

API pembuatan payload manajemen HTTP memiliki satu parameter:

ID Instans: ID unik instans.

Metode mengembalikan objek dengan properti string berikut:

Id: ID instans orkestrasi (harus sama dengan InstanceId input).
StatusQueryGetUri: URL status instance dari orkestrasi.
SendEventPostUri: URL "memicu peristiwa" dari instans orkestrasi.
TerminatePostUri: URL "menghentikan" dari instans orkestrasi.
PurgeHistoryDeleteUri: URL "hapus riwayat" untuk instans orkestrasi.
SuspendPostUri: URL "suspend" untuk instans orkestrasi.
ResumePostUri: URL "lanjutkan" instans orkestrasi.

Fungsi mengirim instans objek ini ke sistem eksternal untuk memantau atau memicu peristiwa pada orkestrasi yang sesuai, seperti yang terlihat pada contoh berikut.

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

Nota

Kode C# sebelumnya menggunakan model dalam proses dengan IDurableOrchestrationClient dan IDurableActivityContext, yang ditandai sebagai usang dalam versi ekstensi Durable Functions yang lebih baru. Untuk proyek .NET baru, pertimbangkan untuk menggunakan model pekerja terisolasi .NET dengan DurableTaskClient. Untuk informasi selengkapnya, lihat artikel versi Durable Functions .

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

Lihat Memulai instans untuk konfigurasi function.json.

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

using namespace System.Net

param($Request, $TriggerMetadata)

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

Instans orkestrasi memutar ulang

Jika Anda mengalami kegagalan orkestrasi karena alasan yang tidak terduga, gulung balik instans ke keadaan sehat sebelumnya dengan menggunakan API yang dibangun untuk tujuan tersebut.

Nota

API ini tidak dimaksudkan untuk menjadi pengganti penanganan kesalahan yang tepat dan kebijakan coba lagi. Sebaliknya, ini dimaksudkan untuk digunakan hanya dalam situasi di mana instans orkestrasi mengalami kegagalan karena alasan yang tidak terduga. Orkestrasi dalam status selain Failed (misalnya, Running, Pending, Terminated, atau Completed) tidak dapat "diulang". Untuk informasi selengkapnya tentang penanganan kesalahan dan kebijakan coba lagi, lihat artikel Penanganan kesalahan .

Gunakan metode RewindAsync (.NET) atau rewind (JavaScript) dari metode orchestration client binding untuk menempatkan orkestrasi kembali ke Running status. Metode ini juga menjalankan ulang aktivitas atau kegagalan eksekusi suborkestrasi yang menyebabkan kegagalan orkestrasi.

Misalnya, Anda memiliki alur kerja yang melibatkan serangkaian persetujuan manusia. Misalkan serangkaian fungsi aktivitas memberi tahu seseorang bahwa persetujuan mereka diperlukan dan menunggu tanggapan secara real-time. Setelah semua aktivitas persetujuan menerima respons atau waktu habis, misalkan aktivitas lain gagal karena kesalahan konfigurasi aplikasi, seperti string koneksi basis data yang tidak valid. Hasilnya adalah kegagalan orkestrasi jauh ke dalam alur kerja. Dengan API RewindAsync (.NET) atau rewind (JavaScript), admin aplikasi dapat memperbaiki kesalahan konfigurasi dan memutar balik orkestrasi yang gagal kembali ke status segera sebelum kegagalan. Tidak ada langkah-langkah interaksi manusia yang perlu disetujui kembali, dan orkestrasi sekarang dapat berhasil diselesaikan.

Nota

Fitur rewind tidak mendukung pengulangan mundur instans orkestrasi yang menggunakan penjadwal tahan lama.

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

Nota

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

Lihat Memulai instans untuk konfigurasi function.json.

using Microsoft.DurableTask.Client;

string reason = "Orchestrator failed and needs to be revived.";
await client.RewindInstanceAsync(instanceId, reason);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const reason = "Orchestrator failed and needs to be revived.";
await client.rewindInstance(instanceId, reason);

Memulai ulang instans orkestrasi

Memulai ulang orkestrasi membuat instans baru menggunakan riwayat instans yang dijalankan sebelumnya. Fitur ini berguna ketika Anda ingin menjalankan ulang orkestrasi dengan pola ID input dan instans yang sama, membuat eksekusi baru berdasarkan aslinya.

[FunctionName("RestartInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("restart-queue")] string instanceId)
{
    return client.RestartAsync(instanceId, restartWithNewInstanceId: true);
}

Nota

using Microsoft.DurableTask.Client;

// Restart an orchestration with a new instance ID
string newInstanceId = await client.RestartInstanceAsync(instanceId, restartWithNewInstanceId: true);
Console.WriteLine($"Restarted as new instance: {newInstanceId}");

// Restart an orchestration keeping the same instance ID
await client.RestartInstanceAsync(instanceId, restartWithNewInstanceId: false);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Restart an orchestration with a new instance ID
const newInstanceId = await client.restartOrchestration(instanceId, true);
console.log(`Restarted as new instance: ${newInstanceId}`);

// Restart an orchestration keeping the same instance ID
await client.restartOrchestration(instanceId, false);

Menghapus riwayat instans orkestrasi

Untuk menghapus semua data yang terkait dengan orkestrasi, bersihkan riwayat instans. Misalnya, hapus sumber daya penyimpanan apa pun yang terkait dengan instans yang telah selesai. Gunakan API instans pembersihan yang ditentukan oleh klien orkestrasi.

Contoh berikut menunjukkan cara memurnikan satu instans orkestrasi.

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

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)

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

using Microsoft.DurableTask.Client;

// Purge a single orchestration instance
PurgeResult result = await client.PurgeInstanceAsync(instanceId);
Console.WriteLine($"Purged {result.PurgedInstanceCount} instance(s).");

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Purge a single orchestration instance
result = client.purge_orchestration(instance_id)
print(f"Purged {result.deleted_instance_count} instance(s).")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.PurgeResult;

// Purge a single orchestration instance
PurgeResult result = client.purgeInstance(instanceId);
System.out.println("Purged " + result.getDeletedInstanceCount() + " instance(s).");

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Purge a single orchestration instance
const result = await client.purgeOrchestration(instanceId);
console.log(`Purged ${result?.deletedInstanceCount ?? 0} instance(s).`);

Contoh berikut menunjukkan fungsi yang dipicu oleh timer yang menghapus riwayat untuk semua instans orkestrasi yang selesai setelah jangka waktu yang ditentukan. Dalam hal ini, sistem menghapus data untuk semua instans yang telah selesai 30 hari atau lebih yang lalu. Contoh fungsi ini dijadwalkan berjalan sekali per hari, pada pukul 12.00 UTC:

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [TimerTrigger("0 0 12 * * *")] TimerInfo myTimer)
{
    return client.PurgeInstanceHistoryAsync(
        DateTime.MinValue,
        DateTime.UtcNow.AddDays(-30),  
        new List<OrchestrationStatus>
        {
            OrchestrationStatus.Completed
        });
}

Nota

Metode purgeInstanceHistoryBy ini dapat digunakan untuk membersihkan riwayat instans secara kondisional untuk beberapa instans.

function.json

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

Nota

Contoh ini menargetkan Durable Functions versi 2.x. Di versi 1.x, gunakan orchestrationClient alih-alih 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);
};

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)

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

using Microsoft.DurableTask.Client;

// Purge completed instances older than 30 days
var filter = new PurgeInstancesFilter(
    CreatedFrom: DateTime.MinValue,
    CreatedTo: DateTime.UtcNow.AddDays(-30),
    Statuses: new[] { OrchestrationRuntimeStatus.Completed });

PurgeResult result = await client.PurgeAllInstancesAsync(filter);
Console.WriteLine($"Purged {result.PurgedInstanceCount} instance(s).");

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from datetime import datetime, timedelta

# Purge completed instances older than 30 days
result = client.purge_orchestrations(
    created_time_from=datetime.min,
    created_time_to=datetime.utcnow() - timedelta(days=30),
    runtime_status=['COMPLETED']
)
print(f"Purged {result.deleted_instance_count} instance(s).")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.PurgeInstanceCriteria;
import com.microsoft.durabletask.PurgeResult;
import com.microsoft.durabletask.OrchestrationRuntimeStatus;
import java.time.Duration;
import java.time.Instant;
import java.util.List;

// Purge completed instances older than 30 days
PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
    .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
    .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));

PurgeResult result = client.purgeInstances(criteria);
System.out.println("Purged " + result.getDeletedInstanceCount() + " instance(s).");

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus, PurgeInstanceCriteria } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Purge completed instances older than 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

const criteria = new PurgeInstanceCriteria();
criteria.setCreatedTimeTo(thirtyDaysAgo);
criteria.setRuntimeStatusList([OrchestrationStatus.COMPLETED]);

const result = await client.purgeOrchestration(criteria);
console.log(`Purged ${result?.deletedInstanceCount ?? 0} instance(s).`);

Nota

Agar operasi riwayat penghapusan menyeluruh berhasil, status runtime instans target harus Diselesaikan, Dihentikan, atau Gagal.

Langkah berikutnya

Menangani penerapan versi

Referensi API HTTP bawaan untuk manajemen instans

Mulai menggunakan Durable Task SDK

Pelajari tentang Durable Task Scheduler

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-22

Mengelola instans orkestrasi

Memulai instance

Instans kueri

Mengkueri semua instans orkestrasi

Instans orkestrasi kueri dengan filter

Menghentikan instans orkestrasi

Menangguhkan dan melanjutkan instans orkestrasi

Mengirim event ke instans

Tunggu penyelesaian orkestrasi

Mengambil URL webhook manajemen HTTP untuk instans orkestrasi

Instans orkestrasi memutar ulang

Memulai ulang instans orkestrasi

Menghapus riwayat instans orkestrasi

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: