الاستعلام عن Microsoft Graph باستخدام REST

  • 3 دقائق

Microsoft Graph هو واجهة برمجة تطبيقات ويب RESTful تمكنك من الوصول إلى موارد خدمة Microsoft Cloud. بمجرد تسجيل التطبيق والحصول على رموز المصادقة لمستخدم أو خدمة، يمكنك تقديم طلبات إلىMicrosoft Graph API.

تحدد Microsoft Graph API معظم مواردها وطرقها وتعدادها في مساحة اسم OData، microsoft.graphفي البيانات الوصفية لـ Microsoft Graph. يتم تعريف عدد قليل من مجموعات API في مساحات الأسماء الفرعية الخاصة بها، مثل واجهة برمجة تطبيقات سجلات المكالمات التي تحدد الموارد مثل callRecord في microsoft.graph.callRecords.

ما لم يتم تحديدها بوضوح في الموضوع المطابق، افترض أن الأنواع والأساليب والتعدادات جزء من مساحة اسم microsoft.graph.

استدعاء أسلوب API REST

للقراءة من مورد أو الكتابة إليه مثل مستخدم أو رسالة بريد إلكتروني، قم بإنشاء طلب يشبه النموذج التالي:

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

تتضمن مكونات الطلب ما يلي:

  • {HTTP method}- طريقة "HTTP" المستخدمة في الطلب إلى Microsoft Graph.
  • {version}- إصدار Microsoft Graph API الذي يستخدمه التطبيق الخاص بك.
  • {resource}- المورد في Microsoft Graph الذي تقوم بالإشارة إليه.
  • {query-parameters} - خيارات استعلام OData اختياري أو معلمات أسلوب REST تخصيص الاستجابة.

بعد إجراء طلب، يتم إرجاع استجابة تتضمن:

  • رمز الحالة - رمز حالة "HTTP" يشير إلى النجاح أو الفشل.
  • رسالة استجابة - البيانات التي طلبتها أو نتيجة العملية. يمكن أن تكون رسالة الاستجابة فارغة لبعض العمليات.
  • nextLink - إذا قام طلبك بإرجاع العديد من البيانات، فستحتاج إلى التنقل عبرها باستخدام عنوان URL الذي تم إرجاعه في @odata.nextLink.

أساليب HTTP

تستخدم Microsoft Graph أسلوب "HTTP" بناء على طلبك لتحديد ما يقوم به طلبك. تدعم API الطرق التالية.

الطريقة ‏‏الوصف
GET قراءة البيانات من مورد.
POST إنشاء مورد جديد أو تنفيذ إجراء.
PATCH تحديث مورد بقيم جديدة.
PUT استبدال مورد بمورد جديد.
حذف إزالة مورد.
  • بالنسبة إلى طرق CRUD GET وDELETE، لا يوجد نص طلب مطلوب.
  • POST PATCHتتطلب الأساليب و و PUT نص طلب محدد بتنسيق JSON يحتوي على معلومات إضافية. مثل قيم خصائص المورد.

إصدار

يدعم Microsoft Graph حالياً نسختين: v1.0 وbeta.

  • تتضمن v1.0 واجهات برمجة التطبيقات المتاحة بشكل عام. استخدم إصدار v1.0 لجميع تطبيقات الإنتاج.
  • يتضمن beta واجهات برمجة التطبيقات قيد المعاينة حالياً. نظرا لأننا قد نقدم تغييرات فاصلة على واجهات برمجة تطبيقات بيتا الخاصة بنا، نوصي باستخدام إصدار بيتا فقط لاختبار التطبيقات قيد التطوير؛ لا تستخدم واجهات برمجة تطبيقات بيتا في تطبيقات الإنتاج الخاصة بك.

Resource

يمكن أن يكون المورد كياناً أو نوعاً معقداً، يعرف عادةً بالخصائص. تختلف الكيانات عن الأنواع المعقدة من خلال تضمين خاصية معرف دائماً.

يتضمن عنوان URL المورد الذي تتفاعل معه في الطلب، مثل meالمستخدم والمجموعة ومحرك الأقراص والموقع. غالباً ما تتضمن الموارد ذات المستوى الأعلى أيضاً علاقات، والتي يمكنك استخدامها للوصول إلى موارد أخرى مثل me/messages أو me/drive. يمكنك أيضاً التفاعل مع الموارد باستخدام الطرق، على سبيل المثال، لإرسال بريد إلكتروني، استخدم me/sendMail.

قد يتطلب كل مورد أذونات مختلفة للوصول إليه. غالبا ما تحتاج إلى مستوى أعلى من الأذونات لإنشاء مورد أو تحديثه بدلا من قراءته. للحصول على تفاصيل حول الأذونات المطلوبة، راجع موضوع مرجع الأسلوب.

معلمات الاستعلام

يمكن أن تكون معلمات الاستعلام خيارات استعلام نظام OData أو سلاسل أخرى يقبلها أسلوب لتخصيص استجابته.

يمكنك استخدام خيارات استعلام نظام OData الاختيارية لتضمين خصائص أكثر أو أقل من الاستجابة الافتراضية. يمكنك تصفية الاستجابة للعناصر التي تطابق استعلام مخصص، أو توفير معلمات أخرى لأسلوب.

على سبيل المثال، تؤدي إضافة المعلمة التالية filter إلى تقييد الرسائل التي تم إرجاعها باستخدام emailAddress خاصية jon@contoso.com.

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

الموارد الأخرى

فيما يلي ارتباطات لبعض الأدوات التي يمكنك استخدامها لإنشاء الطلبات واختبارها باستخدام واجهات برمجة تطبيقات Microsoft Graph.