จัดการงาน

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

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

นอกจากทรัพยากร CourseWork แล้ว คุณยังจัดการงานที่เสร็จแล้วได้ด้วยทรัพยากร StudentSubmission

สร้างงาน

CourseWork สร้างขึ้นได้เฉพาะในนามของครูของหลักสูตร การพยายามสร้าง 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 resource หรือ YouTubeVideo resource ในลักษณะที่คล้ายกัน

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

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

เรียกข้อมูลงาน

คุณสามารถเรียกข้อมูล 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 ใหม่

คำเตือน: โปรเจ็กต์ในคอนโซลนักพัฒนาซอฟต์แวร์ที่สร้างทรัพยากร 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) โดยอัตโนมัติ ดูข้อมูลเกี่ยวกับเนื้อหาที่แนบไปกับ StudentSubmissions ได้ที่ Material

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

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

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

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

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