Mengelola instans di Durable Functions di Azure

Orkestrasi dalam Durable Functions adalah fungsi stateful yang berlangsung lama dan dapat dijalankan, diquery, ditunda, dilanjutkan, serta dihentikan menggunakan API manajemen bawaan. Beberapa API manajemen instans lainnya juga diekspos oleh pengikatan klien orkestrasi Durable Functions, seperti mengirim peristiwa eksternal ke instans, membersihkan riwayat instans, dll. Artikel ini masuk ke detail semua operasi manajemen instans yang didukung.

Memulai instance

Metode start-new (atau schedule-new) pada pengikatan klien orkestrasi memulai instans orkestrasi baru. Secara internal, metode ini menulis pesan melalui penyedia penyimpanan Durable Functions lalu kembali. Pesan ini secara asinkron memicu dimulainya fungsi orkestrasi dengan nama yang ditentukan.

Parameter untuk memulai instans orkestrasi baru adalah sebagai berikut:

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 instance non-acak adalah ketika ID harus berasal dari sumber eksternal, yaitu saat Anda menerapkan pola orkestrator singleton.

Kode berikut adalah contoh fungsi yang 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 adalah untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient alih-alih DurableClient, dan Anda harus menggunakan tipe parameter DurableOrchestrationClient alih-alih IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antar versi, 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);
}

Jika Anda ingin menunggu orkestrator dimulai sebelum kembali dari fungsi Anda, Anda juga dapat menggunakan metodewaitForInstanceStart().

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

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Anda juga dapat memulai instans secara langsung dengan menggunakan func durable start-new perintah di Core Tools, yang mengambil parameter berikut:

function-name (wajib): Nama fungsi yang akan dimulai.
input (opsional): Input ke fungsi, baik sebaris atau melalui file JSON. Untuk file, tambahkan awalan pada jalur file dengan @, seperti @path/to/file.json.
id (opsional): ID instance orkestrasi. Jika Anda tidak menentukan parameter ini, perintah menggunakan GUID acak.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Anda juga dapat mengatur ini di host.json dengan menggunakan durableTask:HubName.

Nota

Perintah Core Tools mengasumsikan Anda menjalankannya dari direktori akar aplikasi fungsi. Jika Anda secara eksplisit menyediakan connection-string-setting parameter dan task-hub-name , Anda dapat menjalankan perintah dari direktori apa pun. Meskipun Anda dapat menjalankan perintah ini tanpa host aplikasi fungsi yang sedang berjalan, Anda mungkin menemukan bahwa Anda tidak dapat mengamati beberapa efek kecuali host aplikasi fungsi tersebut berjalan. Misalnya, perintah start-new mengantre pesan mulai ke hub tugas target, tetapi orkestrasi tidak benar-benar berjalan kecuali ada proses host aplikasi fungsi yang berjalan untuk memproses pesan.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah berikut memulai fungsi bernama HelloWorld, dan meneruskan konten file counter-data.json ke dalamnya:

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

Instans kueri

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

Metode get-status pada pengikatan klien orkestrasi memeriksa 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 akan 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 ketika orkestrasi terakhir kali melakukan checkpoint.
Input: Input fungsi sebagai nilai JSON. Bidang ini tidak diisi jika showInput salah.
CustomStatus: Status orkestrasi kustom dalam format JSON.
Output: Output fungsi sebagai nilai JSON (jika fungsi telah 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 telah dijadwalkan tetapi belum mulai berjalan.
- Berjalan: Instans telah mulai berjalan.
- Selesai: Instans telah selesai secara normal.
- ContinuedAsNew: Instans telah memulai ulang dirinya sendiri dengan riwayat baru. Status ini adalah status sementara.
- Gagal: Instans gagal dengan kesalahan.
- Dihentikan: Instance dihentikan dengan mendadak.
- Ditangguhkan: Instans telah dihentikan sementara dan dapat dilanjutkan kembali pada waktu yang akan datang.
Riwayat: Riwayat pelaksanaan orkestrasi. Bidang ini hanya diisi jika showHistory diatur ke true.

Nota

Orkestrator tidak ditandai sebagai Completed sampai semua tugas terjadwalnya selesai dan orkestrator telah kembali. Dengan kata lain, tidak cukup bagi orkestrator untuk mencapai pernyataannya return agar ditandai sebagai Completed. Ini sangat relevan untuk kasus di mana WhenAny digunakan; pengatur orkestrasi tersebut sering return sebelum semua tugas terjadwal 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: ...
}

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)

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

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Dimungkinkan juga untuk mendapatkan status instans orkestrasi secara langsung dengan menggunakan func durable get-runtime-status perintah di Core Tools.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable get-runtime-status mengambil parameter berikut:

id (wajib): ID instans orkestrasi.
show-input (opsional): Jika diatur ke true, respons berisi input fungsi. Nilai defaultnya adalah false.
show-output (opsional): Jika diatur ke true, respons berisi output fungsi. Nilai defaultnya adalah false.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

Perintah berikut mengambil status (termasuk input dan output) dari sebuah instans dengan ID instans orkestrasi 0ab8c55a6664d68a3a8b220b12d209c. Ini mengasumsikan bahwa Anda menjalankan perintah func dari direktori root aplikasi fungsi.

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

Anda dapat menggunakan durable get-history perintah untuk mengambil riwayat instans orkestrasi. Prosedur ini membutuhkan parameter berikut:

id (wajib): ID instans orkestrasi.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Melakukan kueri pada semua instance

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

Lihat Menjalankan instance untuk konfigurasi function.json.

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

Lihat Memulai instans untuk konfigurasi function.json.

@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 (Alat Inti Fungsi Azure)

Dimungkinkan juga untuk mengkueri instans secara langsung, dengan menggunakan func durable get-instances perintah di Core Tools.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable get-instances mengambil parameter berikut:

top (opsional): Perintah ini mendukung penelusuran halaman. Parameter ini sesuai dengan jumlah instans yang diperoleh per permintaan. Nilai default adalah 10.
continuation-token (opsional): Token untuk menunjukkan halaman atau bagian instans mana yang akan diambil. Setiap get-instances eksekusi mengembalikan token ke kumpulan instans berikutnya.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

func durable get-instances

Instans kueri dengan filter

Bagaimana jika Anda tidak benar-benar memerlukan semua informasi yang dapat diberikan kueri instans standar? Misalnya, bagaimana jika Anda hanya mencari waktu pembuatan orkestrasi, atau status waktu jalan orkestrasi? Anda bisa mempersempit 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 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));
    }
}

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

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Di Azure Functions Core Tools, Anda juga dapat menggunakan durable get-instances perintah dengan filter. Selain parameter top, continuation-token, connection-string-setting, dan task-hub-name yang disebutkan sebelumnya, Anda dapat menggunakan tiga parameter filter (created-after, created-before, dan runtime-status).

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Berikut ini adalah parameter untuk durable get-instances perintah .

created-after (opsional): Ambil instans yang dibuat setelah tanggal/waktu ini (UTC). Tanggalwaktu berformat ISO 8601 diterima.
created-before (opsional): Ambil instans yang dibuat sebelum tanggal/waktu (UTC) ini. Tanggalwaktu berformat ISO 8601 diterima.
runtime-status (opsional): Ambil instans dengan status tertentu (misalnya, berjalan atau selesai). Dapat menyediakan beberapa status (dipisahkan spasi).
top (opsional): Jumlah instance yang diambil setiap permintaan. Nilai default adalah 10.
continuation-token (opsional): Token untuk menunjukkan halaman atau bagian instans mana yang akan diambil. Setiap proses eksekusi get-instances mengembalikan token ke set instans berikutnya.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

Jika Anda tidak menyediakan filter apa pun (created-after, , created-beforeatau runtime-status), perintah hanya mengambil top instans, tanpa memperhatikan status runtime atau waktu pembuatan.

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

Mengakhiri instans

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

Dua parameter untuk API yang dihentikan adalah ID instans dan string alasan , yang ditulis 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);
}

Instans yang dihentikan pada akhirnya akan beralih ke status Terminated . Namun, transisi ini tidak akan segera terjadi. Sebaliknya, operasi penghentian akan 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 akan terus berjalan hingga selesai, terlepas dari apakah Anda telah menghentikan instans orkestrasi yang memanggilnya.

Menangguhkan dan Melanjutkan instance

Menangguhkan orkestrasi memungkinkan Anda menghentikan orkestrasi yang sedang berjalan. Tidak seperti penghentian, Anda memiliki opsi untuk memulai kembali orkestrator yang ditangguhkan di kemudian waktu.

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

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

Ketika orkestrator dilanjutkan setelah ditangguhkan, statusnya akan berubah kembali menjadi Running.

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Anda juga dapat mengakhiri instans orkestrasi secara langsung, dengan menggunakan func durable terminate perintah di Core Tools.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable terminate mengambil parameter berikut:

id (wajib): ID instans orkestrasi untuk dihentikan.
reason (opsional): Alasan penghentian.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

Perintah berikut mengakhiri instans orkestrasi dengan ID 0ab8c55a6664d68a3a8b220b12d209c:

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

Mengirim event ke instans

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

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

Parameter untuk peristiwa kenaikan adalah sebagai berikut:

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

Nota

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

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Anda juga dapat menaikkan peristiwa ke instans orkestrasi secara langsung, dengan menggunakan func durable raise-event perintah di Core Tools.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable raise-event mengambil parameter berikut:

id (wajib): ID instans orkestrasi.
event-name: Nama acara yang akan dinaikkan.
event-data (opsional): Data untuk dikirim ke instans orkestrasi. Ini bisa menjadi jalur ke file JSON, atau Anda dapat memberikan data langsung pada baris perintah.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Defaultnya adalah DurableFunctionsHub. Ini juga dapat diatur dalam host.json, dengan menggunakan durableTask:HubName.

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

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

Tunggu penyelesaian orkestrasi

Dalam orkestrasi yang berjalan lama, Anda mungkin ingin menunggu dan mendapatkan hasil orkestrasi. Dalam kasus ini, juga berguna untuk dapat menentukan periode batas waktu pada orkestrasi. Jika batas waktu telah terlampaui, status orkestrasi harus dikembalikan alih-alih mengembalikan hasilnya.

API "tunggu penyelesaian atau buat respons status pemeriksaan" dapat digunakan untuk mendapatkan output aktual dari instans orkestrasi secara sinkron. Secara default, metode ini memiliki batas waktu default 10 detik dan interval polling 1 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. Namun, dapat diimplementasikan menggunakan 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);
    }
}

Panggil fungsi dengan baris berikut. Gunakan 2 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 2 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.

Memperoleh URL webhook manajemen HTTP

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

API pembuatan payload manajemen HTTP memiliki satu parameter:

Instance ID: ID unik instance.

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 "tangguhkan" instans orkestrasi.
resumePostUri: URL melanjutkan instans orkestrasi.

Fungsi dapat mengirim instans objek ini ke sistem eksternal untuk memantau atau menaikkan peristiwa pada orkestrasi yang sesuai, seperti yang ditunjukkan dalam 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 adalah untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan DurableActivityContext alih-alih IDurableActivityContext, Anda harus menggunakan OrchestrationClient atribut alih-alih DurableClient atribut, dan Anda harus menggunakan DurableOrchestrationClient jenis parameter alih-alih IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antar versi, 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

Memutar kembali instans (pratinjau)

Jika Anda mengalami kegagalan orkestrasi karena alasan yang tidak terduga, Anda dapat memutar 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 kasus di mana instans orkestrasi gagal karena alasan yang tidak terduga. Orkestrasi dalam status selain Failed (misalnya, Running, Pending, Terminated, Completed) tidak dapat "diulang". Untuk informasi selengkapnya tentang penanganan kesalahan dan kebijakan coba lagi, lihat artikel Penanganan kesalahan .

RewindAsync Gunakan metode (.NET) atau rewind (JavaScript) dari pengikatan klien orkestrasi untuk menempatkan orkestrasi kembali ke status Berjalan. Metode ini juga akan menjalankan kembali aktivitas atau kegagalan eksekusi sub-orkestrasi yang menyebabkan kegagalan orkestrasi.

Misalnya, Anda memiliki alur kerja yang melibatkan serangkaian persetujuan manusia. Misalkan ada serangkaian fungsi aktivitas yang memberi tahu seseorang bahwa persetujuan mereka diperlukan, dan tunggu respons real-time. Setelah semua aktivitas persetujuan menerima respons atau waktu habis, misalkan aktivitas lain gagal karena kesalahan konfigurasi aplikasi, seperti string koneksi database yang tidak valid. Hasilnya adalah kegagalan orkestrasi jauh ke dalam alur kerja. RewindAsync Dengan API (.NET) atau rewind (JavaScript), administrator 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.

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Anda juga dapat mengulang kembali instans orkestrasi secara langsung dengan menggunakan perintah func durable rewind di Core Tools.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable rewind mengambil parameter berikut:

id (wajib): ID instans orkestrasi.
reason (opsional): Alasan untuk memutar balik instans orkestrasi.
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Secara default, nama hub tugas dalam file host.json digunakan.

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

Hapus riwayat instance

Untuk menghapus semua data yang terkait dengan orkestrasi, Anda dapat menghapus riwayat instans. Misalnya, Anda mungkin ingin menghapus sumber daya penyimpanan apa pun yang terkait dengan instans yang telah selesai. Untuk melakukannya, gunakan API hapus instans yang didefinisikan oleh klien orkestrasi.

Contoh pertama ini menunjukkan cara membersihkan instance orkestrasi tunggal.

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

Contoh berikutnya menunjukkan fungsi yang dipicu oleh timer untuk menghapus riwayat secara menyeluruh untuk semua instans orkestrasi yang telah selesai setelah interval 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()));
}

Nota

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

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Anda dapat menghapus riwayat instance orkestrasi dengan menggunakan perintah func durable purge-history di Core Tools. Mirip dengan contoh C# kedua di bagian sebelumnya, ini menghapus riwayat untuk semua instans orkestrasi yang dibuat selama interval waktu yang ditentukan. Anda selanjutnya dapat memfilter instans yang dibersihkan berdasarkan status runtime.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable purge-history memiliki beberapa parameter:

created-after (opsional): Hapus menyeluruh riwayat instans yang dibuat setelah tanggal/waktu (UTC) ini. Tanggalwaktu berformat ISO 8601 diterima.
created-before (opsional): Hapus menyeluruh riwayat instans yang dibuat sebelum tanggal/waktu (UTC) ini. Tanggalwaktu berformat ISO 8601 diterima.
runtime-status (opsional): Hapus menyeluruh riwayat instans dengan status tertentu (misalnya, berjalan atau selesai). Dapat menyediakan beberapa status (dipisahkan spasi).
connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Secara default, nama hub tugas dalam file host.json digunakan.

Perintah berikut menghapus riwayat semua instans yang gagal yang dibuat sebelum 14 November 2021 pukul 19.35 (UTC).

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

Menghapus hub tugas

func durable delete-task-hub Dengan menggunakan perintah di Core Tools, Anda dapat menghapus semua artefak penyimpanan yang terkait dengan hub tugas tertentu, termasuk tabel penyimpanan Azure, antrean, dan blob.

Nota

Perintah Core Tools saat ini hanya didukung saat menggunakan penyedia Azure Storage default untuk mempertahankan status runtime.

Perintah durable delete-task-hub memiliki dua parameter:

connection-string-setting (opsional): Nama pengaturan aplikasi yang berisi string koneksi penyimpanan yang akan digunakan. Defaultnya adalah AzureWebJobsStorage.
task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Secara default, nama hub tugas dalam file host.json digunakan.

Perintah berikut menghapus semua Azure penyimpanan data yang dihubungkan dengan hub tugas UserTest.

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

Langkah selanjutnya

Pelajari cara menangani penerapan versi

Referensi API HTTP bawaan untuk manajemen instans

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-06-28

Bagikan melalui

Mengelola instans di Durable Functions di Azure

Memulai instance

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Instans kueri

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Melakukan kueri pada semua instance

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Instans kueri dengan filter

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Mengakhiri instans

Menangguhkan dan Melanjutkan instance

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Mengirim event ke instans

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Tunggu penyelesaian orkestrasi

Memperoleh URL webhook manajemen HTTP

Memutar kembali instans (pratinjau)

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Hapus riwayat instance

Azure Functions Core Tools (Alat Inti Fungsi Azure)

Menghapus hub tugas

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: