Referensi API HTTP

  • Artikel

Ekstensi Durable Functions memaparkan kumpulan API HTTP bawaan yang dapat digunakan untuk melakukan tugas manajemen pada orkestrasi, entitas, dan hub tugas. API HTTP ini adalah webhook ekstensibilitas yang diotorisasi oleh host Azure Functions tetapi ditangani langsung oleh ekstensi Durable Functions.

URL dasar untuk API yang disebutkan dalam artikel ini sama dengan URL dasar untuk aplikasi fungsi Anda. Saat mengembangkan secara lokal menggunakan Azure Functions Core Tools, URL dasar biasanya adalah http://localhost:7071. Dalam layanan yang dihosting Azure Functions, URL dasar biasanya adalah https://{appName}.azurewebsites.net. Nama host kustom juga didukung 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 Deskripsi
taskHub Untai kueri Nama hub tugas. Jika tidak ditentukan, nama hub tugas aplikasi fungsi saat ini diasumsikan.
connection Untai kueri Nama pengaturan aplikasi koneksi untuk penyedia penyimpanan backend. Jika tidak ditentukan, konfigurasi koneksi default untuk aplikasi fungsi diasumsikan.
systemKey Untai kueri Kunci otorisasi yang diperlukan untuk memanggil API.

systemKey adalah kunci otorisasi yang dibuat secara otomatis oleh host Azure Functions. Ini secara khusus memberikan akses ke API ekstensi Durable Task dan dapat dikelola dengan cara yang sama seperti kunci akses Azure Functions lainnya. Anda dapat membuat URL yang berisi nilai string kueri taskHub, connection, dan systemKey yang benar menggunakan API pengikatan klien orkestrasi, seperti API CreateCheckStatusResponse dan CreateHttpManagementPayload di .NET, atau API createCheckStatusResponse dan createHttpManagementPayload dalam JavaScript dll.

Beberapa bagian berikutnya mencakup API HTTP tertentu yang didukung oleh ekstensi dan memberikan contoh bagaimana API HTTP tertentu dapat digunakan.

Mulai orkestrasi

Mulai menjalankan instans baru dari fungsi orkestrator yang ditentukan.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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

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

Bidang Jenis parameter Deskripsi
functionName URL Nama fungsi orkestrator untuk memulai.
instanceId URL Parameter opsional. ID instans orkestrasi. Jika tidak ditentukan, fungsi orkestrator akan dimulai dengan ID instans acak.
{content} Minta konten Opsional. Input fungsi orkestrator berformat JSON.

Respons

Beberapa nilai kode status yang mungkin dapat dikembalikan.

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

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

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

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

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

Bidang Deskripsi
id ID instans orkestrasi.
statusQueryGetUri URL status instans orkestrasi.
sendEventPostUri URL "tingkatkan peristiwa" dari instans orkestrasi.
terminatePostUri URL "hentikan" dari instans orkestrasi.
purgeHistoryDeleteUri URL "hapus menyeluruh riwayat" dari instans orkestrasi.
rewindPostUri (pratinjau) URL "gulung balik" dari instans orkestrasi.
suspendPostUri URL "tangguhkan" instans orkestrasi.
resumePostUri URL "lanjutkan" instans orkestrasi.

Jenis data 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 Poling. Hal ini juga termasuk header respons penting berikut:

  • Lokasi: URL titik akhir status. URL ini berisi nilai yang sama dengan bidang statusQueryGetUri.
  • Coba lagi Setelah: Jumlah detik untuk menunggu di antara operasi poling. Nilai defaultnya adalah 10.

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

Dapatkan status instans

Mendapatkan status instans orkestrasi tertentu.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

GET /runtime/webhooks/durabletask/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 serta parameter unik berikut:

Bidang Jenis parameter Deskripsi
instanceId URL ID instans orkestrasi.
showInput Untai kueri Parameter opsional. Jika diatur ke false, input fungsi tidak akan disertakan dalam payload respons.
showHistory Untai kueri Parameter opsional. Jika diatur ke true, riwayat eksekusi orkestrasi akan disertakan dalam payload respons.
showHistoryOutput Untai kueri Parameter opsional. Jika diatur ke true, output fungsi akan disertakan dalam riwayat eksekusi orkestrasi.
createdTimeFrom Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau setelah tanda waktu ISO8601 diberikan.
createdTimeTo Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau sebelum tanda waktu ISO8601 diberikan.
runtimeStatus Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan berdasarkan status runtime mereka. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans.
returnInternalServerErrorOnFailure Untai kueri Parameter opsional. Jika diatur ke true, API ini akan mengembalikan respons HTTP 500, bukan 200 jika instans dalam status kegagalan. Parameter ini dimaksudkan untuk skenario poling status otomatis.

Respons

Beberapa nilai kode status yang mungkin dapat dikembalikan.

  • HTTP 200 (OK): Instans yang ditentukan dalam status 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): Hanya dikembalikan saat 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:

Bidang Jenis data Deskripsi
runtimeStatus string Status runtime instans. Nilai mencakup Menjalankan, Tertunda, Gagal, Dibatalkan, Dihentikan, Selesai, Ditangguhkan.
input JSON Data JSON digunakan untuk menginisialisasi instans. Bidang ini adalah null jika parameter untai (karakter) kueri showInput diatur ke false.
customStatus JSON Data JSON digunakan untuk status orkestrasi kustom. Bidang ini adalah null jika tidak diatur.
output JSON Output JSON dari instans. Bidang ini adalah null jika instans tidak dalam status selesai.
createdTime string Waktu di mana instans dibuat. Menggunakan notasi diperpanjang ISO 8601.
lastUpdatedTime string Waktu di mana instans terakhir bertahan. Menggunakan notasi diperpanjang ISO 8601.
historyEvents JSON Array JSON yang berisi riwayat eksekusi orkestrasi. Bidang ini adalah null kecuali parameter untai (karakter) 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 statusQueryGetUri yang disebutkan sebelumnya.

Dapatkan status semua instans

Anda juga dapat mengkueri status semua instans dengan menghapus permintaan instanceId dari 'Dapatkan status instans'. Dalam kasus ini, parameter dasar sama dengan 'Dapatkan status instans'. Parameter untai (karakter) kueri untuk pemfilteran juga didukung.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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}

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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}

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

Bidang Jenis parameter Deskripsi
showInput Untai kueri Parameter opsional. Jika diatur ke false, input fungsi tidak akan disertakan dalam payload respons.
showHistoryOutput Untai kueri Parameter opsional. Jika diatur ke true, output fungsi akan disertakan dalam riwayat eksekusi orkestrasi.
createdTimeFrom Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau setelah tanda waktu ISO8601 diberikan.
createdTimeTo Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan yang dibuat pada atau sebelum tanda waktu ISO8601 diberikan.
runtimeStatus Untai kueri Parameter opsional. Ketika ditentukan, memfilter daftar instans yang dikembalikan berdasarkan status runtime mereka. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans.
instanceIdPrefix Untai kueri Parameter opsional. Jika ditentukan, filter daftar instans yang ditampilkan untuk menyertakan hanya instans dengan id instans yang dimulai dengan string awalan yang ditentukan. Tersedia mulai dari versi 2.7.2 ekstensi.
top Untai kueri Parameter opsional. Saat ditentukan, membatasi jumlah instans yang dikembalikan oleh kueri.

Respons

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

Catatan

Operasi ini bisa sangat mahal dalam hal I/O Azure Storage jika Anda menggunakan penyedia Azure Storage default dan jika ada banyak baris dalam tabel Instans. Detail selengkapnya tentang tabel Instans dapat ditemukan di dokumentasi penyedia Azure Storage.

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

Perhatian

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

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

Menghapus menyeluruh riwayat instans tunggal

Menghapus riwayat dan artefak terkait instans orkestrasi tertentu.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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

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

Bidang Jenis parameter Deskripsi
instanceId URL ID instans orkestrasi.

Respons

Nilai kode status HTTP berikut ini dapat dikembalikan.

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

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

Bidang Jenis data Deskripsi
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 menyeluruh beberapa riwayat instans

Anda juga dapat menghapus riwayat dan artefak terkait untuk beberapa instans dalam hub tugas dengan menghapus permintaan {instanceId} dari 'Hapus menyeluruh riwayat instans tunggal'. Untuk menghapus menyeluruh riwayat instans secara selektif, gunakan filter yang sama dengan yang dijelaskan dalam permintaan 'Dapatkan semua status instans'.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

DELETE /runtime/webhooks/durabletask/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 serta parameter unik berikut:

Bidang Jenis parameter Deskripsi
createdTimeFrom Untai kueri Memfilter daftar instans yang dihapus menyeluruh yang dibuat pada atau setelah tanda waktu ISO8601 diberikan.
createdTimeTo Untai kueri Parameter opsional. Saat ditentukan, memfilter daftar instans yang dihapus menyeluruh yang dibuat pada atau sebelum tanda waktu ISO8601 diberikan.
runtimeStatus Untai kueri Parameter opsional. Saat ditentukan, memfilter daftar instans yang dihapus menyeluruh berdasarkan status runtime mereka. Untuk melihat daftar kemungkinan nilai status runtime, lihat artikel Mengkueri instans.

Catatan

Operasi ini bisa sangat mahal dalam hal I/O Azure Storage jika Anda menggunakan penyedia Azure Storage default dan jika ada banyak baris dalam tabel Instans dan/atau tabel Histori. Detail lebih lanjut tentang tabel tersebut dapat ditemukan di dokumentasi Performa dan skala di Durable Functions (Azure Functions).

Respons

Nilai kode status HTTP berikut ini dapat dikembalikan.

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

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

Bidang Jenis data Deskripsi
instancesDeleted Integer Jumlah instans yang dihapus.

Berikut adalah contoh payload respons (diformat untuk keterbacaan):

{
    "instancesDeleted": 250
}

Tingkatkan peristiwa

Mengirim pesan notifikasi kejadian ke instans orkestrasi yang sedang berjalan.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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

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

Bidang Jenis parameter Deskripsi
instanceId URL ID instans orkestrasi.
eventName URL Nama peristiwa yang ditunggu-tunggu oleh instans orkestrasi target.
{content} Minta konten Payload peristiwa berformat JSON.

Respons

Beberapa nilai kode status yang mungkin dapat dikembalikan.

  • HTTP 202 (Diterima): Peristiwa yang ditingkatkan diterima untuk diproses.
  • HTTP 400 (Permintaan buruk): Konten permintaan tidak berdasarkan jenis 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 diangkat.

Berikut adalah contoh permintaan yang mengirim untai (karakter) JSON "incr" ke instans yang menunggu peristiwa bernama operasi:

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.

Menghentikan instans

Menghentikan instans orkestrasi yang sedang berjalan.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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

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

Bidang Jenis Parameter Deskripsi
instanceId URL ID instans orkestrasi.
reason Untai kueri Opsional. Alasan untuk mengakhiri instans orkestrasi.

Respons

Beberapa nilai kode status yang mungkin 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 menghentikan instans yang 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 instans

Menangguhkan instans orkestrasi yang sedang berjalan.

Permintaan

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Bidang Jenis Parameter Deskripsi
instanceId URL ID instans orkestrasi.
reason Untai kueri Opsional. Alasan untuk menangguhkan instans orkestrasi.

Beberapa nilai kode status yang mungkin dapat dikembalikan.

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

Respons untuk API ini tidak berisi konten apa pun.

Melanjutkan instans

Melanjutkan instans orkestrasi yang ditangguhkan.

Permintaan

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Bidang Jenis Parameter Deskripsi
instanceId URL ID instans orkestrasi.
reason Untai kueri Opsional. Alasan untuk melanjutkan instans orkestrasi.

Beberapa nilai kode status yang mungkin dapat dikembalikan.

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

Respons untuk API ini tidak berisi konten apa pun.

Gulung balik instans (pratinjau)

Memulihkan instans orkestrasi yang gagal ke dalam status sedang berjalan dengan memutar ulang operasi yang gagal terbaru.

Permintaan

Untuk versi 1.x dari runtime Functions, permintaan diformat sebagai berikut (beberapa baris ditunjukkan untuk kejelasan):

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

Dalam versi 2.x dari runtime Functions, format URL memiliki semua parameter yang sama tetapi dengan awalan yang sedikit berbeda:

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

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

Bidang Jenis Parameter Deskripsi
instanceId URL ID instans orkestrasi.
reason Untai kueri Opsional. Alasan untuk memutar mundur cepat instans orkestrasi.

Respons

Beberapa nilai kode status yang mungkin dapat dikembalikan.

  • HTTP 202 (Diterima): Permintaan gulung 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 mundur cepat 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 tersebut akan dibuat secara otomatis.

Catatan

Entitas yang tahan lama tersedia mulai dari Durable Functions 2.0.

Permintaan

Permintaan HTTP diformat sebagai berikut (beberapa baris ditunjukkan 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 serta parameter unik berikut:

Bidang Jenis parameter Deskripsi
entityName URL Nama (jenis) entitas.
entityKey URL Kunci (ID unik) entitas.
op Untai kueri Opsional. Nama operasi yang ditentukan pengguna untuk dipanggil.
{content} Minta 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 dari 5. Jika entitas belum ada, entitas akan dibuat oleh permintaan ini:

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

5

Catatan

Secara default dengan entitas berbasis kelas di .NET, menetapkan nilai op dari delete yang akan menghapus status suatu entitas. Namun, jika entitas menentukan operasi bernama delete, operasi yang ditentukan pengguna akan dipanggil sebagai gantinya.

Respons

Operasi ini memiliki beberapa kemungkinan respons:

  • HTTP 202 (Diterima): Operasi sinyal diterima untuk pemrosesan asinkron.
  • HTTP 400 (Permintaan buruk): Konten permintaan tidak berdasarkan jenis application/json, bukan JSON yang valid, atau memiliki nilai entityKey yang tidak valid.
  • HTTP 404 (Tidak ditemukan): Yang ditentukan entityName tidak dapat 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 ditunjukkan untuk kejelasan):

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

Respons

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 dari entitas sebagai kontennya.

Contoh

Contoh permintaan HTTP berikut mendapatkan status entitas yang ada Counter bernama steps:

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

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

{
    "currentValue": 5
}

Entitas daftar

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

Permintaan

Permintaan HTTP diformat sebagai berikut (beberapa baris ditunjukkan 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 serta parameter unik berikut:

Bidang Jenis parameter Deskripsi
entityName URL Opsional. Saat ditentukan, memfilter daftar entitas yang dikembalikan berdasarkan nama entitas mereka (tidak peka huruf besar/kecil).
fetchState Untai kueri Parameter opsional. Jika diatur ke true, status entitas akan disertakan dalam payload respons.
lastOperationTimeFrom Untai kueri Parameter opsional. Saat ditentukan, memfilter daftar entitas yang dikembalikan yang memproses operasi setelah tanda waktu ISO8601 diberikan.
lastOperationTimeTo Untai kueri Parameter opsional. Saat ditentukan, memfilter daftar entitas yang dikembalikan yang memproses operasi sebelum stempel waktu ISO8601 yang diberikan.
top Untai kueri Parameter opsional. Saat ditentukan, membatasi jumlah entitas yang dikembalikan oleh kueri.

Respons

Respons HTTP 200 yang sukses berisi array entitas yang diserialisasikan JSON dan secara opsional status masing-masing entitas.

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

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

Contoh - daftar semua entitas

Contoh permintaan HTTP berikut mencantumkan semua entitas di hub tugas:

GET /runtime/webhooks/durabletask/entities

Respons JSON mungkin terlihat seperti berikut ini (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

Contoh permintaan HTTP berikut hanya mencantumkan dua entitas pertama dari jenis counter dan juga mengambil statusnya:

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

Respons JSON mungkin terlihat seperti berikut ini (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 }
    }
]

Langkah berikutnya

Pelajari cara menggunakan Application Insights untuk memantau fungsi tahan lama Anda