จัดการงาน

แอป Classroom รองรับรายการในสตรีม 3 ประเภท ได้แก่ CourseWork, CourseWorkMaterials และ Announcements คู่มือนี้ อธิบายวิธีจัดการ CourseWork แต่ API สำหรับรายการสตรีมทั้งหมดจะ คล้ายกัน ดูแหล่งข้อมูล API เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับประเภทรายการสตรีมและความแตกต่างของรายการเหล่านั้น

CourseWork ทรัพยากรแสดงถึงรายการงานที่ได้รับมอบหมายให้นักเรียน/นักศึกษาในหลักสูตรหนึ่งๆ รวมถึงสื่อและรายละเอียดเพิ่มเติม เช่น วันที่ครบกำหนดหรือคะแนนสูงสุด CourseWork มี 4 ประเภทย่อย ได้แก่ งาน แบบทดสอบ คำถามแบบคำตอบสั้นๆ และ คำถามแบบหลายตัวเลือก Classroom API รองรับ งาน คำถามที่ต้องการคำตอบสั้นๆ และ คำถามแบบหลายตัวเลือก ซึ่งเป็น 3 ประเภทย่อยของคำถาม โดยประเภทเหล่านี้จะแสดงด้วยฟิลด์ CourseWork.workType

นอกจากCourseWorkแหล่งข้อมูลแล้ว คุณยังจัดการงานที่เสร็จสมบูรณ์ได้ ด้วยแหล่งข้อมูล StudentSubmission

สร้างงานของชั้นเรียน

CourseWork จะสร้างได้ในนามของครูผู้สอนเท่านั้น การพยายามสร้าง CourseWork ในนามของนักเรียนหรือผู้ดูแลระบบโดเมนที่ไม่ได้เป็นครูในหลักสูตรจะทำให้เกิดข้อผิดพลาด PERMISSION_DENIED ดูข้อมูลเพิ่มเติมเกี่ยวกับบทบาทต่างๆ ใน Classroom ได้ที่ประเภทผู้ใช้

เมื่อสร้าง CourseWork โดยใช้วิธี courses.courseWork.create คุณจะ แนบลิงก์เป็น materials ได้ตามที่แสดงในโค้ดตัวอย่างด้านล่าง

Java

classroom/snippets/src/main/java/CreateCourseWork.java

ดูใน GitHub

CourseWork courseWork = null;
try {
  // Create a link to add as a material on course work.
  Link articleLink =
      new Link()
          .setTitle("SR-71 Blackbird")
          .setUrl("https://www.lockheedmartin.com/en-us/news/features/history/blackbird.html");

  // Create a list of Materials to add to course work.
  List<Material> materials = Arrays.asList(new Material().setLink(articleLink));

  /* Create new CourseWork object with the material attached.
  Set workType to `ASSIGNMENT`. Possible values of workType can be found here:
  https://developers.google.com/classroom/reference/rest/v1/CourseWorkType
  Set state to `PUBLISHED`. Possible values of state can be found here:
  https://developers.google.com/classroom/reference/rest/v1/courses.courseWork#courseworkstate */
  CourseWork content =
      new CourseWork()
          .setTitle("Supersonic aviation")
          .setDescription(
              "Read about how the SR-71 Blackbird, the world’s fastest and "
                  + "highest-flying manned aircraft, was built.")
          .setMaterials(materials)
          .setWorkType("ASSIGNMENT")
          .setState("PUBLISHED");

  courseWork = service.courses().courseWork().create(courseId, content).execute();

  /* Prints the created courseWork. */
  System.out.printf("CourseWork created: %s\n", courseWork.getTitle());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("The courseId does not exist: %s.\n", courseId);
  } else {
    throw e;
  }
  throw e;
} catch (Exception e) {
  throw e;
}
return courseWork;

Python

classroom/snippets/classroom_create_coursework.py

ดูใน GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_create_coursework(course_id):
  """
  Creates the coursework the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """

  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member

  try:
    service = build("classroom", "v1", credentials=creds)
    coursework = {
        "title": "Ant colonies",
        "description": """Read the article about ant colonies
                              and complete the quiz.""",
        "materials": [
            {"link": {"url": "http://example.com/ant-colonies"}},
            {"link": {"url": "http://example.com/ant-quiz"}},
        ],
        "workType": "ASSIGNMENT",
        "state": "PUBLISHED",
    }
    coursework = (
        service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )
    print(f"Assignment created with ID {coursework.get('id')}")
    return coursework

  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Put the course_id of course whose coursework needs to be created,
  # the user has access to.
  classroom_create_coursework(453686957652)

ต้องระบุข้อมูลในช่อง title และ workType ช่องอื่นๆ ทั้งหมดไม่บังคับ หากไม่ได้ระบุ state ระบบจะสร้าง CourseWork ในสถานะแบบร่าง

ใช้แหล่งข้อมูลลิงก์ที่มีเป้าหมายที่ระบุ url เพื่อรวมสื่อที่ลิงก์ไว้ใน CourseWork Classroom จะดึงข้อมูล title และ URL ของรูปภาพขนาดย่อ (thumbnailUrl) โดยอัตโนมัติ นอกจากนี้ Classroom API ยังรองรับเนื้อหาใน Google ไดรฟ์และ YouTube โดยกำเนิด ซึ่งสามารถรวมไว้กับแหล่งข้อมูล DriveFile หรือแหล่งข้อมูล YouTubeVideo ในลักษณะเดียวกัน

หากต้องการระบุวันที่ครบกำหนด ให้ตั้งค่าฟิลด์ dueDate และ dueTime เป็นเวลา UTC ที่เกี่ยวข้อง วันที่ครบกำหนดต้องเป็นวันที่ในอนาคต

CourseWork คำตอบมีตัวระบุที่เซิร์ฟเวอร์กำหนดซึ่งใช้ เพื่ออ้างอิงการกำหนดในคำขอ API อื่นๆ ได้

เรียกข้อมูล CourseWork

คุณสามารถดึงข้อมูล CourseWork ในนามของนักเรียนและครูของหลักสูตรที่เกี่ยวข้องได้ นอกจากนี้ คุณยังเรียกข้อมูล CourseWork ในนามของผู้ดูแลระบบโดเมนได้ด้วย แม้ว่าผู้ดูแลระบบจะไม่ได้เป็นครูในหลักสูตรก็ตาม หากต้องการดึงข้อมูลCourseWorkที่เฉพาะเจาะจง ให้ใช้ courses.courseWork.get หากต้องการดึงข้อมูลทั้งหมด CourseWork (อาจตรงกับเกณฑ์บางอย่าง) ให้ใช้ courses.courseWork.list

หมายเหตุ: หากสนใจเฉพาะบางฟิลด์ ให้พิจารณาจำกัดคำขอของคุณ ไว้ที่ฟิลด์เหล่านั้น ซึ่งจะช่วยให้คำขอของคุณดำเนินการได้เร็วขึ้นอย่างมาก ดูรายละเอียดเพิ่มเติมได้ที่การทำงาน กับทรัพยากรบางส่วน

ขอบเขตที่จำเป็นจะขึ้นอยู่กับบทบาทที่ผู้ใช้ที่ขอมีใน หลักสูตร หากผู้ใช้เป็นนักเรียน/นักศึกษา ให้ใช้ขอบเขตใดขอบเขตหนึ่งต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.me.readonly
• https://www.googleapis.com/auth/classroom.coursework.me

หากผู้ใช้เป็นครูหรือผู้ดูแลระบบโดเมน ให้ใช้ขอบเขตใดขอบเขตหนึ่งต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.students.readonly
• https://www.googleapis.com/auth/classroom.coursework.students

การมีสิทธิ์ดึงข้อมูล CourseWork ไม่ได้หมายความว่าคุณมีสิทธิ์เข้าถึงเนื้อหาหรือข้อมูลเมตาของเนื้อหา ในทางปฏิบัติแล้ว หมายความว่า ผู้ดูแลระบบอาจไม่เห็นชื่อไฟล์ในไดรฟ์ที่แนบมา หากไม่ได้เป็นสมาชิกของหลักสูตร

จัดการคำตอบของนักเรียน/นักศึกษา

ทรัพยากร StudentSubmission แสดงถึงงานที่นักเรียนทำสำหรับCourseWork แหล่งข้อมูลนี้มีข้อมูลเมตาที่เกี่ยวข้องกับงาน เช่น สถานะงานและคะแนน ระบบจะสร้าง StudentSubmission โดยปริยาย สำหรับนักเรียนแต่ละคนเมื่อสร้าง CourseWork ใหม่

คำเตือน: การส่งงานของนักเรียนจะแก้ไขได้โดยโปรเจ็กต์ใน Developer Console ที่สร้างทรัพยากร CourseWork ที่เกี่ยวข้องเท่านั้น ซึ่งเป็นข้อจำกัดเพิ่มเติมจากข้อจำกัดด้านสิทธิ์ของผู้ใช้ที่ส่งคำขอ ไคลเอ็นต์ OAuth2 ใดก็ได้ในโปรเจ็กต์นั้นอาจทำการแก้ไขได้ โดยฟิลด์ associatedWithDeveloper จะระบุว่าไคลเอ็นต์ OAuth2 ปัจจุบันแก้ไข StudentSubmission ที่ระบุได้หรือไม่

ส่วนต่อไปนี้จะอธิบายการดำเนินการทั่วไปที่ใช้จัดการคำตอบของนักเรียน/นักศึกษา

ดึงคำตอบของนักเรียน

นักเรียนสามารถดึงข้อมูลงานที่ส่งของตนเอง ครูสามารถดึงข้อมูลงานที่ส่งของนักเรียนทุกคนในหลักสูตร และผู้ดูแลระบบโดเมนสามารถดึงข้อมูลงานที่ส่งทั้งหมดของนักเรียนทุกคนในโดเมน StudentSubmissionแต่ละรายการ จะได้รับตัวระบุ หากทราบตัวระบุ ให้ใช้ courses.courseWork.studentSubmissions.get เพื่อดึงข้อมูลการส่ง

ใช้วิธี courses.courseWork.studentSubmissions.list เพื่อรับทรัพยากรทั้งหมด StudentSubmissionที่ตรงกับเกณฑ์บางอย่าง ดังที่แสดงใน ตัวอย่างต่อไปนี้

Java

classroom/snippets/src/main/java/ListSubmissions.java

ดูใน GitHub

List<StudentSubmission> studentSubmissions = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListStudentSubmissionsResponse response =
        service
            .courses()
            .courseWork()
            .studentSubmissions()
            .list(courseId, courseWorkId)
            .setPageToken(pageToken)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getStudentSubmissions() != null) {
      studentSubmissions.addAll(response.getStudentSubmissions());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (studentSubmissions.isEmpty()) {
    System.out.println("No student submission found.");
  } else {
    for (StudentSubmission submission : studentSubmissions) {
      System.out.printf(
          "Student id (%s), student submission id (%s)\n",
          submission.getUserId(), submission.getId());
    }
  }
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "The courseId (%s) or courseWorkId (%s) does not exist.\n", courseId, courseWorkId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return studentSubmissions;

Python

classroom/snippets/classroom_list_submissions.py

ดูใน GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_submissions(course_id, coursework_id):
  """
  Creates the courses the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """

  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  submissions = []
  page_token = None

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      response = (
          coursework.studentSubmissions()
          .list(
              pageToken=page_token,
              courseId=course_id,
              courseWorkId=coursework_id,
              pageSize=10,
          )
          .execute()
      )
      submissions.extend(response.get("studentSubmissions", []))
      page_token = response.get("nextPageToken", None)
      if not page_token:
        break

    if not submissions:
      print("No student submissions found.")

    print("Student Submissions:")
    for submission in submissions:
      print(
          "Submitted at:"
          f"{(submission.get('id'), submission.get('creationTime'))}"
      )

  except HttpError as error:
    print(f"An error occurred: {error}")
    submissions = None
  return submissions


if __name__ == "__main__":
  # Put the course_id and coursework_id of course whose list needs to be
  # submitted.
  classroom_list_submissions(453686957652, 466086979658)

เรียกข้อมูลStudentSubmissionทรัพยากรที่เป็นของนักเรียนคนใดคนหนึ่งโดย ระบุพารามิเตอร์ userId ดังที่แสดงในตัวอย่างต่อไปนี้

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java

ดูใน GitHub

List<StudentSubmission> studentSubmissions = new ArrayList<>();
String pageToken = null;

try {
  do {
    // Set the userId as a query parameter on the request.
    ListStudentSubmissionsResponse response =
        service
            .courses()
            .courseWork()
            .studentSubmissions()
            .list(courseId, courseWorkId)
            .setPageToken(pageToken)
            .set("userId", userId)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getStudentSubmissions() != null) {
      studentSubmissions.addAll(response.getStudentSubmissions());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (studentSubmissions.isEmpty()) {
    System.out.println("No student submission found.");
  } else {
    for (StudentSubmission submission : studentSubmissions) {
      System.out.printf("Student submission: %s.\n", submission.getId());
    }
  }

Python

classroom/snippets/classroom_list_student_submissions.py

ดูใน GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_student_submissions(course_id, coursework_id, user_id):
  """
  Creates the courses the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """

  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  submissions = []
  page_token = None

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      response = (
          coursework.studentSubmissions()
          .list(
              pageToken=page_token,
              courseId=course_id,
              courseWorkId=coursework_id,
              userId=user_id,
          )
          .execute()
      )
      submissions.extend(response.get("studentSubmissions", []))
      page_token = response.get("nextPageToken", None)
      if not page_token:
        break

    if not submissions:
      print("No student submissions found.")

    print("Student Submissions:")
    for submission in submissions:
      print(
          "Submitted at:"
          f"{(submission.get('id'), submission.get('creationTime'))}"
      )

  except HttpError as error:
    print(f"An error occurred: {error}")
  return submissions


if __name__ == "__main__":
  # Put the course_id, coursework_id and user_id of course whose list needs
  # to be submitted.
  classroom_list_student_submissions(453686957652, 466086979658, "me")

ระบบจะระบุนักเรียนตามรหัสที่ไม่ซ้ำกันหรืออีเมลตามที่แสดงในแหล่งข้อมูล Student ผู้ใช้ปัจจุบันยังอ้างอิงรหัสของตนเองได้โดยใช้รูปแบบย่อ "me"

นอกจากนี้ คุณยังดึงข้อมูลงานที่นักเรียนส่งสำหรับงานทั้งหมดในหลักสูตรได้ด้วย โดยใช้ตัวอักษร "-" เป็น courseWorkId ดังที่แสดงในตัวอย่างต่อไปนี้

Java

service.courses().courseWork().studentSubmissions()
    .list(courseId, "-")
    .set("userId", userId)
    .execute();

Python

service.courses().courseWork().studentSubmissions().list(
    courseId=<course ID or alias>,
    courseWorkId='-',
    userId=<user ID>).execute()

หมายเหตุ: หากสนใจเฉพาะบางฟิลด์ ให้พิจารณาจำกัดคำขอของคุณ ไว้ที่ฟิลด์เหล่านั้น ซึ่งจะช่วยให้คำขอของคุณดำเนินการได้เร็วขึ้นอย่างมาก ดูรายละเอียดเพิ่มเติมได้ที่การทำงาน กับทรัพยากรบางส่วน

ขอบเขตที่จำเป็นจะขึ้นอยู่กับบทบาทที่ผู้ใช้ที่ขอมีใน หลักสูตร หากผู้ใช้เป็นครูหรือผู้ดูแลระบบโดเมน ให้ใช้ขอบเขตต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.students.readonly
• https://www.googleapis.com/auth/classroom.coursework.students

หากผู้ใช้เป็นนักเรียน/นักศึกษา ให้ใช้ขอบเขตต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.me.readonly
• https://www.googleapis.com/auth/classroom.coursework.me

การมีสิทธิ์ดึงข้อมูล StudentSubmission ไม่ได้หมายความว่าคุณมีสิทธิ์ เข้าถึงไฟล์แนบหรือข้อมูลเมตาของไฟล์แนบ ในทางปฏิบัติ หมายความว่าผู้ดูแลระบบอาจไม่เห็นชื่อไฟล์ในไดรฟ์ที่แนบมาหากไม่ได้เป็นสมาชิกของหลักสูตร

เพิ่มไฟล์แนบในคำตอบของนักเรียน/นักศึกษา

คุณแนบลิงก์ไปยังงานที่นักเรียนส่งได้โดยแนบทรัพยากร Link DriveFile หรือ YouTubeVideo โดยทำได้ด้วย courses.courseWork.studentSubmissions.modifyAttachments ดังที่แสดงใน ตัวอย่างต่อไปนี้

Java

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java

ดูใน GitHub

StudentSubmission studentSubmission = null;
try {
  // Create ModifyAttachmentRequest object that includes a new attachment with a link.
  Link link = new Link().setUrl("https://en.wikipedia.org/wiki/Irrational_number");
  Attachment attachment = new Attachment().setLink(link);
  ModifyAttachmentsRequest modifyAttachmentsRequest =
      new ModifyAttachmentsRequest().setAddAttachments(Arrays.asList(attachment));

  // The modified studentSubmission object is returned with the new attachment added to it.
  studentSubmission =
      service
          .courses()
          .courseWork()
          .studentSubmissions()
          .modifyAttachments(courseId, courseWorkId, id, modifyAttachmentsRequest)
          .execute();

  /* Prints the modified student submission. */
  System.out.printf(
      "Modified student submission attachments: '%s'.\n",
      studentSubmission.getAssignmentSubmission().getAttachments());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "The courseId (%s), courseWorkId (%s), or studentSubmissionId (%s) does "
            + "not exist.\n",
        courseId, courseWorkId, id);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return studentSubmission;

Python

classroom/snippets/classroom_add_attachment.py

ดูใน GitHub

def classroom_add_attachment(course_id, coursework_id, submission_id):
  """
  Adds attachment to existing course with specific course_id.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  request = {
      "addAttachments": [
          {"link": {"url": "http://example.com/quiz-results"}},
          {"link": {"url": "http://example.com/quiz-reading"}},
      ]
  }

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      coursework.studentSubmissions().modifyAttachments(
          courseId=course_id,
          courseWorkId=coursework_id,
          id=submission_id,
          body=request,
      ).execute()

  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Put the course_id, coursework_id and submission_id of course in which
  # attachment needs to be added.
  classroom_add_attachment("course_id", "coursework_id", "me")

Linkไฟล์แนบจะกำหนดโดยเป้าหมาย url Classroom จะดึงข้อมูล title และรูปภาพขนาดย่อ (thumbnailUrl) โดยอัตโนมัติ ดูMaterialเพื่อดูข้อมูลเกี่ยวกับสื่อที่แนบไปกับ StudentSubmissions ได้

โดยมีเพียงครูผู้สอนหรือนักเรียนที่เป็นเจ้าของเท่านั้นที่สามารถแก้ไขStudentSubmissionได้ คุณจะแนบ Materials ได้ก็ต่อเมื่อ CourseWorkType ของ StudentSubmission เป็น ASSIGNMENT เท่านั้น

ขอบเขตที่จำเป็นจะขึ้นอยู่กับบทบาทที่ผู้ใช้ที่ขอมีใน หลักสูตร หากผู้ใช้เป็นครู ให้ใช้ขอบเขตต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.students

หากผู้ใช้เป็นนักเรียน/นักศึกษา ให้ใช้ขอบเขตต่อไปนี้

• https://www.googleapis.com/auth/classroom.coursework.me