MCP Tools Reference: classroommcp.googleapis.com

الأداة: list_courses

تعرض هذه الصفحة دورات المستخدم مع تفاصيلها (القسم والغرفة والموضوع والمستويات الدراسية والوصف والأهداف التعليمية والحالة ودور المستخدم). استخدِم هذه الطريقة كنقطة الدخول الأساسية لاكتشاف الدورات التدريبية واسترداد معرّفاتها. غالبًا ما تتشارك الدورات التدريبية في العنوان، لذا استخدِم القسم لتمييزها عن بعضها. تعرض هذه الطريقة الدورات التدريبية النشطة فقط ما لم يتم ضبط courseState (على سبيل المثال، ARCHIVED).

لربط المستخدم بدورة تدريبية في تطبيق Classroom على الويب، استخدِم https://classroom.google.com/c/{course_id} (ساحة المشاركات) أو https://classroom.google.com/w/{course_id}/t/all (صفحة "الواجب الدراسي"). استخدِم المعرّفات كما تم عرضها بالضبط، ولا تخمّنها أو تعدّلها أبدًا.

توضح عينة التعليمات البرمجية التالية كيفية استخدام curl لطلب أداة بروتوكول سياق النموذج (MCP)‏ list_courses.

طلب Curl
curl --location 'https://classroommcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_courses",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

طلب عرض قائمة بالدورات التدريبية

ListCoursesRequest

تمثيل JSON
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
الحقول
courseState

enum (State)

اختيارية: الفلترة حسب حالة الدورة التدريبية القيمة التلقائية هي ACTIVE.

createdDateRange

object (DateRange)

اختيارية: الفلترة حسب نطاق تواريخ الإنشاء

timeZone

string

الحقل مطلوب. المنطقة الزمنية للمستخدم وفقًا لـ IANA (مثلاً، "America/Los_Angeles"). يتم تفسير التواريخ في هذا الطلب وتنسيقها في الردّ وفقًا لهذه المنطقة الزمنية، بما يتطابق مع ما يظهر للمستخدم في Classroom.

titleContains

string

اختيارية: فلترة العنوان حسب سلسلة فرعية غير حساسة لحالة الأحرف

pageSize

integer

اختيارية: تتحكّم في حجم الصفحة. القيمة التلقائية هي 10، والحد الأقصى هو 50.

pageToken

string

اختيارية: الرمز المميّز لتقسيم الصفحات

DateRange

تمثيل JSON
{
  "startDate": string,
  "endDate": string
}
الحقول
startDate

string

بداية النطاق (مشمولة) (التنسيق: YYYY-MM-DD).

endDate

string

نهاية النطاق الشاملة (التنسيق: YYYY-MM-DD).

ولاية

حالات الدورة التدريبية

عمليات التعداد
STATE_UNSPECIFIED حالة غير محدَّدة
ACTIVE الحالة: نشط
ARCHIVED الحالة المؤرشفة
PROVISIONED حالة توفير المتطلبات اللازمة

مخطط النتائج

الردّ على الدورات التدريبية المدرَجة في القائمة

ListCoursesResponse

تمثيل JSON
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
الحقول
courses[]

object (Course)

قائمة الدورات التدريبية

nextPageToken

string

الرمز المميّز للصفحة التالية

الدورة التدريبية

تمثيل JSON
{
  "id": string,
  "title": string,
  "role": enum (Role),
  "creationDate": string,
  "state": enum (State),
  "section": string,
  "room": string,
  "subject": string,
  "gradeLevels": string,
  "description": string,
  "learningGoals": [
    {
      object (LearningGoal)
    }
  ]
}
الحقول
id

string

المعرّف. معرّف هذه الدورة التدريبية

title

string

عنوان الدورة التدريبية

role

enum (Role)

دور المستخدم في هذه الدورة التدريبية

creationDate

string

تاريخ إنشاء الدورة التدريبية (بالتنسيق: YYYY-MM-DD) ويكون فارغًا إذا لم يكن تاريخ الإنشاء معروفًا.

state

enum (State)

النتائج فقط. حالة الدورة التدريبية

section

string

اختيارية: تمثّل هذه السمة قسم الدورة التدريبية.

room

string

اختيارية: غرفة الدورة التدريبية

subject

string

اختيارية: موضوع الدورة التدريبية

gradeLevels

string

اختيارية: تمثّل هذه السمة مستويات الصفوف في الدورة التدريبية.

description

string

اختيارية: وصف الدورة التدريبية

learningGoals[]

object (LearningGoal)

النتائج فقط. الأهداف التعليمية المرتبطة بهذه الدورة التدريبية

LearningGoal

تمثيل JSON
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
الحقول
id

string

النتائج فقط. رقم تعريف الهدف التعليمي لإرفاق معيار، استخدِم id من search_course_standards (وليس standardCode).

type

enum (Type)

النتائج فقط. نوع الهدف التعليمي

standardCode

string

النتائج فقط. رمز عادي (مثلاً "NY-2.NBT.4") لا تتم تعبئة هذا الحقل إلا للمعايير.

title

string

النتائج فقط. وصف العبارة للمعايير أو عنوان المهارات الذي يمكن لشخص عادي قراءته

documentTitle

string

النتائج فقط. اسم مستند المنهج الدراسي لا تتم تعبئة هذا الحقل إلا للمعايير.

الدور

أدوار المستخدم في دورة تدريبية

عمليات التعداد
ROLE_UNSPECIFIED دور غير محدّد
TEACHER الدور: مُعلّم -
COTEACHER الدور: معلّم مساعد -
STUDENT الدور: طالب -
INVITED_OR_INACTIVE دور مدعو أو غير نشط

ولاية

حالات الدورة التدريبية

عمليات التعداد
STATE_UNSPECIFIED حالة غير محدَّدة
ACTIVE الحالة: نشط
ARCHIVED الحالة المؤرشفة
PROVISIONED حالة توفير المتطلبات اللازمة

النوع

نوع الهدف التعليمي

عمليات التعداد
TYPE_UNSPECIFIED نوع الهدف التعليمي غير محدّد.
STANDARD تمثّل هذه السمة معيارًا من معايير التعلُّم من منهج دراسي أكاديمي.
SKILL مهارة تمثّل مفهومًا تعليميًا أو كفاءة معيّنة يمكن للمعلّم فقط إضافة المهارات أو إزالتها في Classroom.

التعليقات التوضيحية للأدوات

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

إلى جانب سلسلة العنوان، يتم تحديد التلميحات المنطقية التالية على النحو التالي:

  • ‫readOnlyHint: إذا كانت القيمة صحيحة، لا تعدّل الأداة بيئتها. القيمة التلقائية: false
  • ‫destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • ‫idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرّر باستخدام الوسيطات نفسها إلى أي تأثير إضافي في بيئتها. القيمة التلقائية: false
  • ‫openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة بحث الويب عالمًا مفتوحًا، في حين أنّ أداة الذاكرة لن تكون كذلك.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

نطاقات التفويض

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/classroom.courses.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly