Bagikan melalui

Lacak operasi Azure asinkron

  • Artikel

Beberapa operasi Azure REST berjalan secara asinkron karena operasi tidak dapat diselesaikan dengan cepat. Artikel ini menjelaskan cara melacak status operasi asinkron melalui nilai yang dikembalikan dengan respons.

Kode status untuk operasi asinkron

Operasi asinkron awalnya mengembalikan kode status HTTP baik itu:

  • 201 (Dibuat)
  • 202 (Diterima)

Namun, kode status itu tidak berarti operasinya adalah asinkron. Operasi asinkron juga mengembalikan nilai untuk provisioningState yang menunjukkan operasi belum selesai. Nilai dapat bervariasi menurut operasi tetapi tidak menyertakan Berhasil, Gagal, atau Dibatalkan. Ketiga nilai tersebut menunjukkan operasi selesai. Jika tidak ada nilai yang dikembalikan untuk provisioningState, operasi selesai dan berhasil.

Ketika operasi berhasil diselesaikan, operasi akan kembali baik itu:

  • 200 (OK)
  • 204 (Tidak Ada Konten)

Lihat dokumentasi REST API untuk melihat respons atas operasi yang Anda jalankan.

Setelah mendapatkan kode respons 201 atau 202, Anda siap untuk memantau status operasi.

URL untuk memantau status

Ada dua cara berbeda untuk memantau status operasi asinkron. Anda menentukan pendekatan yang benar dengan memeriksa nilai header yang dikembalikan dari permintaan asli Anda. Pertama, cari:

  • Azure-AsyncOperation - URL untuk memeriksa status operasi yang sedang berlangsung. Jika operasi Anda mengembalikan nilai ini, gunakan untuk melacak status operasi.
  • Retry-After - Jumlah detik untuk menunggu sebelum memeriksa status operasi asinkron.

Jika Azure-AsyncOperation bukan salah satu nilai header, lalu cari:

  • Location - URL untuk menentukan kapan operasi selesai. Gunakan nilai ini hanya jika Azure-AsyncOperation tidak dikembalikan.
  • Retry-After - Jumlah detik untuk menunggu sebelum memeriksa status operasi asinkron.

Retry-after Saat header tidak dikembalikan, terapkan logika coba lagi Anda sendiri.

Catatan

Klien REST Anda harus menerima ukuran URL minimum 4 KB untuk Azure-AsyncOperation dan Location.

Izin untuk melacak status asinkron

Untuk melacak status operasi asinkron, Anda memerlukan izin yang memadai di tingkat grup sumber daya. Jika Anda hanya memiliki izin di tingkat sumber daya, Anda dapat memulai operasi tetapi Anda tidak dapat melacak statusnya. Izin di tingkat grup sumber daya diperlukan karena URL untuk status pelacakan tidak terlingkup ke sumber daya.

Misalnya, untuk memulai komputer virtual, Anda memerlukan peran Kontributor Komputer Virtual untuk grup sumber daya yang berisi komputer virtual. URL untuk melacak permintaan mulai tidak menyertakan komputer virtual di jalurnya.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Permintaan dan respons Azure-AsyncOperation

Jika Anda memiliki URL dari nilai Azure-AsyncOperation header, kirim permintaan GET ke URL tersebut. Gunakan nilai dari Retry-After untuk menjadwalkan seberapa sering memeriksa status. Anda mendapatkan objek respons yang menunjukkan status operasi. Respons yang berbeda kembali saat memeriksa status operasi dengan Location URL. Untuk informasi selengkapnya tentang respons dari URL lokasi, lihat Buat akun penyimpanan (202 dengan Lokasi dan Coba Lagi Setelahnya).

Properti respons dapat bervariasi tetapi selalu menyertakan status operasi asinkron.

{
    "status": "{status-value}"
}

Contoh berikut ini memperlihatkan nilai lain yang mungkin kembali dari operasi:

{
    "id": "{resource path from GET operation}",
    "name": "{operation-id}",
    "status" : "Succeeded | Failed | Canceled | {resource provider values}",
    "startTime": "2017-01-06T20:56:36.002812+00:00",
    "endTime": "2017-01-06T20:56:56.002812+00:00",
    "percentComplete": {double between 0 and 100 },
    "properties": {
        /* Specific resource provider values for successful operations */
    },
    "error" : {
        "code": "{error code}",  
        "message": "{error description}"
    }
}

Objek kesalahan kembali ketika status Gagal atau Dibatalkan. Semua nilai lain bersifat opsional. Respons yang Anda terima mungkin terlihat berbeda dari contoh.

nilai provisioningState

Operasi yang membuat, memperbarui, atau menghapus (PUT, PATCH, DELETE) sumber daya biasanya mengembalikan nilai provisioningState. Saat operasi selesai, salah satu dari tiga nilai berikut dikembalikan:

  • Berhasil
  • Gagal
  • Dibatalkan

Semua nilai lain mengindikasikan operasi masih berjalan. Penyedia sumber daya dapat mengembalikan nilai yang dikustomisasi yang menunjukkan statusnya. Misalnya, Anda menerima Diterima saat permintaan diterima dan berjalan.

Contoh permintaan dan respons

Jalankan komputer virtual (202 dengan Azure-AsyncOperation)

Contoh ini menunjukkan cara menentukan status operasi mulai untuk komputer virtual. Permintaan awal dalam format berikut:

POST 
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2019-12-01

Ini mengembalikan kode status 202. Di antara nilai header, Anda akan melihat:

Azure-AsyncOperation : https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Untuk memeriksa status operasi asinkron, kirim permintaan lain ke URL tersebut.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Isi respons memuat status operasi:

{
  "startTime": "2017-01-06T18:58:24.7596323+00:00",
  "status": "InProgress",
  "name": "9a062a88-e463-4697-bef2-fe039df73a02"
}

Terapkan sumber daya (201 dengan Azure-AsyncOperation)

Contoh ini menunjukkan cara menentukan status operasi penyebaran untuk menerapkan sumber daya ke Azure. Permintaan awal dalam format berikut:

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/microsoft.resources/deployments/{deployment-name}?api-version=2020-06-01

Ini mengembalikan kode status 201. Isi respons meliputi:

"provisioningState":"Accepted",

Di antara nilai header, Anda akan melihat:

Azure-AsyncOperation: https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Untuk memeriksa status operasi asinkron, kirim permintaan lain ke URL tersebut.

GET 
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Isi respons memuat status operasi:

{
    "status": "Running"
}

Setelah penyebaran selesai, respons berisi:

{
    "status": "Succeeded"
}

Buat akun penyimpanan (202 dengan Lokasi dan Coba Lagi-Setelah)

Contoh ini menunjukkan cara menentukan status operasi buat untuk akun penyimpanan. Permintaan awal dalam format berikut:

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-name}?api-version=2019-06-01

Dan isi permintaan memuat properti untuk akun penyimpanan:

{
    "location": "South Central US",
    "properties": {},
    "sku": {
        "name": "Standard_LRS"
    },
    "kind": "Storage"
}

Ini mengembalikan kode status 202. Di antara nilai header, Anda akan melihat dua nilai berikut ini:

Location: https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01
Retry-After: 17

Setelah menunggu jumlah detik yang ditentukan dalam Coba Lagi-Setelah, periksa status operasi asinkron dengan mengirim permintaan lain ke URL tersebut.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01

Jika permintaan masih berjalan, Anda akan menerima kode status 202. Jika permintaan selesai, Anda akan menerima kode status 200. Isi respons berisi properti akun penyimpanan yang dibuat.

Langkah berikutnya