จัดการงาน

UI ของ Classroom รองรับงานของชั้นเรียน5 ประเภท ได้แก่ งาน งานแบบทดสอบ คำถามแบบตอบสั้นๆ คำถามแบบหลายตัวเลือก และเนื้อหา ปัจจุบัน Classroom API รองรับประเภทเหล่านี้3 ประเภท ซึ่งเรียกว่า CourseWorkType สำหรับ API ได้แก่ งาน คำถามแบบตอบสั้นๆ และคำถามแบบหลายตัวเลือก

หมายเหตุ: คุณสามารถสร้าง Materials เป็นงานใน UI ของ Classroom ได้ แต่ API รองรับเฉพาะการแนบ Materials กับทรัพยากร CourseWorkType เท่านั้น ได้แก่ งาน คำถามแบบตอบสั้นๆ และคำถามแบบหลายตัวเลือก

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

นอกจากทรัพยากร "งาน" แล้ว คุณยังจัดการงานที่ทำเสร็จแล้วได้ด้วยทรัพยากร StudentSubmission ส่วนต่อไปนี้จะอธิบายข้อมูลเหล่านี้โดยละเอียด

สร้างงาน

คุณสร้างงานในนามของครูในหลักสูตรได้เท่านั้น และพยายามสร้างงานในหลักสูตรในนามของนักเรียนจะส่งผลให้เกิดข้อผิดพลาด 403 PERMISSION_DENIED ในทํานองเดียวกัน ผู้ดูแลระบบโดเมนจะสร้างงานสําหรับหลักสูตรที่ไม่ได้สอนไม่ได้ และการพยายามทําเช่นนั้นผ่าน API ก็จะทำให้เกิดข้อผิดพลาด 403 PERMISSION_DENIED ด้วย

เมื่อสร้างงานโดยใช้เมธอด 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)

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

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

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

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

เรียกข้อมูลงานและคำถาม

คุณสามารถเรียกดูงานและคำถามสำหรับนักเรียนและครูของหลักสูตรที่เกี่ยวข้องหรือเรียกดูโดยผู้ดูแลระบบโดเมน หากต้องการเรียกข้อมูลงานหรือคำถามที่เฉพาะเจาะจง ให้ใช้ courses.courseWork.get หากต้องการดึงข้อมูลงานหรือคำถามทั้งหมด (จับคู่กับเกณฑ์บางอย่างหรือไม่ก็ได้) ให้ใช้ 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

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

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

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

มีเพียงโปรเจ็กต์คอนโซลนักพัฒนาซอฟต์แวร์ที่สร้างแหล่งข้อมูล CourseWork ที่เกี่ยวข้องเท่านั้นที่จะแก้ไขข้อมูลที่ส่งของนักเรียนได้ นอกเหนือจากการตรวจสอบว่าผู้ใช้ที่ส่งคำขอมีสิทธิ์ที่ถูกต้องแล้ว ไคลเอ็นต์ OAuth2 ใดก็ได้ในโปรเจ็กต์นั้นทำการแก้ไขได้ โดยช่อง associatedWithDeveloper จะระบุว่าไคลเอ็นต์ OAuth2 ปัจจุบันแก้ไข 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")

ระบบจะระบุนักเรียนด้วยรหัสที่ไม่ซ้ำกันหรืออีเมลของผู้ใช้ตามที่ Google Admin SDK แสดง ผู้ใช้ปัจจุบันยังอ้างอิงถึงรหัสของตนเองได้โดยใช้ตัวย่อ "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

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

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

คุณสามารถแนบลิงก์ไปยังงานที่นักเรียนส่งได้โดยแนบทรัพยากร 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")

ไฟล์แนบลิงก์จะกำหนดโดย URL เป้าหมาย โดย Classroom จะดึงข้อมูลชื่อและภาพปกโดยอัตโนมัติ ดูข้อมูลเกี่ยวกับสื่ออื่นๆ ได้ที่หน้าข้อมูลอ้างอิงที่เกี่ยวข้อง

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

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

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

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

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