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:
[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.
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 menjaditrue
, respons akan berisi riwayat eksekusi.showHistoryOutput
: Jika diatur menjaditrue
, riwayat eksekusi akan berisi output aktivitas.showInput
: Jika diatur menjadifalse
, respons tidak akan berisi input dari fungsi tersebut. Nilai defaultnya adalahtrue
.
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 menjaditrue
.
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.
[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.
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 menjaditrue
, respons akan berisi input fungsi. Nilai defaultnya adalahfalse
.show-output
(opsional): Jika diatur menjaditrue
, respons akan berisi output fungsi. Nilai defaultnya adalahfalse
.-
connection-string-setting
(opsional): Nama pengaturan aplikasi berisi string koneksi penyimpanan yang akan digunakan. Default adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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 adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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.
[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.
Azure Functions Core Tools
Anda juga dapat mengkueri instans secara langsung, dengan menggunakan perintah func durable get-instances
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 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 eksekusiget-instances
mengembalikan token ke kumpulan instans berikutnya. -
connection-string-setting
(opsional): Nama pengaturan aplikasi berisi string koneksi penyimpanan yang akan digunakan. Default adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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.
[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.
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 eksekusiget-instances
mengembalikan token ke kumpulan instans berikutnya. -
connection-string-setting
(opsional): Nama pengaturan aplikasi berisi string koneksi penyimpanan yang akan digunakan. Default adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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.
[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.
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.
[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);
}
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 adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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.
[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.
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 adalahAzureWebJobsStorage
. -
task-hub-name
(opsional): Nama hub tugas Durable Functions yang akan digunakan. Default adalahDurableFunctionsHub
. 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:
// 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));
}
}
}
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:
[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.
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
) Completed
tidak 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.
[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.
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 adalahAzureWebJobsStorage
. -
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.
[FunctionName("PurgeInstanceHistory")]
public static Task Run(
[DurableClient] IDurableOrchestrationClient client,
[QueueTrigger("purge-queue")] string instanceId)
{
return client.PurgeInstanceHistoryAsync(instanceId);
}
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:
[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.
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 adalahAzureWebJobsStorage
. -
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 adalahAzureWebJobsStorage
. -
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