Gerenciar atividades

A interface do Google Sala de Aula é compatível com cinco tipos de atividades: Atividades, Atividades de teste, Perguntas de resposta curta, Perguntas de múltipla escolha e Materiais. No momento, a API Classroom oferece suporte a três desses tipos, que são conhecidos como CourseWorkType para a API: atividades, perguntas de resposta curta e de múltipla escolha.

Para acessar essa funcionalidade, use o recurso CourseWork, que representa uma atividade ou pergunta atribuída aos estudantes em um curso específico, incluindo materiais e detalhes adicionais, como data de entrega ou pontuação máxima.

Além do recurso CourseWork, é possível gerenciar tarefas concluídas com o recurso StudentSubmission. As seções a seguir descrevem esses detalhes.

Criar atividades

As atividades só podem ser criadas em nome dos professores do curso, e tentar criar atividades em um curso em nome de um estudante vai resultar em um erro PERMISSION_DENIED 403. Da mesma forma, os administradores de domínio também não podem criar atividades para cursos que não ministram. Tentar fazer isso pela API também resultará em um erro 403 PERMISSION_DENIED.

Ao criar atribuições usando o método courses.courseWork.create, você pode anexar links como materials, conforme mostrado no exemplo de código abaixo:

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)

O resultado inclui um identificador atribuído pelo servidor que pode ser usado para referenciar a atribuição em outras solicitações de API.

Para incluir materiais vinculados em uma atividade criada pela API Classroom, use um recurso de link, especificando o URL de destino. O Google Sala de Aula busca automaticamente o título e a imagem da miniatura. A API Classroom também oferece suporte nativo a materiais do Google Drive e do YouTube, que podem ser incluídos com um recurso DriveFile ou YouTubeVideo de maneira semelhante.

Para especificar uma data de entrega, defina os campos dueDate e dueTime como o horário UTC correspondente. A data de conclusão precisa estar no futuro.

Recuperar atividades e perguntas

É possível recuperar atividades e perguntas para estudantes e professores do curso correspondente ou por um administrador de domínio. Para recuperar uma atividade ou pergunta específica, use courses.courseWork.get. Para recuperar todas as atividades ou perguntas (se corresponderem a alguns critérios), use courses.courseWork.list.

O escopo necessário depende da função que o usuário solicitante tem no curso. Se o usuário for um estudante, use um dos seguintes escopos:

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

Se o usuário for um professor ou administrador de domínio, use um dos seguintes escopos:

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

Ter permissão para recuperar uma atividade ou pergunta não implica permissões para acessar materiais ou metadados de materiais. Na prática, isso significa que um administrador não poderá ver o título de um arquivo do Drive anexado se não for membro do curso. Se você quiser permitir que os administradores acessem os arquivos do usuário, consulte o guia delegação em todo o domínio.

Gerenciar as respostas dos estudantes

Um recurso StudentSubmission representa o trabalho feito e a nota de um estudante para uma atividade ou pergunta. Um recurso StudentSubmission é criado implicitamente para cada estudante quando uma nova pergunta ou atividade é criada.

As seções a seguir explicam ações comuns que gerenciam as respostas dos estudantes.

Recuperar as respostas dos estudantes

Os estudantes podem recuperar as próprias atividades enviadas, os professores podem recuperar as atividades de todos os estudantes nos cursos e os administradores de domínio podem recuperar todas as atividades de todos os estudantes no domínio. Cada envio de estudante recebe um identificador. Se você souber o identificador, use courses.courseWork.studentSubmissions.get para recuperá-lo.

Use o método courses.courseWork.studentSubmissions.list para acessar recursos StudentSubmission que correspondem a alguns critérios, conforme mostrado no exemplo abaixo:

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

sala de aula/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)

Extraia recursos StudentSubmission que pertencem a um estudante específico, especificando o parâmetro userId, conforme mostrado no exemplo a seguir:

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

Os alunos são identificados pelo ID exclusivo ou endereço de e-mail do usuário, conforme retornado pelo SDK Admin do Google. O usuário atual também pode se referir ao próprio ID usando a abreviação "me".

Também é possível receber envios de estudantes para todas as atividades em um curso. Para fazer isso, use o literal "-" como courseWorkId, conforme mostrado no exemplo abaixo:

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

O escopo necessário depende da função que o usuário solicitante tem no curso. Use o escopo a seguir se o usuário for professor ou administrador de domínio:

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

Use o seguinte escopo se o usuário for um estudante:

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

Ter permissão para recuperar uma entrega de estudante não implica permissões para acessar anexos ou metadados de anexos. Na prática, isso significa que um administrador não poderá ver o título de um arquivo do Drive anexado se não for membro do curso. Se você quiser permitir que os administradores acessem os arquivos do usuário, consulte o guia delegação em todo o domínio.

Como adicionar anexos a uma resposta do estudante

É possível anexar links a um envio de estudante anexando um recurso Link, DriveFile ou YouTubeVideo. Isso é feito com courses.courseWork.studentSubmissions.modifyAttachments, conforme mostrado no exemplo abaixo:

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

sala de aula/snippets/sala_de_aula_adicionar_anexo.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")

Um anexo de link é definido pelo URL de destino. O Google Sala de Aula extrai automaticamente o título e a imagem em miniatura. Você pode aprender sobre os outros materiais nas respectivas páginas de referência.

O StudentSubmission só pode ser modificado por um professor do curso ou pelo aluno a que ele pertence. Só é possível anexar Materials se o CourseWorkType do envio do estudante for ASSIGNMENT.

O escopo necessário depende do papel que o usuário solicitante tem no curso. Use o seguinte escopo se o usuário for um professor:

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

Use o escopo a seguir se o usuário for um estudante:

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