MCP Tools Reference: classroommcp.googleapis.com

เครื่องมือ: list_courses

แสดงรายการหลักสูตรของผู้ใช้พร้อมรายละเอียด (ส่วน ห้อง วิชา ระดับชั้น คำอธิบาย เป้าหมายการเรียนรู้ สถานะ และบทบาทของผู้ใช้) ใช้เป็นจุดแรกเข้าหลักเพื่อค้นหาหลักสูตรและดึงรหัสหลักสูตร หลักสูตรมักจะใช้ชื่อเดียวกัน ดังนั้นให้ใช้ส่วนเพื่อแยกความแตกต่าง แสดงเฉพาะหลักสูตรที่ใช้งานอยู่ (ACTIVE) เว้นแต่จะมีการตั้งค่า 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

จุดเริ่มต้นของช่วง (รวมวันที่เริ่มต้น) (รูปแบบ: ปปปป-ดด-วว)

endDate

string

วันที่สิ้นสุดของช่วง (รูปแบบ: ปปปป-ดด-วว)

รัฐ

สถานะของหลักสูตร

Enum
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

วันที่สร้างหลักสูตร (รูปแบบ: ปปปป-ดด-วว) เว้นว่างไว้หากไม่ทราบวันที่สร้าง

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

เอาต์พุตเท่านั้น ชื่อเอกสารหลักสูตร จะป้อนข้อมูลสำหรับมาตรฐานเท่านั้น

บทบาท

บทบาทของผู้ใช้ในหลักสูตร

Enum
ROLE_UNSPECIFIED บทบาทที่ไม่ได้ระบุ
TEACHER บทบาทครู
COTEACHER บทบาทครูร่วมสอน
STUDENT บทบาทของนักเรียน
INVITED_OR_INACTIVE บทบาทที่ได้รับเชิญหรือไม่มีการใช้งาน

รัฐ

สถานะของหลักสูตร

Enum
STATE_UNSPECIFIED สถานะที่ไม่ได้ระบุ
ACTIVE สถานะใช้งานอยู่
ARCHIVED สถานะเก็บถาวร
PROVISIONED สถานะจัดสรรแล้ว

ประเภท

ประเภทของเป้าหมายการเรียนรู้

Enum
TYPE_UNSPECIFIED ประเภทเป้าหมายการเรียนรู้ที่ไม่ระบุ
STANDARD มาตรฐานการเรียนรู้จากหลักสูตรการศึกษา
SKILL ทักษะที่แสดงถึงแนวคิดหรือความสามารถด้านการศึกษา มีเพียงครูเท่านั้นที่เพิ่มหรือนำทักษะออกได้ใน Classroom

คำอธิบายประกอบเครื่องมือ

ระบบจะส่งคำอธิบายประกอบเครื่องมือไปยังไคลเอ็นต์ MCP เพื่ออธิบายความเสี่ยงพื้นฐานของเครื่องมือหนึ่งๆ ไคลเอ็นต์ส่วนใหญ่จะถือว่าคำแนะนำเหล่านี้ไม่น่าเชื่อถือ แต่สามารถใช้เพื่อตัดสินใจว่าจะส่งข้อความแจ้งเพื่อยืนยันไปยังผู้ใช้เมื่อใด

นอกจากสตริงชื่อแล้ว ยังมีการกำหนดคำแนะนำบูลีนต่อไปนี้ด้วย

  • readOnlyHint: หากเป็นจริง เครื่องมือจะไม่แก้ไขสภาพแวดล้อมของตนเอง ค่าเริ่มต้น: false
  • destructiveHint: หากเป็น "จริง" เครื่องมือจะดำเนินการที่ส่งผลกระทบต่อข้อมูลได้ หากเป็นเท็จ เครื่องมือจะดำเนินการได้เฉพาะการดำเนินการแบบเพิ่มเท่านั้น ค่าเริ่มต้น: true
  • idempotentHint: หากเป็นจริง การเรียกใช้เครื่องมือซ้ำๆ ด้วยอาร์กิวเมนต์เดียวกันจะไม่มีผลเพิ่มเติมต่อสภาพแวดล้อม ค่าเริ่มต้น: false
  • openWorldHint: หากเป็นจริง เครื่องมือจะโต้ตอบกับ "โอเพนเวิลด์" ของเอนทิตีภายนอกได้ หากเป็นเท็จ เครื่องมือจะโต้ตอบได้เฉพาะกับเอนทิตีภายในเท่านั้น ตัวอย่างเช่น เครื่องมือค้นเว็บจะเป็นแบบโอเพนเวิลด์ ส่วนเครื่องมือความทรงจำจะไม่ใช่แบบโอเพนเวิลด์

คำแนะนำเกี่ยวกับการทำลาย: ❌ | คำแนะนำเกี่ยวกับ Idempotent: ✅ | คำแนะนำเกี่ยวกับแบบอ่านอย่างเดียว: ✅ | คำแนะนำเกี่ยวกับโอเพนเวิลด์: ❌

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth อย่างใดอย่างหนึ่งต่อไปนี้

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