Mengelola instans di Durable Functions di Azure

Orkestrasi di Durable Functions adalah fungsi stateful jangka panjang yang dapat dimulai, dikueri, ditangguhkan, dilanjutkan, dan dihentikan menggunakan API manajemen bawaan. Beberapa API manajemen instans lainnya juga diekspos oleh pengikatan klien orkestrasi Durable Functions, seperti mengirim peristiwa eksternal ke instans, menghapur riwayat instans, dll. Artikel ini masuk ke detail semua operasi manajemen instans yang didukung.

Memulai instans

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 dan kemudian 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: Semua data yang dapat diserialkan JSON yang harus diteruskan sebagai input ke fungsi orkestrator.
• InstanceId: (Opsional) ID unik instans. Jika Anda tidak menentukan parameter ini, metode ini akan menggunakan ID acak.

Tip

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

Kode berikut adalah fungsi contoh yang memulai instans orkestrasi baru:

C#

[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
    [QueueTrigger("start-queue")] string input,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

Kecuali ditentukan, contoh di halaman ini menggunakan pemicu HTTP dengan function.json. berikut.

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
}

Catatan

Contoh ini menargetkan Durable Functions version 2.x. Di versi 1.x, gunakan orchestrationClient bukan durableClient.

index.js

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

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

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

Python

Kecuali ditentukan, contoh di halaman ini menggunakan pemicu HTTP dengan function.json. berikut.

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
}

Catatan

Contoh ini menargetkan Durable Functions version 2.x. Di versi 1.x, gunakan orchestrationClient bukan durableClient.

__init__.py

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

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

PowerShell

Kecuali ditentukan, contoh di halaman ini menggunakan pemicu HTTP dengan function.json. berikut.

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
}

Catatan

Contoh ini menargetkan Durable Functions version 2.x. Di versi 1.x, gunakan orchestrationClient bukan durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

Java

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

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

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

Azure Functions Core Tools

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

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

Catatan

Perintah Core Tools menganggap Anda menjalankannya dari direktori akar aplikasi fungsi. Jika Anda secara eksplisit memberikan parameter connection-string-setting dan task-hub-name, perintah dapat dijalankan dari direktori apa pun. Meskipun perintah ini dapat dijalankan tanpa host aplikasi fungsi yang berjalan, Anda mungkin menemukan bahwa beberapa efek tidak dapat diamati kecuali host tersebut berjalan. Misalnya, perintah start-new memasukkan pesan awal ke dalam hub tugas target, tetapi orkestrasi tidak benar-benar berjalan kecuali ada proses host aplikasi fungsi yang berjalan yang dapat memproses pesan tersebut.

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

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

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

Mengkueri instans

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

Metode get-status pada pengikatan klien orkestrasi menanyakan status instans orkestrasi.

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

• showHistory: Jika diatur menjadi true, respons akan berisi riwayat eksekusi.
• showHistoryOutput: Jika diatur menjadi true, riwayat eksekusi akan berisi output aktivitas.
• showInput: Jika diatur menjadi false, respons tidak akan berisi input dari fungsi tersebut. Nilai defaultnya adalah true.

Metode ini mengembalikan objek dengan properti berikut:

• Nama: Nama fungsi orkestrator.
• InstanceId: ID instans orkestrasi (harus sama dengan input instanceId).
• CreatedTime: Waktu pada saat fungsi orchestrator mulai berjalan.
• LastUpdatedTime: Waktu pada kali terakhir orkestrasi berada di titik pemeriksaan.
• 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 akan menyertakan detail kegagalan. Jika fungsi orkestrator ditangguhkan atau dihentikan, properti ini akan menyertakan alasan penangguhan atau penghentian (jika ada).
• RuntimeStatus: Salah satu nilai berikut:
  • Tertunda: Instans telah dijadwalkan tetapi belum mulai berjalan.
  • Berjalan: Instance telah berjalan.
  • Selesai:Instans telah selesai dengan lancar.
  • ContinuedAsNew:Instans telah dihidupkan ulang sendiri dengan riwayat baru. Status ini bersifat sementara.
  • Gagal: Instans mengalami kegagalan dengan kesalahan.
  • Dihentikan: Instans dihentikan secara tiba-tiba.
  • Ditangguhkan: Instans ditangguhkan dan dapat dilanjutkan di lain waktu.
• Riwayat: Riwayat eksekusi orkestrasi. Bidang ini hanya diisi jika showHistory diatur menjadi true.

Catatan

Orkestrator tidak akan ditandai sebagai Completed hingga semua tugas terjadwal telah selesai dan orkestrator telah kembali. Dengan kata lain, tidak cukup bagi orkestrator untuk mencapai pernyataan return agar dapat ditandai sebagai Completed. Hal ini khususnya relevan untuk kasus di mana WhenAny digunakan; orkestra tersebut sering return sebelum semua tugas terjadwal dijalankan.

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

C#

[FunctionName("GetStatus")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("check-status-queue")] string instanceId)
{
    DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

Azure Functions Core Tools

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

Catatan

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

Perintah durable get-runtime-status mengambil parameter berikut:

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

Perintah berikut mengambil status (termasuk input dan output) instans dengan ID instans orkestrasi 0ab8c55a66644d68a3a8b220b12d209c. Anda akan dianggap menjalankan perintah func dari direktori akar aplikasi fungsi:

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

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

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

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Mengkueri semua instans

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.

C#

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var noFilter = new OrchestrationStatusQueryCondition();
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        noFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
    
    // Note: ListInstancesAsync only returns the first page of results.
    // To request additional pages provide the result.ContinuationToken
    // to the OrchestrationStatusQueryCondition's ContinuationToken property.
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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


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

    instances = await client.get_status_all()

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

Lihat Memulai instans untuk konfigurasi function.json.

PowerShell

Catatan

Fitur ini saat ini tidak didukung di PowerShell, tetapi dapat dicapai menggunakan API HTTP Durable Functions.

Java

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

Azure Functions Core Tools

Anda juga dapat mengkueri instans secara langsung, dengan menggunakan perintah func durable get-instancesatau di Core Tools.

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable get-instances mengambil parameter berikut:

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

func durable get-instances

Mengkueri instans dengan filter

Bagaimana jika Anda tidak benar-benar membutuhkan semua informasi yang dapat disediakan oleh kueri instans standar? Misalnya, bagaimana jika Anda hanya mencari waktu pembuatan orkestrasi, atau status runtime orkestrasi? Anda dapat mempersempit kueri dengan menerapkan filter.

C#

[FunctionName("QueryStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    // Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };
    
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

PowerShell

Catatan

Fitur ini saat ini tidak didukung di PowerShell, tetapi dapat dicapai menggunakan API HTTP Durable Functions.

Java

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

Azure Functions Core Tools

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

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Berikut ini adalah parameter untuk perintah durable get-instances.

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

Jika Anda tidak menyediakan filter apa pun (created-after, created-before, atau runtime-status), perintah hanya mengambil instans top 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

Menghentikan 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 menghentikannya.

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

C#

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

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Java

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

Instans yang dihentikan pada akhirnya akan mengalami transisi ke status Terminated. Namun, transisi ini tidak akan terjadi dengan segera. Sebaliknya, operasi penghentian akan dimasukkan ke dalam antrean 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.

Catatan

Penghentian instans saat ini tidak disebarluaskan. Fungsi aktivitas dan sub-orkestrasi berjalan hingga selesai, terlepas dari apakah Anda telah menghentikan instans orkestrasi yang memanggilnya.

Menangguhkan dan Melanjutkan instans

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

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

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
    await context.CreateTimer(dueTime, CancellationToken.None);
    
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

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

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

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

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

Python

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

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

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

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

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

Java

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

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

    String resumeReason = "Continue workflow";
    client.getClient().resumeInstance(instanceID, resumeReason);
}

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

Ketika orkestrator yang ditangguhkan dilanjutkan, statusnya akan berubah kembali ke Running.

Azure Functions Core Tools

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

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable terminate mengambil parameter berikut:

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

Perintah berikut menghentikan instans orkestrasi dengan ID 0ab8c55a66644d68a3a8b220b12d209c:

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

Mengirim peristiwa ke instans

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

Anda dapat mengirim pemberitahuan peristiwa ke instans yang sedang berjalan dengan menggunakan API raise event dari klien orkestrasi. Orkestrasi dapat mendengarkan dan merespons peristiwa ini menggunakan tunggu API orkestrator peristiwa eksternal.

Parameter untuk peristiwa kenaikan adalah sebagai berikut:

• InstanceId: ID unik instans.
• EventName: Nama peristiwa yang akan dikirim.
• EventData: Payload JSON-serializable untuk dikirim ke instans.

C#

[FunctionName("RaiseEvent")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("event-queue")] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Java

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

Catatan

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

Azure Functions Core Tools

Anda juga dapat meningkatkan kejadian menjadi contoh orkestrasi secara langsung, dengan menggunakan perintah func durable raise-event atau di Core Tools.

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable raise-event mengambil parameter berikut:

• id (wajib): ID instans orkestrasi.
• event-name: Nama peristiwa yang akan dinaikkan.
• event-data (opsional): Data yang akan dikirim ke instans orkestrasi. Ini dapat menjadi jalur ke file JSON, atau Anda dapat menyediakan data langsung di baris perintah.
• connection-string-setting (opsional): Nama pengaturan aplikasi berisi string koneksi penyimpanan yang akan digunakan. Default adalah AzureWebJobsStorage.
• task-hub-name (opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalah DurableFunctionsHub. Ini juga dapat diatur di 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

Menunggu penyelesaian orkestrasi

Dalam orkestrasi jangka panjang, Anda mungkin ingin menunggu dan mendapatkan hasil dari orkestrasi. Dalam kasus ini, juga berguna untuk dapat menentukan periode waktu habis di orkestrasi. Jika waktu habis terlampaui, status orkestrasi harus dikembalikan bukan 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:

C#

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace VSSample
{
    public static class HttpSyncStart
    {
        private const string Timeout = "timeout";
        private const string RetryInterval = "retryInterval";

        [FunctionName("HttpSyncStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
            HttpRequestMessage req,
            [DurableClient] IDurableOrchestrationClient starter,
            string functionName,
            ILogger log)
        {
            // Function input comes from the request content.
            object eventData = await req.Content.ReadAsAsync<object>();
            string instanceId = await starter.StartNewAsync(functionName, eventData);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

            TimeSpan timeout = GetTimeSpan(req, Timeout) ?? TimeSpan.FromSeconds(30);
            TimeSpan retryInterval = GetTimeSpan(req, RetryInterval) ?? TimeSpan.FromSeconds(1);
            
            return await starter.WaitForCompletionOrCreateCheckStatusResponseAsync(
                req,
                instanceId,
                timeout,
                retryInterval);
        }

        private static TimeSpan? GetTimeSpan(HttpRequestMessage request, string queryParameterName)
        {
            string queryParameterStringValue = request.RequestUri.ParseQueryString()[queryParameterName];
            if (string.IsNullOrEmpty(queryParameterStringValue))
            {
                return null;
            }

            return TimeSpan.FromSeconds(double.Parse(queryParameterStringValue));
        }
    }
}

JavaScript

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

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

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

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

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Catatan

PowerShell saat ini tidak memiliki perintah bawaan untuk skenario ini.

Java

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 waktu habis dan 0,5 detik untuk interval mencoba kembali:

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

Catatan

Perintah cURL di atas mengasumsikan Anda memiliki fungsi orkestrator bernama E1_HelloSequence dalam proyek Anda. Karena cara 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, terdapat dua kasus:

• Instans orkestrasi selesai dalam batas waktu yang ditentukan (dalam hal ini, 2 detik), dan responsnya adalah output instans orkestrasi aktual, disampaikan 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!"
]

• Instance orkestrasi tidak dapat diselesaikan dalam batas waktu yang ditentukan, dan responsnya adalah respons 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}"
}

Catatan

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

Mengambil 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 sebagai alternatif dapat diakses secara terprogram menggunakan pengikatan klien orkestrasi. Secara khusus, API payload manajemen HTTP buat dapat digunakan untuk mendapatkan objek yang dapat diserialisasikan yang berisi URL webhook ini.

API buat payload manajemen HTTP memiliki satu parameter:

• InstanceId: ID unik instans.

Metode ini mengembalikan objek dengan properti string berikut:

• Id: ID instans orkestrasi (harus sama dengan input InstanceId).
• StatusQueryGetUri: URL status dari instans orkestrasi.
• SendEventPostUri: URL "naikkan peristiwa" dari instans orkestrasi.
• TerminatePostUri: URL "hentikan" dari instans orkestrasi.
• PurgeHistoryDeleteUri: URL "hapus menyeluruh riwayat" dari instans orkestrasi.
• suspendPostUri: URL "ditangguhkan" dari instans orkestrasi.
• resumePostUri: URL "dilanjutkan" dari instans orkestrasi.

Fungsi dapat mengirim instans objek ini ke sistem eksternal untuk memantau atau menaikkan peristiwa di orkestrasi terkait, seperti yang ditunjukkan dalam contoh berikut:

C#

[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
    [ActivityTrigger] IDurableActivityContext ctx,
    [DurableClient] IDurableOrchestrationClient client,
    [CosmosDB(
        databaseName: "MonitorDB",
        containerName: "HttpManagementPayloads",
        Connection = "CosmosDBConnectionSetting")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Azure Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan DurableActivityContext bukan IDurableActivityContext, atribut OrchestrationClient bukan DurableClient, dan jenis parameter DurableOrchestrationClient bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

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

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

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

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

Java

Catatan

Fitur ini saat ini tidak didukung di Java.

Menggulung balik instans (pratinjau)

Jika terjadi kegagalan orkestrasi karena alasan yang tidak terduga, Anda dapat menggulung balik instans ke status sehat sebelumnya dengan menggunakan API yang dibuat untuk tujuan tersebut.

Catatan

API ini tidak dimaksudkan sebagai pengganti untuk penanganan kesalahan yang tepat dan kebijakan coba lagi. Sebaliknya, API ini dimaksudkan untuk digunakan hanya dalam kasus saat instans orkestrasi mengalami gagal karena alasan yang tidak terduga. Orkestrasi dalam status selain Failed (misalnya, Running, , Pending, Terminated) Completedtidak boleh "diulang". Untuk informasi selengkapnya tentang penanganan kesalahan dan kebijakan coba lagi, lihat artikel Penanganan kesalahan.

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

Misalnya, anggap Anda memiliki alur kerja yang melibatkan serangkaian persetujuan manusia. Anggap ada serangkaian fungsi aktivitas yang memberi tahu seseorang bahwa persetujuan mereka diperlukan, dan menunggu respons secara real time. Setelah semua aktivitas persetujuan menerima respons atau waktu habis, anggap aktivitas lain gagal karena kesalahan konfigurasi aplikasi, seperti string koneksi database yang tidak valid. Hasilnya adalah kegagalan orkestrasi jauh ke dalam alur kerja. Dengan API RewindAsync (.NET) atau rewind (JavaScript), administrator aplikasi dapat memperbaiki kesalahan konfigurasi, dan menggulung balik orkestrasi yang gagal kembali ke status segera sebelum terjadi kegagalan. Tidak ada langkah interaksi manusia yang perlu disetujui kembali, dan orkestrasi kini dapat diselesaikan dengan lancar.

Catatan

Fitur gulung balik tidak mendukung penggulungan balik instans orkestrasi yang menggunakan timer tahan lama.

C#

[FunctionName("RewindInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("rewind-queue")] string instanceId)
{
    string reason = "Orchestrator failed and needs to be revived.";
    return client.RewindAsync(instanceId, reason);
}

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

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

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

Catatan

Untuk saat ini, fitur ini tidak didukung di Python.

PowerShell

Catatan

Fitur ini saat ini tidak didukung di PowerShell.

Java

Catatan

Fitur ini saat ini tidak didukung di Java.

Azure Functions Core Tools

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

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable rewind mengambil parameter berikut:

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

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

Menghapus menyeluruh riwayat instans

Untuk menghapus semua data yang terkait dengan orkestrasi, Anda dapat menghapus menyeluruh riwayat instans. Misalnya, Anda mungkin ingin menghapus semua sumber daya penyimpanan yang terkait dengan instans yang telah selesai. Untuk melakukannya, gunakan API instans penghapusan menyeluruh yang ditentukan oleh klien orkestrasi.

Contoh pertama ini menunjukkan cara menghapus menyeluruh satu instans orkestrasi.

C#

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

JavaScript

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

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

Lihat Memulai instans untuk konfigurasi function.json.

Python

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Catatan

Fitur ini saat ini tidak didukung di PowerShell, tetapi dapat dicapai menggunakan API HTTP Durable Functions.

Java

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

Contoh berikutnya menunjukkan fungsi yang dipicu timer yang menghapus menyeluruh riwayat untuk semua instans orkestrasi yang selesai setelah interval waktu yang ditentukan. Dalam hal ini, fungsi ini akan menghapus data untuk semua instans yang selesai 30 hari atau lebih yang lalu. Contoh fungsi ini dijadwalkan untuk berjalan sekali per hari, pada 24.00 UTC:

C#

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

Catatan

Kode C# sebelumnya ditujukan untuk Durable Functions 2.x. Untuk Durable Functions 1.x, Anda harus menggunakan atribut OrchestrationClient, bukan atribut DurableClient, dan jenis parameter DurableOrchestrationClient, bukan IDurableOrchestrationClient. Untuk informasi selengkapnya tentang perbedaan antara versi, lihat artikel Versi Durable Functions.

JavaScript

Metode purgeInstanceHistoryBy ini dapat digunakan untuk menghapus menyeluruh 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
}

Catatan

Contoh ini menargetkan Durable Functions version 2.x. Di versi 1.x, gunakan orchestrationClient bukan durableClient.

index.js

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

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

PowerShell

Catatan

Fitur ini saat ini tidak didukung di PowerShell, tetapi dapat dicapai menggunakan API HTTP Durable Functions.

Python

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

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

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

Java

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

Catatan

Agar operasi hapus menyeluruh riwayat berhasil, status runtime dari instans target harus Selesai, Dihentikan, atau Gagal.

Azure Functions Core Tools

Anda dapat menghapus menyeluruh riwayat instans orkestrasi dengan menggunakan perintah func durable purge-history atau di Core Tools. Serupa dengan contoh C# kedua di bagian sebelumnya, fungsi ini akan menghapus menyeluruh riwayat untuk semua instans orkestrasi yang dibuat selama interval waktu yang ditentukan. Anda dapat memfilter instans yang dihapus menyeluruh lebih lanjut berdasarkan status runtime.

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable purge-history memiliki beberapa parameter:

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

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

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

Menghapus hub tugas

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

Catatan

Perintah Alat Inti saat ini hanya didukung saat menggunakan penyedia Microsoft Azure Storage default untuk status runtime yang bertahan.

Perintah durable delete-task-hub memiliki dua parameter:

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

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

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

Langkah berikutnya

Pelajari cara menangani penerapan versi

Referensi API HTTP bawaan untuk manajemen instans