Gestire il programma dei corsi

L'app Classroom supporta tre tipi di elementi dello stream: CourseWork, CourseWorkMaterials e Announcements. Questa guida descrive come gestire CourseWork, ma le API per tutti gli elementi dello stream sono simili. Consulta le risorse API per saperne di più sui tipi di elementi stream e sulle relative 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 consegna o il punteggio massimo. Esistono quattro sottotipi di CourseWork: compiti, compiti con 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.

Creare 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 del dominio che non è un insegnante del corso genera un errore CourseWork.PERMISSION_DENIED Consulta la sezione Tipi di utente per scoprire di più sui diversi ruoli di Classroom.

Quando crei CourseWork 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
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 di collegamento con un target specificato url per includere i materiali collegati nel CourseWork. Classroom recupera automaticamente l'URL di title e l'URL immagine della 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 consegna, 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.

Recuperare il programma dei corsi

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

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

L'autorizzazione a recuperare un CourseWork non implica necessariamente l'autorizzazione ad 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 è membro del corso.

Gestire le risposte degli studenti

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

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

Recuperare le risposte degli studenti

Gli studenti possono recuperare i propri 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 StudentSubmission viene assegnato un identificatore. Se conosci l'identificatore, utilizza courses.courseWork.studentSubmissions.get per recuperare i contenuti inviati.

Utilizza il metodo courses.courseWork.studentSubmissions.list per recuperare tutte le risorse StudentSubmission che soddisfano alcuni 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 uno studente specifico specificando il parametro userId, come mostrato nell'esempio seguente:

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 sono identificati dall'ID univoco o dall'indirizzo email, come rappresentato nella risorsa Student. L'utente corrente può anche fare riferimento al proprio ID utilizzando la sigla"me".

È anche possibile recuperare 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()

L'ambito richiesto dipende dal ruolo dell'utente che effettua la richiesta 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 metadati degli allegati. In pratica, questo significa che un amministratore potrebbe non vedere il titolo di un file di Drive allegato se non è un membro del corso.

Aggiungere allegati a una risposta dello 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
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 allegato Link è definito dal url di destinazione; 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 dall'insegnante del corso o dall'autore dello stesso. Puoi allegare Materials solo se il CourseWorkType del StudentSubmission è ASSIGNMENT.

L'ambito richiesto dipende dal ruolo dell'utente che effettua la richiesta 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