Menerima peristiwa perubahan Microsoft Graph API melalui Azure Event Grid (pratinjau)

  • Artikel

Artikel ini akan menjelaskan langkah-langkah untuk berlangganan peristiwa yang diterbitkan oleh Microsoft Graph API. Tabel berikut mencantumkan sumber peristiwa tempat peristiwa tersedia melalui Graph API. Untuk sebagian besar sumber daya, peristiwa yang mengumumkan pembuatan, pembaruan, dan penghapusannya didukung. Untuk informasi terperinci tentang sumber daya tempat peristiwa dinaikkan untuk sumber peristiwa, lihat sumber daya yang didukung oleh pemberitahuan perubahan Microsoft Graph API .

Penting

Kemampuan Microsoft Graph API untuk mengirim peristiwa ke Azure Event Grid saat ini dalam pratinjau publik. Jika Anda memiliki pertanyaan atau memerlukan dukungan, kirim email kepada kami di ask-graph-and-grid@microsoft.com.

Sumber kejadian Microsoft Tipe kejadian yang tersedia
Microsoft Entra ID Jenis peristiwa Microsoft Entra
Microsoft Outlook Jenis kejadian Microsoft Outlook
Percakapan grup Microsoft 365
Microsoft Teams Jenis kejadian Microsoft Teams
Microsoft SharePoint dan OneDrive
Microsoft SharePoint
Peringatan keamanan
Microsoft Conversations
Microsoft Universal Print

Penting

Jika Anda belum memahami fitur Peristiwa Mitra, lihat Ringkasan Peristiwa Mitra.

Mengapa saya harus berlangganan peristiwa dari sumber Microsoft Graph API melalui Event Grid?

Selain kemampuan untuk berlangganan peristiwa Microsoft Graph API melalui Event Grid, Anda memiliki opsi lain di mana Anda dapat menerima pemberitahuan serupa (bukan peristiwa). Pertimbangkan untuk menggunakan Microsoft Graph API untuk mengirimkan peristiwa ke Event Grid jika Anda memiliki sedikitnya salah satu persyaratan berikut:

  • Anda mengembangkan solusi berbasis peristiwa yang memerlukan peristiwa dari ID Microsoft Entra, Outlook, Teams, dll. untuk bereaksi terhadap perubahan sumber daya. Anda memerlukan model peristiwa yang kuat dan kemampuan terbitkan-berlangganan yang disediakan Event Grid. Untuk ringkasan Event Grid, lihat Konsep Event Grid.
  • Anda ingin menggunakan Event Grid untuk merutekan peristiwa ke beberapa tujuan menggunakan satu langganan API Graph dan Anda ingin menghindari pengelolaan beberapa langganan API Graph.
  • Anda harus merutekan peristiwa ke aplikasi hilir, webhook, atau layanan Azure yang berbeda tergantung pada beberapa properti dalam peristiwa tersebut. Misalnya, Anda mungkin ingin merutekan jenis peristiwa seperti Microsoft.Graph.UserCreated dan Microsoft.Graph.UserDeleted ke aplikasi khusus yang memproses onboarding dan off-boarding pengguna. Anda mungkin juga ingin mengirim Microsoft.Graph.UserUpdated peristiwa ke aplikasi lain yang menyinkronkan informasi kontak, misalnya. Anda dapat mencapainya menggunakan satu langganan API Graph saat menggunakan Event Grid sebagai tujuan pemberitahuan. Untuk informasi selengkapnya, lihat pemfilteran peristiwa dan penanganan aktivitas.
  • Interoperabilitas sangat penting untuk Anda. Anda ingin meneruskan dan menangani peristiwa dengan cara standar menggunakan standar spesifikasi CloudEvents CNCF.
  • Anda menyukai dukungan ekstensibilitas yang disediakan CloudEvents. Misalnya, jika Anda ingin melacak peristiwa di seluruh sistem yang sesuai, gunakan ekstensi CloudEvents Distributed Tracing. Pelajari selengkapnya tentang ekstensi CloudEvents lainnya.
  • Anda ingin menggunakan pendekatan berbasis peristiwa yang terbukti yang diadopsi oleh industri.

Mengaktifkan peristiwa Graph API untuk mengalir ke topik mitra Anda

Anda meminta Microsoft Graph API untuk meneruskan peristiwa ke topik mitra Event Grid dengan membuat langganan Graph API menggunakan Microsoft Graph API SDK dan mengikuti langkah-langkah dalam tautan ke sampel yang disediakan di bagian ini. Lihat Bahasa yang didukung untuk Microsoft Graph API SDK untuk dukungan SDK yang tersedia.

Prasyarat umum

Anda harus memenuhi prasyarat umum ini sebelum menerapkan aplikasi Anda untuk membuat dan memperbarui langganan Microsoft Graph API:

  • Kenali langkah-langkah tingkat tinggi untuk berlangganan peristiwa mitra. Seperti yang dijelaskan dalam artikel tersebut, sebelum membuat langganan Graph API, Anda harus mengikuti instruksi di:

  • Memiliki pengetahuan kerja tentang pemberitahuan Microsoft Graph API. Sebagai bagian dari pembelajaran, Anda dapat menggunakan Graph API Explorer untuk membuat langganan Graph API.

  • Memahami konsep Peristiwa Mitra.

  • Identifikasi sumber daya Microsoft Graph API tempat Anda ingin menerima peristiwa perubahan status sistem. Lihat Pemberitahuan perubahan Microsoft Graph API untuk informasi selengkapnya. Misalnya, untuk melacak perubahan pada pengguna di MICROSOFT Entra ID, Anda harus menggunakan sumber daya pengguna . Gunakan grup untuk melacak perubahan pada grup pengguna.

  • Memiliki akun administrator penyewa di penyewa Microsoft 365. Anda bisa mendapatkan penyewa pengembangan secara gratis dengan bergabung dengan Program Pengembang Microsoft 365.

Anda akan menemukan prasyarat lain khusus untuk bahasa pemrograman pilihan dan lingkungan pengembangan yang Anda gunakan di tautan sampel Microsoft Graph API yang ditemukan di bagian mendatang.

Penting

Meskipun instruksi terperinci untuk mengimplementasikan aplikasi Anda ditemukan di bagian sampel dengan instruksi terperinci, Anda harus membaca semua bagian dalam artikel ini karena berisi informasi penting tambahan yang terkait dengan penerusan peristiwa Microsoft Graph API menggunakan Event Grid.

Cara membuat langganan Microsoft Graph API

Saat Anda membuat langganan Graph API, topik mitra dibuat untuk Anda. Anda meneruskan informasi berikut dalam notificationUrl parameter untuk menentukan topik mitra apa yang akan dibuat dan dikaitkan dengan langganan Graph API baru:

  • nama topik mitra
  • nama grup sumber daya tempat topik mitra dibuat
  • wilayah (lokasi)
  • Langganan Azure

Sampel kode ini menunjukkan kepada Anda cara membuat langganan Graph API. Mereka menunjukkan contoh untuk membuat langganan untuk menerima peristiwa dari semua pengguna di penyewa ID Microsoft Entra saat dibuat, diperbarui, atau dihapus.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted,Created",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType: jenis perubahan sumber daya yang ingin Anda terima peristiwanya. Nilai yang valid: Updated, Deleted, dan Created. Anda dapat menentukan satu atau beberapa nilai ini yang dipisahkan oleh koma.
  • notificationUrl: URI yang digunakan untuk menentukan topik mitra tempat peristiwa dikirim. Ini harus sesuai dengan pola berikut: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>. Lokasi (juga dikenal sebagai wilayah Azure) name dapat diperoleh dengan menjalankan perintah az account list-locations . Jangan gunakan nama tampilan lokasi. Misalnya, jangan gunakan "BARAT Tengah AS". Gunakan westcentralus sebagai gantinya. 
      az account list-locations
  • lifecycleNotificationUrl: URI yang digunakan untuk menentukan topik mitra tempat microsoft.graph.subscriptionReauthorizationRequiredperistiwa dikirim. Kejadian ini menandakan aplikasi Anda bahwa langganan Graph API akan segera kedaluwarsa. URI mengikuti pola yang sama seperti notificationUrl yang dijelaskan di atas jika menggunakan Event Grid sebagai tujuan peristiwa siklus hidup. Dalam hal ini, topik mitra harus sama dengan yang ditentukan dalam notificationUrl.
  • sumber daya: sumber daya yang menghasilkan peristiwa yang mengumumkan perubahan status.
  • expirationDateTime: waktu kedaluwarsa saat langganan kedaluwarsa dan alur peristiwa berhenti. Ini harus sesuai dengan format yang ditentukan dalam RFC 3339. Anda harus menentukan waktu kedaluwarsa yang berada dalam panjang langganan maksimum yang diizinkan per jenis sumber daya.
  • status klien. Properti ini bersifat opsional. Ini digunakan untuk verifikasi panggilan ke aplikasi penanganan aktivitas Anda selama pengiriman peristiwa. Untuk informasi selengkapnya, lihat Properti langganan API Graph.

Penting

  • Nama topik mitra harus unik dalam wilayah Azure yang sama. Setiap kombinasi ID aplikasi penyewa dapat membuat hingga 10 topik mitra yang unik.

  • Perhatikan batas layanan sumber daya API Graph tertentu saat mengembangkan solusi Anda.

  • Langganan Graph API yang lifecycleNotificationUrl ada tanpa properti tidak menerima peristiwa siklus hidup. Untuk menambahkan properti lifecycleNotificationUrl, Anda harus menghapus langganan yang ada dan membuat langganan baru yang menentukan properti selama pembuatan langganan.

Catatan

Jika aplikasi Anda menggunakan header x-ms-enable-features dengan permintaan Anda untuk membuat langganan Graph API selama pratinjau privat, Anda harus menghapusnya karena tidak lagi diperlukan.

Setelah membuat langganan Graph API, Anda memiliki topik mitra yang dibuat di Azure.

Memperpanjang langganan Microsoft Graph API

Langganan Graph API harus diperbarui oleh aplikasi Anda sebelum kedaluwarsa untuk menghindari penghentian alur peristiwa. Untuk membantu Anda mengotomatiskan proses perpanjangan, Microsoft Graph API mendukung peristiwa pemberitahuan siklus hidup tempat aplikasi Anda dapat berlangganan. Saat ini, semua jenis sumber daya Microsoft Graph API mendukung microsoft.graph.subscriptionReauthorizationRequired, yang dikirim ketika salah satu kondisi berikut terjadi:

  • Token akses akan kedaluwarsa.
  • Langganan Graph API akan kedaluwarsa.
  • Administrator penyewa telah mencabut izin aplikasi Anda untuk membaca sumber daya.

Jika Anda tidak memperbarui langganan Graph API setelah kedaluwarsa, Anda perlu membuat langganan Graph API baru. Anda dapat merujuk ke topik mitra yang sama dengan yang Anda gunakan dalam langganan kedaluwarsa selama telah kedaluwarsa selama kurang dari 30 hari. Jika langganan Graph API telah kedaluwarsa selama lebih dari 30 hari, Anda tidak dapat menggunakan kembali topik mitra yang ada. Dalam hal ini, Anda harus menentukan nama topik mitra lain. Atau, Anda dapat menghapus topik mitra yang ada untuk membuat topik mitra baru dengan nama yang sama selama pembuatan langganan Graph API.

Cara memperbarui langganan Microsoft Graph API

Setelah menerima microsoft.graph.subscriptionReauthorizationRequired peristiwa, aplikasi Anda harus memperbarui langganan Graph API dengan melakukan tindakan ini:

  1. Jika Anda memberikan rahasia klien di properti clientState saat membuat langganan Graph API, rahasia klien tersebut disertakan dengan peristiwa tersebut. Validasi bahwa clientState peristiwa cocok dengan nilai yang digunakan saat Anda membuat langganan Graph API.

  2. Pastikan bahwa aplikasi memiliki token akses yang valid untuk mengambil langkah berikutnya. Informasi selengkapnya disediakan di bagian sampel yang akan datang dengan instruksi terperinci.

  3. Panggil salah satu dari dua API berikut. Jika panggilan API berhasil, alur pemberitahuan perubahan akan dilanjutkan.

    • /reauthorize Panggil tindakan untuk mengotorisasi ulang langganan tanpa memperpanjang tanggal kedaluwarsanya.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • Lakukan tindakan "perbarui" reguler untuk mengotorisasi ulang dan memperbarui langganan secara bersamaan.

      PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-Type: application/json

{
   "expirationDateTime": "2024-04-30T11:00:00.0000000Z"
}

      Perpanjangan mungkin gagal jika aplikasi tidak lagi berwenang untuk mengakses sumber daya. Kemudian mungkin perlu bagi aplikasi untuk mendapatkan token akses baru agar berhasil mengotorisasi ulang langganan.

Tantangan otorisasi tidak menggantikan kebutuhan untuk memperbarui langganan sebelum kedaluwarsa. Siklus hidup token akses dan kedaluwarsa langganan tidak sama. Token akses Anda mungkin kedaluwarsa sebelum langganan Anda. Penting untuk disiapkan untuk secara teratur mengotorisasi ulang titik akhir Anda untuk me-refresh token akses Anda. Mengotorisasi ulang titik akhir Anda tidak akan memperbarui langganan Anda. Namun, memperpanjang langganan Anda juga akan mengotorisasi ulang titik akhir Anda.

Saat memperbarui dan/atau mengotorisasi ulang langganan Graph API Anda, topik mitra yang sama yang ditentukan saat langganan dibuat digunakan.

Saat Menentukan expirationDateTime baru, setidaknya harus tiga jam dari waktu saat ini. Jika tidak, aplikasi Anda mungkin akan menerima microsoft.graph.subscriptionReauthorizationRequired peristiwa segera setelah perpanjangan.

Untuk contoh tentang cara mengotorisasi ulang langganan Graph API Anda menggunakan salah satu bahasa yang didukung, lihat permintaan otorisasi ulang langganan.

Untuk contoh tentang cara memperbarui dan mengotorisasi ulang langganan Graph API Anda menggunakan salah satu bahasa yang didukung, lihat memperbarui permintaan langganan..

Sampel dengan instruksi terperinci

Dokumentasi Microsoft Graph API menyediakan sampel kode dengan instruksi untuk:

  • Siapkan lingkungan pengembangan Anda dengan instruksi tertentu sesuai dengan bahasa yang Anda gunakan. Instruksi juga mencakup cara mendapatkan penyewa Microsoft 365 untuk tujuan pengembangan.
  • Buat langganan Graph API. Untuk memperbarui langganan, Anda dapat memanggil Graph API menggunakan cuplikan kode di Cara memperbarui langganan Graph API di atas.
  • Dapatkan token autentikasi untuk menggunakannya saat memanggil Microsoft Graph API.

Catatan

Dimungkinkan untuk membuat langganan Graph API Anda menggunakan Microsoft Graph API Explorer. Anda masih harus menggunakan sampel untuk aspek penting lainnya dari solusi Anda seperti autentikasi dan penerimaan peristiwa.

Sampel aplikasi web tersedia untuk bahasa berikut:

  • Sampel C#. Ini adalah sampel terbaru yang mencakup cara membuat dan memperbarui langganan Graph API dan memandul Anda melalui beberapa langkah untuk mengaktifkan alur peristiwa.
  • Sampel Java
    • GraphAPIController berisi kode sampel untuk membuat, menghapus, dan memperbarui langganan Graph API. Ini harus digunakan bersama dengan aplikasi sampel Java di atas.
  • Sampel NodeJS.

Penting

Anda perlu mengaktifkan topik mitra yang dibuat sebagai bagian dari pembuatan langganan Graph API Anda. Anda juga perlu membuat langganan peristiwa Event Grid ke aplikasi web Anda untuk menerima peristiwa. Untuk itu, Anda menggunakan URL yang dikonfigurasi di aplikasi web Anda untuk menerima peristiwa sebagai titik akhir webhook di langganan peristiwa Anda. Langkah selanjutnya untuk informasi selengkapnya.

Penting

Apakah Anda memerlukan kode sampel untuk bahasa lain atau memiliki pertanyaan? Silakan email kami di ask-graph-and-grid@microsoft.com.

Langkah berikutnya

Ikuti instruksi dalam dua langkah berikut untuk menyelesaikan pengaturan untuk menerima peristiwa Microsoft Graph API menggunakan Event Grid:

Tautan berguna lainnya: