Gestire il programma dei corsi

L'app Classroom supporta tre tipi di elementi del flusso: CourseWork, CourseWorkMaterials e Announcements. Questa guida descrive come gestire CourseWork, ma le API per tutti gli elementi del flusso sono simili. Consulta le risorse API per scoprire di più sui tipi di elementi del flusso e sulle loro differenze.

La risorsa CourseWork rappresenta un elemento di lavoro assegnato agli studenti di un determinato corso, inclusi eventuali materiali e dettagli aggiuntivi, come la data di scadenza o il punteggio massimo. Esistono quattro sottotipi di CourseWork: compiti, quiz, domande a risposta breve e domande a scelta multipla. L'API Classroom supporta tre di questi sottotipi: compiti, domande a risposta breve e domande a scelta multipla. Questi tipi sono rappresentati dal campo CourseWork.workType.

Oltre alla risorsa CourseWork, puoi gestire il lavoro completato con la risorsa StudentSubmission.

Crea lavori del corso

CourseWork può essere creato solo per conto dell'insegnante del corso. Il tentativo di creare CourseWork per conto di uno studente o di un amministratore di dominio che non è un insegnante del corso genera un errore PERMISSION_DENIED. Consulta la sezione Tipi di utenti per scoprire di più sui diversi ruoli in Classroom.

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

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)

I campi title e workType sono obbligatori. Tutti gli altri campi sono facoltativi. Se state non è specificato, CourseWork viene creato in stato di bozza.

Utilizza una risorsa Link con una destinazione specificata url per includere i materiali collegati in CourseWork. Classroom recupera automaticamente l'title e l'URL dell'immagine in miniatura (thumbnailUrl). L'API Classroom supporta anche in modo nativo i materiali di Google Drive e YouTube, che possono essere inclusi con una risorsa DriveFile o YouTubeVideo in modo simile.

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

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

Retrieve CourseWork

Puoi recuperare CourseWork per conto di studenti e insegnanti del corso corrispondente. Puoi anche recuperare CourseWork per conto degli amministratori di dominio, anche se non sono insegnanti del corso. Per recuperare un CourseWork specifico, utilizza courses.courseWork.get. Per recuperare tutti CourseWork (corrispondenti facoltativamente ad alcuni criteri), utilizza courses.courseWork.list.

L'ambito richiesto dipende dal ruolo dell'utente richiedente 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

L'autorizzazione a recuperare un CourseWork non implica le autorizzazioni per accedere ai materiali o ai metadati dei materiali. In pratica, ciò significa che un amministratore potrebbe non vedere il titolo di un file di Drive allegato se non è membro del corso.

Gestire le risposte degli studenti

Una risorsa StudentSubmission rappresenta il lavoro svolto da uno studente per un CourseWork. La risorsa include metadati relativi al lavoro, ad esempio lo stato e il voto del lavoro. Un StudentSubmission viene creato implicitamente per ogni studente quando viene creato un nuovo CourseWork.

Le sezioni seguenti spiegano le azioni comuni che gestiscono le risposte degli studenti.

Recuperare le risposte degli studenti

Gli studenti possono recuperare i propri invii, gli insegnanti possono recuperare gli invii di tutti gli studenti dei loro corsi e gli amministratori di dominio possono recuperare tutti gli invii di tutti gli studenti del loro dominio. A ogni StudentSubmission viene assegnato un identificatore. Se conosci l'identificatore, utilizza courses.courseWork.studentSubmissions.get per recuperare l'invio.

Utilizza il metodo courses.courseWork.studentSubmissions.list per ottenere tutte le risorse StudentSubmission che corrispondono a determinati criteri, come mostrato nell'esempio seguente:

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)

Recupera le risorse StudentSubmission appartenenti a un determinato studente specificando il parametro userId, come mostrato nel seguente esempio:

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

Gli studenti vengono identificati dall'ID univoco o dall'indirizzo email, come rappresentato nella risorsa Student. L'utente attuale può anche fare riferimento al proprio ID utilizzando l'abbreviazione "me".

È anche possibile recuperare i contenuti inviati dagli studenti per tutti i compiti di un corso. Per farlo, 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()

L'ambito richiesto dipende dal ruolo dell'utente richiedente nel corso. Se l'utente è un insegnante o un amministratore di dominio, utilizza il seguente ambito:

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

Se l'utente è uno studente, utilizza il seguente ambito:

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

L'autorizzazione a recuperare un StudentSubmission non implica l'autorizzazione ad accedere agli allegati o ai relativi metadati. In pratica, ciò significa che un amministratore potrebbe non vedere il titolo di un file di Drive allegato se non è membro del corso.

Aggiungere allegati alla risposta di uno studente

Puoi allegare link a un compito inviato da uno 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
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")

Un Linkallegato è definito dalla destinazione url; Classroom recupera automaticamente il title e l'immagine in miniatura (thumbnailUrl). Consulta Material per scoprire i materiali che possono essere allegati a StudentSubmissions.

Il StudentSubmission può essere modificato solo da un insegnante del corso o dallo studente che ne è proprietario. Puoi allegare Materials solo se il CourseWorkType di StudentSubmission è ASSIGNMENT.

L'ambito richiesto dipende dal ruolo dell'utente richiedente nel corso. Se l'utente è un insegnante, utilizza il seguente ambito:

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

Se l'utente è uno studente, utilizza il seguente ambito:

  • https://www.googleapis.com/auth/classroom.coursework.me
Avanti
Creare e gestire argomenti