Gerenciar tarefas

O app Sala de Aula é compatível com três tipos de itens do mural: CourseWork, CourseWorkMaterials e Announcements. Este guia descreve como gerenciar CourseWork, mas as APIs para todos os itens de stream são semelhantes. Consulte Recursos da API para saber mais sobre os tipos de itens de stream e as diferenças entre eles.

O recurso CourseWork representa um item de trabalho atribuído a estudantes em um curso específico, incluindo materiais e detalhes adicionais, como data de entrega ou pontuação máxima. Há quatro subtipos de CourseWork: atividades, atividades com teste, perguntas de resposta curta e perguntas de múltipla escolha. A API Classroom é compatível com três desses subtipos: atividades, perguntas de resposta curta e perguntas de múltipla escolha. Esses tipos são representados pelo campo CourseWork.workType.

Além do recurso CourseWork, é possível gerenciar o trabalho concluído com o recurso StudentSubmission.

Criar atividades

Os CourseWork só podem ser criados em nome do professor do curso. A tentativa de criar CourseWork em nome de um estudante ou de um administrador de domínio que não seja professor do curso resulta em um erro PERMISSION_DENIED. Consulte Tipos de usuários para saber mais sobre as diferentes funções no Google Sala de Aula.

Ao criar CourseWork 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)

Os campos title e workType são obrigatórios. Todos os outros campos são opcionais. Se state não for especificado, o CourseWork será criado em um estado de rascunho.

Use um recurso de link com um destino especificado url para incluir materiais vinculados no CourseWork. A Sala de Aula busca automaticamente o title e o URL da imagem em miniatura (thumbnailUrl). 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 vencimento, defina os campos dueDate e dueTime com o horário UTC correspondente. A data de vencimento precisa estar no futuro.

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

Recuperar CourseWork

Você pode recuperar CourseWork em nome dos estudantes e professores do curso correspondente. Você também pode recuperar CourseWork em nome dos administradores do domínio, mesmo que eles não sejam professores do curso. Para recuperar um CourseWork específico, use courses.courseWork.get. Para recuperar todos os CourseWork (opcionalmente correspondendo 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 do 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 um CourseWork não implica permissões para acessar materiais ou metadados de materiais. Na prática, isso significa que um administrador talvez não veja o título de um arquivo anexado do Drive se não for participante do curso.

Gerenciar respostas dos estudantes

Um recurso StudentSubmission representa o trabalho feito por um estudante para uma CourseWork. O recurso inclui metadados relacionados ao trabalho, como status e nota. Um StudentSubmission é criado implicitamente para cada estudante quando um novo CourseWork é criado.

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

Recuperar respostas dos estudantes

Os estudantes podem recuperar os próprios envios, os professores podem recuperar os envios de todos os estudantes dos cursos, e os administradores de domínio podem recuperar todos os envios de todos os estudantes do domínio. Cada StudentSubmission recebe um identificador. Se você souber o identificador, use courses.courseWork.studentSubmissions.get para recuperar o envio.

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

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)

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

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 estudantes são identificados pelo ID exclusivo ou endereço de e-mail, conforme representado no recurso Student. O usuário atual também pode se referir à própria ID usando o atalho "me".

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

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. Se o usuário for um professor ou administrador do domínio, use o seguinte escopo:

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

Se o usuário for um estudante, use o seguinte escopo:

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

Ter permissão para recuperar um StudentSubmission não implica permissões para acessar anexos ou metadados de anexos. Na prática, isso significa que um administrador pode não ver o título de um arquivo anexado do Drive se não for participante do curso.

Adicionar anexos a uma resposta de estudante

É possível anexar links a uma atividade enviada por um estudante anexando um recurso Link, DriveFile ou YouTubeVideo. Isso é feito com courses.courseWork.studentSubmissions.modifyAttachments, conforme mostrado na amostra a seguir:

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

Um anexo Link é definido pelo destino url. O Google Sala de Aula busca automaticamente o title e a imagem em miniatura (thumbnailUrl). Consulte Material para saber mais sobre os materiais que podem ser anexados a StudentSubmissions.

O StudentSubmission só pode ser modificado por um professor do curso ou pelo estudante que é o proprietário dele. Só é possível anexar Materials se o CourseWorkType do StudentSubmission for ASSIGNMENT.

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

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

Se o usuário for um estudante, use o seguinte escopo:

  • https://www.googleapis.com/auth/classroom.coursework.me
Avançar
Criar e gerenciar tópicos