آلية عمل الطلبات

توضّح هذه الصفحة نظرة عامة على مستوى عالٍ حول طريقة عمل الطلبات في Google Classroom API. والهدف من ذلك هو مساعدة القرّاء الذين ليس لديهم دراية مسبقة بالتصميم المستند إلى الموارد أو واجهات برمجة التطبيقات في Google Workspace.

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

التصميم المستند إلى الموارد

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

على سبيل المثال، يمكن create() وpatch() وget() وlist() وdelete() Course في Classroom باستخدام واجهة برمجة التطبيقات.

إنشاء

لإنشاء مورد جديد، مثل Course، استخدِم طريقة create() للمورد المعنيّ.

تتطلّب طلبات Create() دائمًا إدخال التفاصيل الأولية المهمة الخاصة بالمرجع المعني. على سبيل المثال، لإنشاء Course، عليك استدعاء طريقة create() في مورد Course وتحديد name وdescription في الطلب، بالإضافة إلى معلومات اختيارية مثل room.

بالنسبة إلى الموارد الفرعية (التي تُعرف أحيانًا باسم الموارد التابعة)، يجب توفير معرّفات للمورد الرئيسي أيضًا. على سبيل المثال، عند إنشاء CourseWork ضمن Course، يجب توفير Course id لتحديد Course الذي ينتمي إليه CourseWork.

تعرض طرق Create() مثيلاً للمورد الذي تم إنشاؤه حديثًا في ردّ طلب واجهة برمجة التطبيقات. يتضمّن المرجع الذي يتم عرضه عادةً أي حقول إضافية أنشأها الخادم، مثل id أو creationTime.

التصحيح

لتعديل المراجع الحالية، استدعِ طريقة patch() (التي تُسمى أحيانًا update()) على المرجع ذي الصلة. تتشابه الطريقة patch() مع الطريقة create() إلى حد كبير، مع وجود اختلافَين رئيسيَّين، وهما أنّه عند استدعاء الطريقة patch()، يجب تحديد ما يلي:

1. تمثّل هذه السمة id المرجع المطلوب تعديله.
2. قائمة بالحقول، تُعرف باسم updateMask، لتحديد الحقول التي سيتم تعديلها في المورد. هذا الحقل اختياري في الحالات التي تتوفّر فيها مجموعة حقول تلقائية أو يتم استنتاج الحقول.

ملاحظة: قد تلاحظ طرق update() إلى جانب طرق patch(). على الرغم من أنّ كليهما يعدّل أحد الموارد، إلا أنّهما يختلفان في السلوك. يستبدل الأمر Update() أحد الموارد بآخر جديد تمامًا، بينما يحدّث الأمر patch() حقولاً محددة فقط. على سبيل المثال، تستبدل courses.update() Course حاليًا بالكامل، بينما تستخدم courses.patch() fieldMask المذكورة أعلاه لتعديل حقول معيّنة فقط في Course. لتبسيط الأمور، تستخدم واجهة برمجة التطبيقات Google Classroom API patch() بشكل حصري تقريبًا، وننصحك باستخدام هذه الطريقة بشكل عام.

تعرض طرق Patch() النسخة الكاملة من المورد المعدَّل في استجابة طلب البيانات من واجهة برمجة التطبيقات، وذلك بعد إكمال جميع التغييرات.

الحصول على البيانات وإدراجها

هناك طريقتان لاسترداد الموارد: get() وlist().

تستردّ طريقة get() موردًا محدّدًا من خلال معرّف معيّن. على سبيل المثال، استرجاع Course استنادًا إلى id أو alias تعرض الدالة get() المورد الكامل مباشرةً.

تستردّ الطريقة list() موارد متعدّدة من النوع نفسه في طلب واحد، بدون الحاجة إلى معرّفات الموارد الفردية. غالبًا ما تحصل عملية list() على جميع الموارد الفرعية الخاصة ببعض الموارد الرئيسية، على سبيل المثال، استرداد جميع CourseWork ضمن Course. ويفيد ذلك في تقليل عدد الطلبات مقارنةً بإجراء عدة طلبات get()، كما أنّه مفيد بشكل خاص عندما لا تعرف id الموارد التي تريدها.

بشكل عام، تحتوي طرق list() على حد أقصى لعدد الموارد التي يمكن عرضها في مكالمة واحدة، ويمكن ضبط حدود دنيا من خلال تضمين قيمة pageSize مع المكالمة. في الحالات التي يتوفّر فيها عدد من الموارد أكبر من الحدّ الأقصى، تتيح طريقة list() التقسيم على صفحات، إذ تقدّم كل "صفحة" من النتائج التي يتم عرضها pageToken، ويمكن تضمينها في طلب list() لاحق لجلب المجموعة التالية من الموارد.

حذف

تقبل الطريقة delete() معرّف مورد، مثل id، وتحذف المورد المقابل. في حال نجاح عملية delete()، سيتم عرض استجابة فارغة.

عمليات أخرى

لا يمكن تنفيذ جميع العمليات المتاحة باستخدام Classroom API من خلال العمليات العادية المذكورة أعلاه، مثل تعديل الجهات المعيّنة لمورد CourseWork. في هذه الحالات، تتوفّر طرق مخصّصة، مثل طريقة modifyAssignees. يختلف سلوك هذه الطرق ويجب الرجوع إلى المستندات الخاصة بها بشكل فردي.