ابزار: 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 ( |
| فیلدها | |
|---|---|
courseState |
اختیاری. فیلتر کردن براساس وضعیت دوره. پیشفرضها به |
createdDateRange |
اختیاری. فیلتر کردن براساس محدوده تاریخهای ایجاد. |
timeZone |
الزامی. منطقه زمانی IANA کاربر (مثلاً |
titleContains |
اختیاری. فیلتر کردن عنوان براساس رشته فرعی غیرحساس به حروف بزرگ و کوچک. |
pageSize |
اختیاری. اندازه صفحه را کنترل میکند. پیشفرض ۱۰ است؛ حداکثر ۵۰. |
pageToken |
اختیاری. کد برای صفحهبندی. |
DateRange
| نمایش JSON |
|---|
{ "startDate": string, "endDate": string } |
| فیلدها | |
|---|---|
startDate |
شروع محدوده (قالب: YYYY-MM-DD). |
endDate |
پایان محدوده (قالب: سسسس-مم-رر). |
ایالت
وضعیتهای دوره.
| شمارشیها | |
|---|---|
STATE_UNSPECIFIED |
وضعیت نامشخص. |
ACTIVE |
وضعیت فعال. |
ARCHIVED |
وضعیت بایگانیشده. |
PROVISIONED |
وضعیت اختصاصیافته. |
طرح برونداد
پاسخ به فهرست کردن دورهها.
ListCoursesResponse
| نمایش JSON |
|---|
{
"courses": [
{
object ( |
| فیلدها | |
|---|---|
courses[] |
فهرست دورهها. |
nextPageToken |
کد صفحه بعدی. |
دوره آموزشی
| نمایش JSON |
|---|
{ "id": string, "title": string, "role": enum ( |
| فیلدها | |
|---|---|
id |
شناسه. شناسه این دوره. |
title |
عنوان دوره. |
role |
نقش کاربر در این دوره. |
creationDate |
تاریخ ایجاد دوره (قالب: YYYY-MM-DD). اگر تاریخ ایجاد مشخص نباشد، خالی است. |
state |
فقط خروجی. وضعیت دوره. |
section |
اختیاری. بخش دوره. |
room |
اختیاری. اتاق دوره. |
subject |
اختیاری. موضوع دوره. |
gradeLevels |
اختیاری. مقطع تحصیلی دوره. |
description |
اختیاری. شرح دوره. |
learningGoals[] |
فقط خروجی. اهداف یادگیری پیوستشده به این دوره. |
LearningGoal
| نمایش JSON |
|---|
{
"id": string,
"type": enum ( |
| فیلدها | |
|---|---|
id |
فقط خروجی. شناسه هدف یادگیری. برای پیوست کردن استاندارد، از |
type |
فقط خروجی. نوع هدف یادگیری. |
standardCode |
فقط خروجی. کد استاندارد (مثلاً «NY-2.NBT.4»). فقط برای استانداردها درج میشود. |
title |
فقط خروجی. شرح بیانیه برای استانداردها، یا عنوان قابلخواندن برای انسان برای مهارتها. |
documentTitle |
فقط خروجی. نام سند برنامه درسی. فقط برای استانداردها درج میشود. |
نقش
نقشهای کاربر در دوره.
| شمارشیها | |
|---|---|
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.readonlyhttps://www.googleapis.com/auth/classroom.rosters.readonly