Referensi API HTTP

Ekstensi Durable Functions mengekspos sekumpulan API HTTP bawaan yang dapat melakukan tugas manajemen pada orchestrations, entities, dan hub task. API HTTP ini adalah webhook ekstensibilitas yang diotorisasi host Azure Functions, tetapi ekstensi Durable Functions menangani secara langsung.

Sebelum menggunakan API HTTP ini, pastikan Anda memiliki:

Pemahaman dasar tentang konsep model pemrograman Tugas Tahan Lama (orkestrator, aktivitas, entitas)
Proyek Durable Functions diinisialisasi dengan pengikatan yang dikonfigurasi
Akses ke URL dasar aplikasi fungsi Anda, nama hub tugas, pengaturan koneksi, dan kunci otorisasi

URL Dasar dan parameter umum

Semua API HTTP berbagi URL dasar yang sama dengan aplikasi fungsi Anda. Saat Anda mengembangkan secara lokal menggunakan Azure Functions Core Tools, URL dasar biasanya http://localhost:7071. Dalam layanan yang dihosting Azure Functions, URL dasar biasanya https://{appName}.azurewebsites.net. Ekstensi ini juga mendukung nama host kustom jika dikonfigurasi di aplikasi App Service Anda.

Semua API HTTP yang diterapkan oleh ekstensi memerlukan parameter berikut. Jenis data dari semua parameter adalah string.

Parameter	Jenis Parameter	Description
`taskHub`	Rangkaian Kueri	Nama pusat tugas. Jika tidak ditentukan, nama hub tugas aplikasi fungsi saat ini diasumsikan.
`connection`	Rangkaian Kueri	Nama pengaturan aplikasi koneksi untuk penyedia penyimpanan backend. Jika tidak ditentukan, konfigurasi koneksi default untuk aplikasi fungsi diasumsikan.
`systemKey`	Rangkaian Kueri	Kunci otorisasi yang diperlukan untuk memanggil API.

Cara mendapatkan nilai parameter

Menggunakan pengikatan klien orkestrasi (disarankan): Hasilkan URL lengkap secara otomatis menggunakan API pengikatan klien orkestrasi :

.NET: CreateCheckStatusResponse(),CreateHttpManagementPayload()
JavaScript: createCheckStatusResponse(), createHttpManagementPayload()

Konstruksi URL manual:

taskHub: Diambil dari host.json file:
- v2.x: extensions.durableTask.hubName
- v1.x: durableTask.hubName
- Juga dapat dikonfigurasi melalui pengaturan aplikasi menggunakan %AppSettingName% sintaksis
connection: Nama pengaturan aplikasi yang berisi koneksi penyimpanan. Diambil dari host.json:
- v2.x: extensions.durableTask.storageProvider.connectionStringName (default ke AzureWebJobsStorage jika tidak ditentukan)
- v1.x: durableTask.azureStorageConnectionStringName (default ke AzureWebJobsStorage jika tidak ditentukan)
- Dapat menggunakan string koneksi atau koneksi berbasis identity (autentikasi Microsoft Entra)
systemKey: Kunci otorisasi khusus ekstensi untuk Durable Task API. Diambil dari portal Azure:
1. Buka Aplikasi Fungsi Anda
2. Pilih Fungsi → Kunci aplikasi di menu sebelah kiri
3. Di bawah bagian Kunci sistem, temukan kunci (biasanya dibuat secara otomatis untuk ekstensi)
4. Salin nilai kunci
️ Keamanan catatan: Kunci sistem memberikan akses ke semua API HTTP Durable Functions. Jangan bagikan secara publik atau sertakan dalam kode sisi klien.

Setiap API HTTP mendukung serangkaian pola permintaan/respons yang konsisten. Bagian berikut ini menyediakan informasi untuk setiap operasi.

Alur kerja API umum

Siklus hidup orkestrasi umum mengikuti urutan ini:

Mulai orkestrasi → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → Mengembalikan ID instans dan URL status
Periksa status → GET /runtime/webhooks/durabletask/instances/{instanceId} kemajuan Monitor →
Mengirim peristiwa (opsional) → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} → Mengirim sinyal eksternal
Membersihkan (opsional) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} riwayat Pembersihan →

Untuk detail operasi dan contoh permintaan/respons, lihat referensi di bawah ini.

Memulai orkestrasi

Memulai eksekusi instance baru dari fungsi orkestrator yang ditentukan.

Permintaan

Important

Format URL berbeda dengan versi runtime Functions. Pilih format yang cocok dengan lingkungan Anda.

Runtime Functions 2.x (disarankan):

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Runtime Functions 1.x (warisan):

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`functionName`	URL	Nama fungsi pengorkestrasi yang akan dimulai.
`instanceId`	URL	Parameter pilihan. ID instance orkestrasi. Jika tidak ditentukan, fungsi orkestrator dimulai dengan ID instans acak.
`{content}`	Meminta konten	Optional. Input fungsi orkestrator berformat JSON.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Fungsi orkestrator yang ditentukan dijadwalkan untuk mulai berjalan. Header respons Location berisi URL untuk memantau status orkestrasi.
HTTP 400 (Permintaan buruk): Fungsi orkestrator yang ditentukan tidak ada, ID instans yang ditentukan tidak valid, atau konten permintaan tidak valid JSON.

Berikut ini adalah contoh permintaan yang memulai RestartVMs fungsi orkestrator dan menyertakan payload objek JSON:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
}

Payload respons untuk kasus HTTP 202 adalah objek JSON dengan bidang berikut:

Ladang	Description
`id`	ID instance orkestrasi.
`statusQueryGetUri`	URL status instansi orkestrasi.
`sendEventPostUri`	URL dari instans orkestrasi untuk memicu acara.
`terminatePostUri`	URL "hentikan" instans orkestrasi.
`purgeHistoryDeleteUri`	URL "hapus riwayat" dari instans orkestrasi.
`rewindPostUri`	(pratinjau) URL "putar ulang" instans orkestrasi.
`suspendPostUri`	URL "tangguhkan" instans orkestrasi.
`resumePostUri`	URL "lanjutkan" dari instans orkestrasi.

Jenis data dari semua bidang adalah string.

Berikut adalah contoh payload respons untuk instans orkestrasi dengan abc123 sebagai ID-nya (diformat untuk keterbacaan):

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

Respons HTTP dimaksudkan agar kompatibel dengan Pola Konsumen Polling. Ini juga mencakup header respons penting berikut:

Lokasi: URL titik akhir status, yang berisi nilai yang sama dengan statusQueryGetUri bidang .
Coba Lagi-Setelah: Jumlah detik untuk menunggu di antara operasi polling. Nilai defaultnya adalah 10.

Untuk informasi selengkapnya tentang pola polling HTTP asinkron, lihat dokumentasi pelacakan operasi asinkron HTTP .

Mendapatkan status instance

Mendapatkan status instans orkestrasi tertentu. Gunakan ini untuk memantau kemajuan orkestrasi dan mengambil hasil.

Permintaan

Runtime Functions 2.x (disarankan):

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

Runtime Functions 1.x (warisan):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`showInput`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `false`, input fungsi tidak disertakan dalam payload respons.
`showHistory`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `true`, riwayat eksekusi orkestrasi disertakan dalam payload respons.
`showHistoryOutput`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `true`, output fungsi disertakan dalam riwayat eksekusi orkestrasi.
`createdTimeFrom`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau setelah tanda waktu ISO8601 yang diberikan.
`createdTimeTo`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau sebelum tanda waktu ISO8601 yang diberikan.
`runtimeStatus`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan berdasarkan status runtime mereka. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans .
`returnInternalServerErrorOnFailure`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `true`, API ini mengembalikan respons HTTP 500 alih-alih 200 jika instans dalam status kegagalan. Parameter ini ditujukan untuk skenario polling status otomatis.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 200 (OK): Instans yang ditentukan dalam keadaan selesai atau gagal.
HTTP 202 (Diterima): Instans yang ditentukan sedang berlangsung.
HTTP 400 (Permintaan Buruk): Instans yang ditentukan gagal atau dihentikan.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ada atau belum mulai berjalan.
HTTP 500 (Kesalahan Server Internal): Dikembalikan hanya ketika returnInternalServerErrorOnFailure diatur ke true dan instans yang ditentukan gagal dengan pengecualian yang tidak tertangani.

Payload respons untuk kasus HTTP 200 dan HTTP 202 adalah objek JSON dengan bidang berikut:

Ladang	Jenis data	Description
`runtimeStatus`	string	Status waktu jalan instans. Nilai termasuk Berjalan, Tertunda, Gagal, Dibatalkan, Dihentikan, Selesai, Ditangguhkan.
`input`	JSON	Data JSON yang digunakan untuk menginisialisasi instans. Bidang ini adalah `null` jika `showInput` parameter string kueri diatur ke `false`.
`customStatus`	JSON	Data JSON yang digunakan untuk status orkestrasi kustom. Bidang ini adalah `null` jika tidak diatur.
`output`	JSON	Output JSON dari instance. Bidang ini adalah `null` jika instansenya tidak berada dalam status selesai.
`createdTime`	string	Waktu saat instans dibuat. Menggunakan notasi yang diperluas ISO 8601.
`lastUpdatedTime`	string	Waktu di mana instans terakhir bertahan. Menggunakan notasi yang diperluas ISO 8601.
`historyEvents`	JSON	Array JSON yang berisi riwayat eksekusi orkestrasi. Bidang ini adalah `null` kecuali parameter string kueri `showHistory` diatur ke `true`.

Berikut adalah contoh payload respons termasuk riwayat eksekusi orkestrasi dan output aktivitas (diformat untuk keterbacaan):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

Respons HTTP 202 juga menyertakan header respons Lokasi yang mereferensikan URL yang sama dengan bidang yang statusQueryGetUri disebutkan sebelumnya.

Mendapatkan semua status instans

Mengkueri status beberapa instans orkestrasi sekaligus. Anda dapat memfilter hasil berdasarkan status, waktu pembuatan, dan awalan ID instans. Gunakan operasi ini untuk memantau semua orkestrasi aktif atau menemukan instans tertentu.

Permintaan

Runtime Functions 2.x (disarankan):

GET /runtime/webhooks/durabletask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

Runtime Functions 1.x (warisan):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`showInput`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `false`, input fungsi tidak disertakan dalam payload respons.
`showHistoryOutput`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `true`, sertakan output fungsi dalam riwayat eksekusi orkestrasi.
`createdTimeFrom`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau setelah tanda waktu ISO8601 yang diberikan.
`createdTimeTo`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau sebelum tanda waktu ISO8601 yang diberikan.
`runtimeStatus`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan berdasarkan status runtime mereka. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans .
`instanceIdPrefix`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang dikembalikan untuk hanya menyertakan instans yang ID instansnya dimulai dengan string awalan yang ditentukan. Tersedia dimulai dengan ekstensi versi 2.7.2 .
`top`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, membatasi jumlah instance yang dikembalikan oleh kueri.

Jawaban

Berikut adalah contoh payload respons termasuk status orkestrasi (diformat untuk keterbacaan):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Note

Operasi ini bisa mahal dalam hal I/O Azure Storage jika Anda menggunakan penyedia Azure Storage dan ada banyak baris dalam tabel Instans. Untuk informasi selengkapnya tentang tabel Instans, lihat dokumentasi penyedia Azure Storage.

Jika ada lebih banyak hasil, token kelanjutan dikembalikan di header respons. Nama header adalah x-ms-continuation-token.

Caution

Hasil kueri mungkin mengembalikan lebih sedikit item daripada batas yang ditentukan oleh top. Ketika Anda menerima hasil, Anda harus selalu memeriksa untuk melihat apakah ada token kelanjutan.

Jika Anda mengatur nilai token kelanjutan di header permintaan berikutnya, Anda bisa mendapatkan halaman hasil berikutnya. Nama header permintaan juga x-ms-continuation-token.

Membersihkan riwayat instans tunggal

Menghapus riwayat dan artefak terkait untuk instans orkestrasi tertentu. Operasi ini membebaskan sumber daya penyimpanan dan tidak dapat dibatalkan.

Permintaan

Runtime Functions 2.x (disarankan):

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Runtime Functions 1.x (warisan):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`instanceId`	URL	ID instance orkestrasi.

Jawaban

Nilai kode status HTTP berikut dapat dikembalikan.

HTTP 200 (OK): Riwayat instans berhasil dihapus menyeluruh.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ada.

Payload respons untuk kasus HTTP 200 adalah objek JSON dengan bidang berikut:

Ladang	Jenis data	Description
`instancesDeleted`	integer	Jumlah instans yang dihapus. Untuk kasus instans tunggal, nilai ini harus selalu `1`.

Berikut adalah contoh payload respons (diformat untuk keterbacaan):

{
    "instancesDeleted": 1
}

Menghapus riwayat beragam instans

Menghapus riwayat dan artefak untuk beberapa instans sekaligus, difilter berdasarkan status, waktu pembuatan, atau awalan ID instans. Gunakan ini untuk membersihkan instans lama secara massal dan mengelola biaya penyimpanan.

Permintaan

Runtime Functions 2.x (disarankan):

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Runtime Functions 1.x (warisan):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`createdTimeFrom`	Rangkaian Kueri	Memfilter daftar instans yang dibersihkan yang dibuat pada atau setelah tanda waktu ISO8601 yang diberikan.
`createdTimeTo`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar instans yang telah dihapus yang dibuat pada atau sebelum tanda waktu ISO8601 yang diberikan.
`runtimeStatus`	Rangkaian Kueri	Parameter pilihan. Ketika ditentukan, memfilter daftar instans yang telah dihapus berdasarkan status waktu jalannya. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans .

Note

Operasi ini bisa mahal dalam hal I/O Azure Storage jika Anda menggunakan penyedia Azure Storage dan ada banyak baris dalam tabel Instans atau Riwayat. Untuk informasi selengkapnya tentang tabel ini, lihat Performance dan skala dalam Durable Functions (Azure Functions).

Jawaban

Nilai kode status HTTP berikut dapat dikembalikan.

HTTP 200 (OK): Riwayat instans berhasil dihapus menyeluruh.
HTTP 404 (Tidak Ditemukan): Tidak ada instans yang ditemukan yang cocok dengan ekspresi filter.

Payload respons untuk kasus HTTP 200 adalah objek JSON dengan bidang berikut:

Ladang	Jenis data	Description
`instancesDeleted`	integer	Jumlah instans yang dihapus.

Berikut adalah contoh payload respons (diformat untuk keterbacaan):

{
    "instancesDeleted": 250
}

Ajukan acara

Mengirim pesan pemberitahuan peristiwa ke instans orkestrasi yang sedang berjalan. Orkestrasi harus menunggu peristiwa ini berdasarkan nama menggunakan WaitForExternalEvent atau wait_for_external_event.

Permintaan

Runtime Functions 2.x (disarankan):

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Runtime Functions 1.x (warisan):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`eventName`	URL	Nama acara yang sedang ditunggu oleh instans orkestrasi target.
`{content}`	Meminta konten	Payload peristiwa berformat JSON.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Peristiwa yang dinaikkan diterima untuk diproses.
HTTP 400 (Permintaan buruk): Konten permintaan tidak berjenis application/json atau bukan JSON yang valid.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ditemukan.
HTTP 410 (Hilang): Instans yang ditentukan telah selesai atau gagal dan tidak dapat memproses peristiwa yang dimunculkan.

Berikut adalah contoh permintaan yang mengirimkan string "incr" JSON ke instans yang menunggu peristiwa bernama operation:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

Respons untuk API ini tidak berisi konten apa pun.

Hentikan instans

Mengakhiri instans orkestrasi yang sedang berjalan.

Permintaan

Runtime Functions 2.x (disarankan):

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Runtime Functions 1.x (warisan):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut.

Ladang	Jenis Parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`reason`	Rangkaian Kueri	Optional. Alasan untuk mengakhiri instans orkestrasi.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Permintaan penghentian diterima untuk diproses.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ditemukan.
HTTP 410 (Hilang): Instans yang ditentukan telah selesai atau gagal.

Berikut adalah contoh permintaan yang mengakhiri instans yang sedang berjalan dan menentukan alasan buggy:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Respons untuk API ini tidak berisi konten apa pun.

Menangguhkan instance

Menjeda instans orkestrasi yang sedang berjalan tanpa mengakhirinya. Instans dapat dilanjutkan nanti menggunakan resume operasi.

Permintaan

Dalam runtime Functions versi 2.x, permintaan diformat sebagai berikut (beberapa baris ditampilkan untuk kejelasan):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Ladang	Jenis Parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`reason`	Rangkaian Kueri	Optional. Alasan untuk menangguhkan instans orkestrasi.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Permintaan yang ditangguhkan diterima untuk diproses. Tidak ada isi respons yang dikembalikan.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ditemukan.
HTTP 410 (Hilang): Instans yang ditentukan telah selesai, gagal, atau dihentikan dan tidak dapat ditangguhkan.

Verifikasi: Setelah menerima HTTP 202, kueri status instans menggunakan GET /runtime/webhooks/durabletask/instances/{instanceId} untuk memverifikasi bahwa runtimeStatus telah berubah menjadi "Suspended".

Melanjutkan instance

Melanjutkan eksekusi instans orkestrasi yang ditangguhkan sebelumnya.

Permintaan

Dalam runtime Functions versi 2.x, permintaan diformat sebagai berikut (beberapa baris ditampilkan untuk kejelasan):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Ladang	Jenis Parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`reason`	Rangkaian Kueri	Optional. Alasan untuk melanjutkan instans orkestrasi.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Permintaan resume diterima untuk diproses. Tidak ada isi respons yang dikembalikan.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ditemukan.
HTTP 410 (Hilang): Instans yang ditentukan telah selesai, gagal, atau dihentikan dan tidak dapat dilanjutkan.

Memundurkan instans (pratinjau)

Memulihkan instans orkestrasi yang gagal ke dalam kondisi berjalan dengan mengulangi operasi gagal terbaru. Fitur ini memungkinkan pemulihan dari kegagalan sementara tanpa intervensi manual.

Permintaan

Runtime Functions 2.x (disarankan):

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Runtime Functions 1.x (warisan):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut.

Ladang	Jenis Parameter	Description
`instanceId`	URL	ID instance orkestrasi.
`reason`	Rangkaian Kueri	Optional. Alasan untuk menggulung balik instans orkestrasi.

Jawaban

Beberapa kemungkinan nilai kode status dapat dikembalikan.

HTTP 202 (Diterima): Permintaan putar balik diterima untuk diproses.
HTTP 404 (Tidak Ditemukan): Instans yang ditentukan tidak ditemukan.
HTTP 410 (Hilang): Instans yang ditentukan telah selesai atau dihentikan.

Berikut adalah contoh permintaan yang memutar balik instans yang gagal dan menentukan alasan diperbaiki:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Respons untuk API ini tidak berisi konten apa pun.

Entitas sinyal

Mengirim pesan operasi satu arah ke Entitas Tahan Lama. Jika entitas tidak ada, entitas dibuat secara otomatis. Operasi entitas diproses secara berurutan dan bertahan lama.

Note

Entitas tahan lama tersedia mulai dari Durable Functions 2.0.

Permintaan

Permintaan HTTP diformat sebagai berikut (beberapa baris ditampilkan untuk kejelasan):

POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`entityName`	URL	Nama (jenis) entitas.
`entityKey`	URL	Kunci entitas (ID unik).
`op`	Rangkaian Kueri	Optional. Nama operasi yang ditentukan pengguna untuk dipanggil.
`{content}`	Meminta konten	Payload peristiwa berformat JSON.

Berikut adalah contoh permintaan yang mengirim pesan "Tambahkan" yang ditentukan pengguna ke Counter entitas bernama steps. Konten pesan adalah nilai 5. Jika entitas belum ada, permintaan ini akan membuatnya:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

Note

Secara default dengan entitas berbasis class di .NET, menentukan nilai opdelete menghapus status entitas. Namun, jika entitas menentukan operasi bernama delete, operasi yang ditentukan pengguna dipanggil sebagai gantinya.

Jawaban

Operasi ini memiliki beberapa kemungkinan respons:

HTTP 202 (Diterima): Operasi sinyal diterima untuk pemrosesan asinkron.
HTTP 400 (Permintaan buruk): Konten permintaan tidak berjenis application/json, bukan JSON yang valid, atau memiliki nilai yang tidak valid entityKey .
HTTP 404 (Tidak Ditemukan): Yang ditentukan entityName tidak ditemukan.

Permintaan HTTP yang berhasil tidak berisi konten apa pun dalam respons. Permintaan HTTP yang gagal mungkin berisi informasi kesalahan berformat JSON dalam konten respons.

Dapatkan entitas

Mendapatkan status entitas yang ditentukan.

Permintaan

Permintaan HTTP diformat sebagai berikut (beberapa baris ditampilkan untuk kejelasan):

GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Jawaban

Operasi ini memiliki dua kemungkinan respons:

HTTP 200 (OK): Entitas yang ditentukan ada.
HTTP 404 (Tidak Ditemukan): Entitas yang ditentukan tidak ditemukan.

Respons yang berhasil berisi status entitas yang diserialisasikan JSON sebagai kontennya.

Example

Untuk mendapatkan status entitas yang ada Counter bernama steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

Counter Jika entitas hanya berisi sejumlah langkah yang disimpan dalam bidangcurrentValue, konten respons mungkin terlihat seperti berikut ini (diformat untuk keterbacaan):

{
    "currentValue": 5
}

Daftar entitas

Anda dapat mengkueri beberapa entitas dengan nama entitas atau berdasarkan tanggal operasi terakhir.

Permintaan

Permintaan HTTP diformat sebagai berikut (beberapa baris ditampilkan untuk kejelasan):

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

Parameter permintaan untuk API ini mencakup set default yang disebutkan sebelumnya dan parameter unik berikut:

Ladang	Jenis parameter	Description
`entityName`	URL	Optional. Saat ditentukan, memfilter daftar entitas yang dikembalikan berdasarkan nama entitasnya (tidak peka huruf besar/kecil).
`fetchState`	Rangkaian Kueri	Parameter pilihan. Jika diatur ke `true`, status entitas disertakan dalam payload respons.
`lastOperationTimeFrom`	Rangkaian Kueri	Parameter pilihan. Jika ditentukan, memfilter daftar entitas yang dikembalikan yang memproses operasi setelah tanda waktu ISO8601 yang diberikan.
`lastOperationTimeTo`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, memfilter daftar entitas yang dikembalikan yang memproses operasi sebelum tanda waktu ISO8601 yang diberikan.
`top`	Rangkaian Kueri	Parameter pilihan. Saat ditentukan, membatasi jumlah entitas yang dikembalikan oleh kueri.

Jawaban

Respons HTTP 200 yang berhasil berisi array entitas berseri JSON dan secara opsional status setiap entitas.

Secara default, operasi mengembalikan 100 entitas pertama yang cocok dengan kriteria kueri. Pemanggil dapat menentukan nilai parameter string kueri untuk top mengembalikan jumlah hasil maksimum yang berbeda. Jika ada lebih banyak hasil di luar apa yang dikembalikan, token kelanjutan juga dikembalikan di header respons. Nama header adalah x-ms-continuation-token.

Jika Anda mengatur nilai token kelanjutan di header permintaan berikutnya, Anda bisa mendapatkan halaman hasil berikutnya. Nama header permintaan juga x-ms-continuation-token.

Contoh - mencantumkan semua entitas

Untuk mencantumkan semua entitas di hub tugas:

GET /runtime/webhooks/durabletask/entities

Respons JSON mungkin terlihat seperti berikut (diformat untuk keterbacaan):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

Contoh - memfilter daftar entitas

Untuk mencantumkan dua counter entitas pertama dan mengambil statusnya:

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

Respons JSON mungkin terlihat seperti berikut (diformat untuk keterbacaan):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

Contoh alur kerja lengkap

Contoh ini menunjukkan siklus hidup orkestrasi penuh menggunakan curl perintah. Anda juga dapat menggunakan Postman, Thunder Client, atau klien HTTP apa pun.

1. Memulai orkestrasi

Memulai orkestrasi baru ProcessOrder dengan data input:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/orchestrators/ProcessOrder" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "amount": 150.00
  }'

Respons (HTTP 202):

{
  "id": "abc123def456",
  "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX",
  "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/{eventName}?code=XXX",
  "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/terminate?reason={text}&code=XXX"
}

Simpan ID instans: abc123def456

2. Polling untuk status

Periksa kemajuan orkestrasi:

curl "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Respons saat berjalan (HTTP 202):

{
  "runtimeStatus": "Running",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": null,
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:05Z"
}

Respons ketika selesai (HTTP 200):

{
  "runtimeStatus": "Completed",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": { "status": "shipped", "trackingNumber": "TRK-98765" },
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:15Z"
}

3. Kirim peristiwa eksternal (opsional)

Jika orkestrasi menunggu persetujuan, kirim peristiwa persetujuan:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/ApprovalReceived?code=XXX" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true, "reviewer": "manager@contoso.com" }'

Respons: HTTP 202 (Diterima)

4. Bersihkan riwayat (opsional)

Setelah orkestrasi selesai, hapus menyeluruh riwayatnya:

curl -X DELETE "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Respons (HTTP 200):

{
  "instancesDeleted": 1
}

Langkah berikutnya

Pelajari cara menggunakan Application Insights untuk memantau fungsi tahan lama Anda

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-03

Referensi API HTTP

URL Dasar dan parameter umum

Cara mendapatkan nilai parameter

Alur kerja API umum

Memulai orkestrasi

Permintaan

Jawaban

Mendapatkan status instance

Permintaan

Jawaban

Mendapatkan semua status instans

Permintaan

Jawaban

Membersihkan riwayat instans tunggal

Permintaan

Jawaban

Menghapus riwayat beragam instans

Permintaan

Jawaban

Ajukan acara

Permintaan

Jawaban

Hentikan instans

Permintaan

Jawaban

Menangguhkan instance

Permintaan

Jawaban

Melanjutkan instance

Permintaan

Jawaban

Memundurkan instans (pratinjau)

Permintaan

Jawaban

Entitas sinyal

Permintaan

Jawaban

Dapatkan entitas

Permintaan

Jawaban

Example

Daftar entitas

Permintaan

Jawaban

Contoh - mencantumkan semua entitas

Contoh - memfilter daftar entitas

Contoh alur kerja lengkap

1. Memulai orkestrasi

2. Polling untuk status

3. Kirim peristiwa eksternal (opsional)

4. Bersihkan riwayat (opsional)

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: