Share via

Aplikasi terkelola Azure dengan pemberitahuan

  • Artikel

Pemberitahuan aplikasi terkelola Azure memungkinkan penerbit mengotomatiskan tindakan berdasarkan peristiwa siklus hidup instans aplikasi terkelola. Penerbit dapat menentukan titik akhir webhook pemberitahuan kustom agar menerima pemberitahuan kejadian terkait instans aplikasi terkelola baru dan yang sudah ada. Penerbit dapat menyiapkan alur kerja kustom pada saat penyediaan aplikasi, pembaruan, dan penghapusan.

Memulai

Untuk mulai menerima pemberitahuan aplikasi terkelola, buat titik akhir HTTPS publik. Tentukan titik akhir saat Anda menerbitkan definisi aplikasi katalog layanan atau penawaran Marketplace Microsoft Azure.

Berikut adalah langkah-langkah yang direkomendasikan untuk memulai dengan cepat:

  1. Buat titik akhir HTTPS publik yang mencatat permintaan POST yang masuk dan menampilkan 200 OK.
  2. Tambahkan titik akhir ke definisi aplikasi katalog layanan atau penawaran Marketplace Azure seperti yang dijelaskan kemudian di artikel ini.
  3. Buat instans aplikasi terkelola yang mereferensikan definisi aplikasi atau penawaran Marketplace Azure.
  4. Validasi bahwa pemberitahuan sedang diterima.
  5. Aktifkan otorisasi seperti yang dijelaskan di bagian Autentikasi titik akhir di artikel ini.
  6. Ikuti instruksi di bagian Skema pemberitahuan di artikel ini untuk memilah permintaan pemberitahuan dan menerapkan logika bisnis Anda berdasarkan pemberitahuan.

Menambahkan pemberitahuan definisi aplikasi katalog layanan

Contoh berikut menunjukkan cara menambahkan URI titik akhir pemberitahuan dengan menggunakan portal atau REST API.

Portal Azure

Untuk memulai, lihat Mulai Cepat: Membuat dan menerbitkan definisi Azure Managed Application.

Cuplikan layar portal Azure yang menunjukkan definisi aplikasi yang dikelola katalog layanan dan titik akhir pemberitahuan.

REST API

Catatan

Anda hanya dapat menyediakan satu titik akhir di properti notificationEndpoints pada definisi aplikasi terkelola.

{
  "properties": {
    "isEnabled": true,
    "lockLevel": "ReadOnly",
    "displayName": "Sample Application Definition",
    "description": "Notification-enabled application definition.",
    "notificationPolicy": {
      "notificationEndpoints": [
        {
            "uri": "https://isv.azurewebsites.net:1214?sig=unique_token"
        }
      ]
    },
    "authorizations": [
      {
        "principalId": "d6b7fbd3-4d99-43fe-8a7a-f13aef11dc18",
        "roleDefinitionId": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
      },
    ...

Menambahkan pemberitahuan aplikasi terkelola Marketplace Azure

Untuk informasi selengkapnya, lihat Membuat penawaran aplikasi Azure.

Cuplikan layar pemberitahuan aplikasi yang dikelola Marketplace Microsoft Azure di portal Azure.

Pemicu kejadian

Tabel berikut menjelaskan semua kemungkinan kombinasi eventType dan provisioningState sekaligus pemicunya:

EventType ProvisioningState Pemicu untuk pemberitahuan
TARUH Diterima Grup sumber daya terkelola telah dibuat dan diproyeksikan dengan sukses setelah aplikasi PUT (sebelum penyebaran di dalam grup sumber daya terkelola dimulai).
TARUH Berhasil Penyediaan penuh aplikasi terkelola berhasil setelah PUT.
TARUH Gagal Kegagalan PUT penyediaan instans aplikasi di titik mana saja.
PATCH Berhasil Setelah PATCH berhasil pada instans aplikasi terkelola untuk memperbarui tag, kebijakan akses JIT, atau identitas terkelola.
DELETE Menghapus Segera setelah pengguna memulai DELETE instans aplikasi terkelola.
DELETE Dihapus Setelah penghapusan keseluruhan dan sukses dari aplikasi terkelola.
DELETE Gagal Setelah kesalahan selama proses pencabutan akses yang memblokir penghapusan.

Skema pemberitahuan

Ketika Anda membuat titik akhir webhook Anda untuk menangani pemberitahuan, Anda harus mengurai payload agar mendapatkan properti penting untuk kemudian bertindak atas pemberitahuan yang diterima. Katalog layanan dan pemberitahuan aplikasi yang dikelola Marketplace Microsoft Azure menyediakan banyak properti yang sama, tetapi ada beberapa perbedaan pada properti tersebut. Properti applicationDefinitionId hanya berlaku untuk katalog layanan. Properti billingDetails dan plan hanya berlaku untuk Marketplace Microsoft Azure.

Azure menambahkan /resource ke URI titik akhir pemberitahuan yang telah Anda berikan dalam definisi aplikasi terkelola. Titik akhir webhook harus dapat menangani pemberitahuan pada URI /resource. Sebagai contohnya, jika Anda memberikan URI titik akhir pemberitahuan seperti https://fabrikam.com, URI titik akhir webhook adalah https://fabrikam.com/resource.

Skema pemberitahuan aplikasi katalog layanan

Sampel berikut menunjukkan pemberitahuan katalog layanan setelah berhasilnya penyediaan instans aplikasi terkelola.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>"
}

Jika penyediaan gagal, pemberitahuan dengan detail kesalahan akan dikirim ke titik akhir yang ditentukan.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>",
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}

Skema pemberitahuan aplikasi Marketplace Azure

Sampel berikut menunjukkan pemberitahuan katalog layanan setelah berhasilnya penyediaan instans aplikasi terkelola.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  }
}

Jika penyediaan gagal, pemberitahuan dengan detail kesalahan akan dikirim ke titik akhir yang ditentukan.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  },
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}
Properti Deskripsi
eventType Jenis peristiwa yang memicu pemberitahuan. (Misalnya, PUT, PATCH, DELETE.)
applicationId Pengidentifikasi sumber daya yang sepenuhnya memenuhi syarat dari aplikasi terkelola yang dipicu oleh pemberitahuan.
eventTime Tanda waktu peristiwa yang memicu pemberitahuan. (Tanggal dan waktu dalam format UTC ISO 8601.)
provisioningState Status penyediaan instans aplikasi terkelola. Contohnya Berhasil, Gagal, Menghapus, Dihapus.
applicationDefinitionId Hanya ditentukan untuk aplikasi terkelola katalog layanan. Mewakili pengidentifikasi sumber daya yang sepenuhnya memenuhi syarat dari definisi aplikasi tempat instans aplikasi terkelola disediakan.
billingDetails Hanya ditentukan untuk aplikasi yang dikelola Marketplace Azure. Detail penagihan instans aplikasi terkelola. Berisi resourceUsageId yang bisa Anda gunakan untuk mengkueri Marketplace Microsoft Azure untuk detail penggunaan.
plan Hanya ditentukan untuk aplikasi yang dikelola Marketplace Azure. Mewakili penerbit, penawaran, SKU, dan versi instans aplikasi terkelola.
error Ditentukan hanya ketika provisioningState gagal. Berisi kode kesalahan, pesan, dan detail masalah yang menyebabkan kegagalan.

Autentikasi titik akhir

Untuk mengamankan titik akhir webhook dan memastikan keaslian pemberitahuan:

  1. Sediakan parameter kueri di atas URI webhook, seperti: https://your-endpoint.com?sig=Guid. Dengan setiap pemberitahuan, periksa apakah parameter kueri sig memiliki nilai yang diharapkan Guid.
  2. Terbitkan GET pada instans aplikasi terkelola dengan menggunakan applicationId. Validasi bahwa provisioningState cocok dengan provisioningState pemberitahuan untuk memastikan konsistensi.

Pengambilan pemberitahuan

Layanan pemberitahuan aplikasi terkelola mengharapkan respons 200 OK dari titik akhir webhook ke pemberitahuan. Layanan pemberitahuan akan mencoba kembali jika titik akhir webhook menampilkan kode galat HTTP yang lebih besar atau sama dengan 500, jika menampilkan kode galat 429, atau jika titik akhir tidak dapat dijangkau untuk sementara waktu. Jika titik akhir webhook tidak tersedia dalam waktu 10 jam, pesan pemberitahuan akan dihilangkan dan upaya untuk mengulang akan berhenti.