Zarządzanie materiałami dydaktycznymi

Aplikacja Classroom obsługuje 3 typy elementów strumienia: CourseWork, CourseWorkMaterials i Announcements. Ten przewodnik opisuje, jak zarządzać CourseWork, ale interfejsy API wszystkich elementów strumienia są podobne. Więcej informacji o typach elementów strumienia i ich różnicach znajdziesz w zasobach interfejsu API.

Zasób CourseWork reprezentuje element pracy przypisany do studentów w ramach konkretnego kursu, w tym wszelkie dodatkowe materiały i szczegóły, takie jak termin wykonania lub maksymalna liczba punktów. Istnieją 4 podtypy CourseWork: projekty, projekty – testy, pytania z krótkimi odpowiedziami i pytania jednokrotnego wyboru. Interfejs Classroom API obsługuje 3 podtypy: projekty, pytania z krótką odpowiedzią i pytania jednokrotnego wyboru. Te typy są reprezentowane przez pole CourseWork.workType.

Oprócz zasobu CourseWork możesz zarządzać zakończoną pracą za pomocą zasobu StudentSubmission.

Tworzenie zadań

CourseWork można tylko utworzyć w imieniu nauczyciela. Próba utworzenia CourseWork w imieniu ucznia lub administratora domeny, który nie jest nauczycielem w kursie, powoduje błąd PERMISSION_DENIED. Aby dowiedzieć się więcej o różnych rolach w Classroom, zapoznaj się z artykułem Typy użytkowników.

Podczas tworzenia CourseWork za pomocą metody courses.courseWork.create możesz dołączać linki jako materials, jak pokazano w przykładowym kodzie poniżej:

Java

classroom/snippets/src/main/java/CreateCourseWork.java
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
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)

Pola title i workType są wymagane. Wszystkie pozostałe pola są opcjonalne. Jeśli parametr state nie jest określony, element CourseWork jest tworzony w stanie roboczym.

Aby uwzględnić w CourseWork połączone materiały, użyj zasobu linku z określonym celem url. Classroom automatycznie pobiera adres URL title i adres URL obrazu miniatury (thumbnailUrl). Interfejs API Classroom obsługuje też natywny interfejs Google Drive i materiały z YouTube, które można dołączać w podobny sposób za pomocą zasobu DriveFile lub YouTubeVideo.

Aby określić termin, ustaw pola dueDate i dueTime na odpowiadający czas w UTC. Termin musi przypadać w przyszłości.

Odpowiedź CourseWork zawiera przypisany przez serwer identyfikator, którego można użyć do odwołania się do przypisania w innych żądaniach interfejsu API.

Pobieranie CourseWork

Możesz pobrać CourseWork w imieniu uczniów i nauczycieli danego kursu. Możesz też pobierać dane CourseWork w imieniu administratorów domeny, nawet jeśli nie są oni nauczycielami na zajęciach. Aby pobrać konkretny CourseWork, użyj courses.courseWork.get. Aby pobrać wszystkie dane CourseWork (opcjonalnie z uwzględnieniem niektórych kryteriów), użyj parametru courses.courseWork.list.

Wymagany zakres zależy od roli, jaką ma użytkownik przesyłający prośbę w ramach kursu. Jeśli użytkownik jest uczniem, użyj jednego z tych zakresów uprawnień:

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

Jeśli użytkownik jest nauczycielem lub administratorem domeny, użyj jednego z tych zakresów:

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

Posiadanie uprawnień do pobrania CourseWork nie oznacza uprawnień do dostępu do materiałów ani metadanych materiałów. W praktyce oznacza to, że administrator może nie widzieć tytułu załączonego pliku na Dysku, jeśli nie jest uczestnikiem zajęć.

Zarządzanie odpowiedziami uczniów

Zasób StudentSubmission odpowiada pracy wykonanej przez ucznia w ramach zadania CourseWork. Zasób zawiera metadane związane z pracą, takie jak jej stan i ocena. Podczas tworzenia nowego CourseWork dla każdego ucznia jest tworzony StudentSubmission.

W poniższych sekcjach opisujemy typowe działania związane z zarządzaniem odpowiedziami uczniów.

Pobieranie odpowiedzi uczniów

Uczniowie mogą pobierać swoje projekty, nauczyciele mogą pobierać projekty wszystkich uczniów na swoich zajęciach, a administratorzy domen mogą pobierać wszystkie projekty wszystkich uczniów w domenie. Każdemu StudentSubmission przypisany jest identyfikator. Jeśli znasz identyfikator, użyj courses.courseWork.studentSubmissions.get, aby pobrać przesłane dane.

Aby pobrać wszystkie zasoby StudentSubmission, które spełniają określone kryteria, użyj metody courses.courseWork.studentSubmissions.list, jak pokazano w tym przykładzie:

Java

classroom/snippets/src/main/java/ListSubmissions.java
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
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)

Pobierz zasoby StudentSubmission należące do konkretnego ucznia, podając parametr userId, jak w tym przykładzie:

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java
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
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")

Uczniowie są identyfikowani na podstawie unikalnego identyfikatora lub adresu e-mail, jak podano w zasobie Student. Bieżący użytkownik może też odwoływać się do swojego identyfikatora za pomocą skrótu "me".

Możesz też pobrać prace uczniów z wszystkich projektów w danym kursie. W tym celu użyj literalnego ciągu "-" jako courseWorkId, jak w tym przykładzie:

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()

Wymagany zakres zależy od roli, jaką ma użytkownik przesyłający prośbę w ramach kursu. Jeśli użytkownik jest nauczycielem lub administratorem domeny, użyj tego zakresu:

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

Jeśli użytkownik jest uczniem, użyj tego zakresu:

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

Uprawnienia do pobierania StudentSubmission nie oznaczają uprawnień do dostępu do załączników ani metadanych załączników. W praktyce oznacza to, że administrator może nie widzieć tytułu załączonego pliku z Dysku, jeśli nie jest uczestnikiem zajęć.

Dodawanie załączników do odpowiedzi ucznia

Linki do zadań uczniów możesz dołączać, dołączając zasób Link, DriveFile lub YouTubeVideo. Aby to zrobić, użyj funkcji courses.courseWork.studentSubmissions.modifyAttachments, jak w tym przykładzie:

Java

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java
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
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")

Załącznik Link jest definiowany przez docelowy element url; Classroom automatycznie pobiera title i miniaturę (thumbnailUrl). Więcej informacji o materiałach, które można dołączyć do StudentSubmissions, znajdziesz w sekcji Material.

StudentSubmission może być modyfikowany tylko przez nauczyciela prowadzącego zajęcia lub ucznia, który jest jego właścicielem. Możesz załączyć Materials tylko wtedy, gdy CourseWorkType wartości StudentSubmission to ASSIGNMENT.

Wymagany zakres zależy od roli, jaką ma użytkownik przesyłający prośbę w ramach kursu. Jeśli użytkownik jest nauczycielem, użyj tego zakresu:

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

Jeśli użytkownik jest uczniem, użyj tego zakresu:

  • https://www.googleapis.com/auth/classroom.coursework.me
Dalej
Tworzenie tematów i zarządzanie nimi