تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توضّح هذه الصفحة نظرة عامة على مستوى عالٍ حول طريقة عمل الطلبات في Google Classroom API. والهدف من ذلك هو مساعدة القرّاء الذين ليس لديهم دراية مسبقة بالتصميم المستند إلى الموارد أو واجهات برمجة التطبيقات في Google Workspace.
لإنشاء مورد جديد، مثل Course، استخدِم طريقة create() للمورد المعنيّ.
تتطلّب طلبات Create() دائمًا إدخال التفاصيل الأولية المهمة الخاصة بالمرجع المعني. على سبيل المثال، لإنشاء Course، عليك استدعاء طريقة create() في مورد Course وتحديد name وdescription في الطلب، بالإضافة إلى معلومات اختيارية مثل room.
بالنسبة إلى الموارد الفرعية (التي تُعرف أحيانًا باسم الموارد التابعة)، يجب توفير معرّفات للمورد الرئيسي أيضًا. على سبيل المثال، عند إنشاء CourseWork ضمن Course، يجب توفير Courseid لتحديد Course الذي ينتمي إليه CourseWork.
تعرض طرق Create() مثيلاً للمورد الذي تم إنشاؤه حديثًا في ردّ طلب واجهة برمجة التطبيقات. يتضمّن المرجع الذي يتم عرضه عادةً أي حقول إضافية أنشأها الخادم، مثل id أو creationTime.
التصحيح
لتعديل المراجع الحالية، استدعِ طريقة patch() (التي تُسمى أحيانًا update()) على المرجع ذي الصلة. تتشابه الطريقة patch() مع الطريقة create() إلى حد كبير، مع وجود اختلافَين رئيسيَّين، وهما أنّه عند استدعاء الطريقة patch()، يجب تحديد ما يلي:
تمثّل هذه السمة id المرجع المطلوب تعديله.
قائمة بالحقول، تُعرف باسم updateMask، لتحديد الحقول التي سيتم تعديلها في المورد. هذا الحقل اختياري في الحالات التي تتوفّر فيها مجموعة حقول تلقائية أو يتم استنتاج الحقول.
تعرض طرق 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. يختلف سلوك هذه الطرق
ويجب الرجوع إلى المستندات الخاصة بها بشكل فردي.
تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# How requests work\n\nThis page describes a high-level overview of how requests work in the\nGoogle Classroom API. The goal is to aid readers who aren't already familiar with\nresource-oriented design or Google Workspace APIs.\n\nFor specific code samples, see the corresponding API guides, for example [Create\n\\& manage courses](/workspace/classroom/guides/manage-courses) or [Create \\& manage coursework](/workspace/classroom/guides/manage-coursework).\n\nResource-oriented design\n------------------------\n\nAs mentioned in [API resources](/workspace/classroom/guides/key-concepts/api-structure), the Classroom API follows\n[resource-oriented design](https://google.aip.dev/121) patterns. Most resources have methods for standard\noperations like creating, reading, updating, and deleting instances of the\nresource.\n\nFor example, it's possible to [`create()`](/workspace/classroom/reference/rest/v1/courses/create), [`patch()`](/workspace/classroom/reference/rest/v1/courses/patch), [`get()`](/workspace/classroom/reference/rest/v1/courses/get), [`list()`](/workspace/classroom/reference/rest/v1/courses/list),\nand [`delete()`](/workspace/classroom/reference/rest/v1/courses/delete) a Classroom [`Course`](/workspace/classroom/reference/rest/v1/courses) using the API.\n\nCreate\n------\n\nTo create a new resource, like a `Course`, call the `create()` method for the\ncorresponding resource.\n\n`Create()` calls always require the initial, critical details of the\ncorresponding resource as input. For example, to create a `Course`, call the\n`create()` method on the `Course` resource and specify the `name` and\n`description` in the request, along with optional information like the `room`.\n\nFor subresources (sometimes called child resources), identifiers for the parent\nresource are also required. For example, when creating a [`CourseWork`](/workspace/classroom/reference/rest/v1/courses.courseWork) within a\n`Course`, the `Course` `id` is needed to establish in which `Course` the\n`CourseWork` belongs.\n\n`Create()` methods return an instance of the newly created resource in the API\ncall response. The returned resource typically has any additional,\nserver-generated fields, such as the resource `id` or `creationTime`.\n\nPatch\n-----\n\nTo modify existing resources, call the `patch()` method (which is sometimes\ncalled `update()`) on the corresponding resource. The `patch()` method is almost\nidentical to `create()`, with two key differences; when calling the `patch()`\nmethod you must specify:\n\n1. The `id` of the resource to modify.\n2. A list of fields, called an `updateMask`, to determine which fields on the resource to update. This is optional in cases where there is a default set of fields or the fields are inferred.\n\n| **Tip:** You might notice `update()` methods alongside `patch()` methods. While both modify a resource, they differ in behavior. `Update()` completely replaces a resource with a new one, while `patch()` only updates select fields. For example, [`courses.update()`](/workspace/classroom/reference/rest/v1/courses/update) replaces an entire existing `Course`, while [`courses.patch()`](/workspace/classroom/reference/rest/v1/courses/patch) uses the aforementioned `fieldMask` to modify only specific fields in the `Course`. For simplicity, the Google Classroom API almost exclusively uses `patch()`, and it's recommended that you use that method generally.\n\n`Patch()` methods return the full instance of the updated resource in the API\ncall response, with all changes completed.\n\nGet and list\n------------\n\nThere are two methods for retrieving resources: `get()` and `list()`.\n\nThe `get()` method retrieves a specific resource by some identifier. For\nexample, fetching a `Course` based on `id` or [`alias`](/workspace/classroom/reference/rest/v1/courses.aliases). The `get()` call\nreturns the full resource directly.\n\nThe `list()` method retrieves multiple resources of the same type in a single\nrequest, without the need for the individual resource identifiers. Often the\n`list()` operation gets all the subresources of some parent resource, for\nexample, retrieving all the `CourseWork` within a `Course`. This is useful for\nminimizing requests, compared to making multiple `get()` calls, and particularly\nvaluable when you don't know the `id` of the resources you want.\n\nGenerally, `list()` methods have some maximum amount of resources that can be\nreturned in a single call, and lower limits can be configured by including a\n`pageSize` value with the call. In cases where there are more resources than the\nlimit, the `list()` method supports *pagination* ; each \"page\" of results that is\nreturned provides a `pageToken`, which can be included in a subsequent `list()`\ncall to fetch the next batch of resources.\n\nDelete\n------\n\nThe `delete()` method accepts a resource identifier, like `id`, and deletes the\ncorresponding resource. If the `delete()` is successful, an empty response is\nreturned.\n\nOther operations\n----------------\n\nNot all operations possible with the Classroom API can be achieved\nwith the aforementioned standard operations, for example, modifying the\nassignees of a `CourseWork` resource. In these cases, custom methods are\navailable, like the [`modifyAssignees`](/workspace/classroom/reference/rest/v1/courses.courseWork/modifyAssignees) method. The behavior of these methods\nare bespoke and you should consult the documentation for them individually."]]
