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

توضّح هذه الصفحة نظرة عامة على مستوى عالٍ حول آلية عمل الطلبات في واجهة برمجة التطبيقات 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() مثيلًا للمورد الذي تم إنشاؤه حديثًا في استجابة Create()call. يحتوي المورد الذي يتم إرجاعه عادةً على أي حقول إضافية يتم إنشاؤها من الخادم، مثل المورد id أو creationTime.

التصحيح

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

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

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

تُعيد طُرق 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. إنّ سلوك هذه الطرق مخصّص ويجب الرجوع إلى مستنداتها بشكلٍ فردي.