Gestire le attività del corso

L'interfaccia utente di Classroom supporta cinque tipi di lavori del corso: compiti, compiti con quiz, domande a risposta breve, domande a scelta multipla e materiali. Al momento l'API Classroom supporta tre di questi tipi, noti come CourseWorkType per l'API: Compiti, Domande a risposta breve e Domande a scelta multipla.

Nota: è possibile creare Materials come Compiti nell'interfaccia utente di Classroom, tuttavia l'API supporta l'aggancio di Materials solo alle risorse CourseWorkType: Compiti, Domande a risposta breve e Domande a scelta multipla.

Per accedere a questa funzionalità, puoi utilizzare la risorsa CourseWork, che rappresenta un compito o una domanda assegnati agli studenti di un determinato corso, inclusi eventuali materiali e dettagli aggiuntivi, come la data di scadenza o il punteggio massimo.

Oltre alla risorsa CourseWork, puoi gestire i compiti completati con la risorsa StudentSubmission. Le seguenti sezioni descrivono queste in modo più dettagliato.

Crea compiti

I compiti possono essere creati solo per conto degli insegnanti del corso e tentare di creare compiti in un corso per conto di uno studente comporterà un errore 403 PERMISSION_DENIED. Analogamente, gli amministratori di dominio non possono creare compiti per i corsi che non insegnano e il tentativo di farlo tramite l'API comporterà anche un errore 403 PERMISSION_DENIED.

Quando crei i compiti utilizzando il metodo courses.courseWork.create, puoi allegare i link come materials, come mostrato nel codice di esempio riportato di seguito:

Java

classroom/snippets/src/main/java/CreateCourseWork.java

Visualizza su 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

Visualizza su 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)

Il risultato include un identificatore assegnato dal server che può essere utilizzato per fare riferimento all'assegnazione in altre richieste API.

I campi title e workType sono obbligatori. Tutti gli altri campi sono facoltativi. Se state non è specificato, verrà creata una bozza del compito.

Per includere i materiali collegati in un compito creato tramite l'API Classroom, utilizza una risorsa di collegamento, specificando l'URL di destinazione. Classroom recupera automaticamente il titolo e l'immagine in miniatura. L'API Classroom supporta anche in modo nativo i materiali di Google Drive e YouTube, che possono essere inclusi con una risorsa DriveFile o una risorsa YouTubeVideo in modo simile.

Per specificare una data di consegna, imposta i campi dueDate e dueTime sull'ora UTC corrispondente. La data di scadenza deve essere una data futura.

Recuperare compiti e domande

Puoi recuperare i compiti e le domande per gli studenti e gli insegnanti del corso corrispondente o da un amministratore di dominio. Per recuperare un compito o una domanda specifici, utilizza courses.courseWork.get. Per recuperare tutti i compiti o le domande (eventualmente corrispondenti ad alcuni criteri), utilizza courses.courseWork.list.

Se ti interessano solo alcuni campi, ti consigliamo di limitare le richieste a questi campi. Questo può accelerare notevolmente le tue richieste. Per ulteriori dettagli, consulta Utilizzo di risorse parziali.

L'ambito richiesto dipende dal ruolo dell'utente che effettua la richiesta nel corso. Se l'utente è uno studente, utilizza uno dei seguenti ambiti:

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

Se l'utente è un insegnante o un amministratore di dominio, utilizza uno dei seguenti ambiti:

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

Avere l'autorizzazione per recuperare un compito o una domanda non implica necessariamente l'autorizzazione per accedere ai materiali o ai metadati dei materiali. In pratica, questo significa che un amministratore potrebbe non vedere il titolo di un file di Drive allegato se non è un membro del corso. Se vuoi consentire agli amministratori di accedere ai file degli utenti, consulta la guida alla delega a livello di dominio.

Gestire le risposte degli studenti

Una risorsa StudentSubmission rappresenta il lavoro svolto e il voto di uno studente per un compito o una domanda. Quando viene creata una nuova domanda o un nuovo compito, viene creata implicitamente una risorsa StudentSubmission per ogni studente.

I contenuti inviati dagli studenti possono essere modificati solo dal progetto Console per gli sviluppatori che ha creato la risorsa CourseWork corrispondente. Oltre a verificare che l'utente che effettua la richiesta abbia le autorizzazioni corrette. Le modifiche possono essere apportate da qualsiasi client OAuth2 nel progetto; il campo associatedWithDeveloper indica se il client OAuth2 corrente può modificare un determinato StudentSubmission.

Le sezioni seguenti descrivono le azioni comuni per gestire le risposte degli studenti.

Recuperare le risposte degli studenti

Gli studenti possono recuperare i contenuti inviati, gli insegnanti possono recuperare i contenuti inviati per tutti gli studenti dei loro corsi e gli amministratori di dominio possono recuperare tutti i contenuti inviati per tutti gli studenti del loro dominio. A ogni compito inviato dallo studente viene assegnato un identificatore. Se conosci l'identificatore, utilizza courses.courseWork.studentSubmissions.get per recuperarlo.

Utilizza il metodo courses.courseWork.studentSubmissions.list per recuperare le risorse StudentSubmission che soddisfano alcuni criteri, come mostrato nell'esempio seguente:

Java

classroom/snippets/src/main/java/ListSubmissions.java

Visualizza su 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

Visualizza su 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)

Recupera le risorse StudentSubmission che appartengono a un determinato studente specificando il parametro userId, come mostrato nell'esempio seguente:

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java

Visualizza su 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

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

Gli studenti vengono identificati dall'ID univoco o dall'indirizzo email dell'utente, come riportato dall'SDK Admin di Google. L'utente corrente può anche fare riferimento al proprio ID utilizzando la scorciatoia "me".

È anche possibile ricevere i contenuti inviati dagli studenti per tutti i compiti all'interno di un corso. A tal fine, utilizza il valore letterale "-" come courseWorkId, come mostrato nell'esempio seguente:

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

Se ti interessano solo alcuni campi, ti consigliamo di limitare le richieste a questi campi. In questo modo, le richieste possono essere velocizzate notevolmente. Per ulteriori dettagli, consulta la sezione Utilizzo di risorse parziali.

L'ambito richiesto dipende dal ruolo dell'utente che effettua la richiesta nel corso. Utilizza l'ambito seguente se l'utente è un insegnante o un amministratore di dominio:

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

Utilizza il seguente ambito se l'utente è uno studente:

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

Avere l'autorizzazione per recuperare un compito inviato dallo studente non implica necessariamente l'autorizzazione per accedere agli allegati o ai metadati degli allegati. In pratica, ciò significa che un amministratore potrebbe non vedere il titolo di un file di Drive allegato se non è un membro del corso. Se vuoi consentire agli amministratori di accedere ai file degli utenti, consulta la guida sulla delega a livello di dominio.

Aggiungere allegati alla risposta di uno studente

Puoi allegare link a un lavoro inviato dallo studente allegando una risorsa Link, DriveFile o YouTubeVideo. Questa operazione viene eseguita con courses.courseWork.studentSubmissions.modifyAttachments, come mostrato nell'esempio seguente:

Java

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java

Visualizza su 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

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

L'allegato del link viene definito dall'URL di destinazione; Classroom recupererà automaticamente il titolo e l'immagine della miniatura. Puoi scoprire di più sugli altri materiali nelle rispettive pagine di riferimento.

Il StudentSubmission può essere modificato solo dall'insegnante del corso o dall'autore dello stesso. Puoi allegare Materials solo se il valore CourseWorkType dell'invio dello studente è ASSIGNMENT.

L'ambito richiesto dipende dal ruolo dell'utente che effettua la richiesta nel corso. Utilizza il seguente ambito se l'utente è un insegnante:

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

Utilizza il seguente ambito se l'utente è uno studente:

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