Mengkueri Microsoft Graph menggunakan REST

  • 3 menit

Microsoft Graph adalah API web RESTful yang memungkinkan Anda mengakses sumber daya layanan Microsoft Cloud. Setelah mendaftarkan aplikasi dan mendapat token autentikasi untuk pengguna atau layanan, Anda dapat membuat permintaan ke Microsoft Graph API.

Microsoft Graph API mendefinisikan sebagian besar sumber daya, metode, dan enumerasinya di namespace layanan OData, microsoft.graph, dalam metadata Microsoft Graph. Beberapa set API didefinisikan di subnamespace layanannya, seperti API rekaman panggilan yang menentukan sumber daya seperti callRecord di microsoft.graph.callRecords.

Kecuali ditentukan secara eksplisit dalam topik terkait, asumsikan jenis, metode, dan enumerasi adalah bagian dari namespace layanan microsoft.graph.

Memanggil metode REST API

Untuk membaca dari atau menulis ke sumber daya seperti pengguna atau pesan email, buat permintaan yang terlihat seperti sampel berikut:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Komponen permintaan meliputi:

  • {HTTP method} - Metode HTTP yang digunakan pada permintaan ke Microsoft Graph.
  • {version} - Versi Microsoft Graph API yang digunakan oleh aplikasi Anda.
  • {resource} - Sumber daya di Microsoft Graph yang Anda referensikan.
  • {query-parameters} - Opsi kueri OData opsional atau parameter metode REST yang mengkustomisasi respons.

Setelah Anda mengajukan permintaan, respons dikembalikan dengan mencakup:

  • Kode status - Kode status HTTP yang menunjukkan keberhasilan atau kegagalan.
  • Pesan respons - Data yang Anda minta atau hasil operasi. Pesan respons dapat kosong untuk beberapa operasi.
  • nextLink - Jika permintaan Anda mengembalikan banyak data, Anda perlu halaman melaluinya dengan menggunakan URL yang dikembalikan di @odata.nextLink.

Metode HTTP

Microsoft Graph menggunakan metode HTTP atas permintaan Anda untuk menentukan apa yang dilakukan oleh permintaan Anda. API mendukung metode berikut.

Metode Deskripsi
DAPATKAN Membaca data dari sumber daya.
PENGUMUMAN Membuat sumber daya baru, atau melakukan tindakan.
Patch Memperbarui sumber daya dengan nilai-nilai baru.
TARUH Mengganti sumber daya dengan sumber daya baru.
MENGHAPUS Menghapus sumber daya.
  • Untuk metode CRUD GET dan DELETE, badan permintaan tidak diperlukan.
  • Metode POST, PATCH, dan PUT memerlukan isi permintaan yang ditentukan dalam format JSON yang berisi informasi tambahan. Seperti nilai untuk properti sumber daya.

Versi

Microsoft Graph saat ini mendukung dua versi: v1.0 dan beta.

  • v1.0 meliputi API yang tersedia secara umum. Gunakan versi v1.0 untuk semua aplikasi produksi.
  • beta meliputi API yang saat ini berada dalam pratinjau. Karena kami mungkin memperkenalkan perubahan yang melanggar pada API beta kami, kami sarankan Anda menggunakan versi beta hanya untuk menguji aplikasi yang sedang dikembangkan; jangan gunakan API beta di aplikasi produksi Anda.

Sumber daya

Sumber daya dapat berupa entitas atau tipe kompleks, umumnya didefinisikan dengan properti. Entitas berbeda dari jenis kompleks dengan selalu menyertakan properti id .

URL Anda menyertakan sumber daya yang berinteraksi dengan Anda dalam permintaan, seperti me, pengguna, grup, drive, dan situs. Seringkali, sumber daya tingkat atas juga menyertakan hubungan, yang dapat Anda gunakan untuk mengakses sumber daya lain, seperti me/messages atau me/drive. Anda juga dapat berinteraksi dengan sumber daya menggunakan metode; misalnya, untuk mengirim email, gunakan me/sendMail.

Setiap sumber daya mungkin memerlukan izin yang berbeda untuk mengaksesnya. Anda sering memerlukan tingkat izin yang lebih tinggi untuk membuat atau memperbarui sumber daya daripada membacanya. Untuk detail tentang izin yang diperlukan, lihat topik referensi metode.

Parameter kueri

Parameter kueri dapat berupa opsi kueri sistem OData, atau string lain yang diterima metode untuk menyesuaikan responsnya.

Anda bisa menggunakan opsi kueri sistem OData opsional untuk menyertakan lebih banyak atau lebih sedikit properti daripada respons default. Anda dapat memfilter respons untuk item yang cocok dengan kueri kustom, atau menyediakan parameter lain untuk metode .

Misalnya, menambahkan parameter berikut filter membatasi pesan yang dikembalikan dengan emailAddress properti jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Sumber daya lainnya

Berikut ini adalah tautan ke beberapa alat yang dapat Anda gunakan untuk membuat dan menguji permintaan menggunakan API Microsoft Graph.