MCP Tools Reference: classroommcp.googleapis.com

ابزار: list_courses

دوره‌های کاربر را با جزئیات آن‌ها (بخش، اتاق، موضوع، مقاطع تحصیلی، شرح، اهداف یادگیری، وضعیت، و نقش کاربر) فهرست می‌کند. از این به‌عنوان نقطه ورودی اصلی برای کاوش دوره‌ها و بازیابی شناسه‌های آن‌ها استفاده کنید. دوره‌ها اغلب عنوان مشترکی دارند، بنابراین از بخش برای متمایز کردن آن‌ها استفاده کنید. فقط دوره‌های «فعال» را برمی‌گرداند، مگراینکه courseState تنظیم شده باشد (مثلاً «بایگانی‌شده»).

برای پیوند دادن کاربر به دوره‌ای در برنامه وب 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

اختیاری. اندازه صفحه را کنترل می‌کند. پیش‌فرض ۱۰ است؛ حداکثر ۵۰.

pageToken

string

اختیاری. کد برای صفحه‌بندی.

DateRange

نمایش JSON
{
  "startDate": string,
  "endDate": string
}
فیلدها
startDate

string

شروع محدوده (قالب: YYYY-MM-DD).

endDate

string

پایان محدوده (قالب: س‌س‌س‌س-م‌م-رر).

ایالت

وضعیت‌های دوره.

شمارشی‌ها
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