Bagikan melalui

Menerima peristiwa perubahan Microsoft Graph API melalui Azure Event Grid

  • 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 .

Sumber kejadian Microsoft Sumber Tipe kejadian yang tersedia
Microsoft Entra ID Pengguna, Grup Jenis peristiwa Microsoft Entra
Microsoft Outlook Kejadian (rapat kalender), Pesan (email), Kontak Jenis kejadian Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (rapat) Jenis kejadian Microsoft Teams
OneDrive DriveItem Peristiwa Microsoft OneDrive
Microsoft SharePoint Daftar Peristiwa Microsoft SharePoint
To Do Tugas Yang Harus Dilakukan Peristiwa Microsoft ToDo
Peringatan keamanan Peringatan Peristiwa Pemberitahuan Keamanan Microsoft
Pencetakan cloud Printer, Cetak Definisi Tugas Peristiwa Microsoft Cloud Printing
Microsoft Conversations Percakapan Peristiwa Percakapan Grup Microsoft 365

Anda membuat langganan Microsoft Graph API untuk memungkinkan kejadian Graph API mengalir ke topik mitra. Topik mitra secara otomatis dibuat untuk Anda sebagai bagian dari pembuatan langganan Graph API. Anda menggunakan topik mitra tersebut untuk membuat langganan kejadian untuk mengirim kejadian Anda ke salah satu penanganan aktivitas yang didukung yang paling sesuai dengan kebutuhan Anda untuk memproses kejadian.

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 CloudEvents Cloud Native Computing Foundation (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 Software Development Kits (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. Untuk informasi selengkapnya, lihat Pemberitahuan perubahan Microsoft Graph API. 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 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 sebelumnya 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 Permintaan Perubahan (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.

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

Memperpanjang langganan Microsoft Graph API

Aplikasi Anda harus memperbarui langganan Graph API 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 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 kedaluwarsa selama kurang dari 30 hari. Jika langganan Graph API kedaluwarsa selama lebih dari 30 hari, Anda tidak dapat menggunakan kembali topik mitra yang ada. Dalam hal ini, Anda perlu 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. Otorisasi ulang titik akhir Anda tidak memperbarui langganan Anda. Namun, memperbarui langganan Anda juga 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 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 memperpanjang langganan, Anda dapat memanggil Graph API menggunakan cuplikan kode di Cara memperbarui langganan Graph API.
  • 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 memancarkan 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.
  • 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: