Creare allegati al di fuori di Google Classroom

Questa guida illustra come creare allegati aggiuntivi nel tuo sito web o nella tua applicazione. Le interazioni sono simili alla creazione di compiti utilizzando gli endpoint dell'API CourseWork. Implementa questo percorso per consentire agli utenti di creare allegati aggiuntivi dal tuo sito web o dalla tua applicazione.

Importante: ti consigliamo vivamente di implementare questo flusso di creazione degli allegati se già crei compiti CourseWork. L'estensione di un'implementazione di Coursework ti consente di convertire molti più utenti al tuo componente aggiuntivo e richiede un lavoro aggiuntivo minimo.

Flusso di lavoro

A livello generale, il percorso di creazione degli allegati segue questa sequenza:

1. Un utente insegnante apre il tuo sito web o la tua app e seleziona un contenuto da assegnare ai suoi studenti.
2. Verifica che l'utente possa creare allegati dei componenti aggiuntivi.
3. Se l'utente non può creare allegati aggiuntivi, crea un compito Coursework con l'URL dei contenuti selezionati come materiale link.
4. Se l'utente può creare allegati dei componenti aggiuntivi, procedi nel seguente modo:
   1. Crea un compito.
   2. Crea un allegato del componente aggiuntivo che rimandi ai contenuti selezionati e associato al nuovo compito.
5. Comunica all'insegnante che il compito è stato creato correttamente.

Ogni azione è descritta nelle sezioni seguenti.

Verificare se un utente può creare allegati dei componenti aggiuntivi

Puoi creare allegati aggiuntivi per conto di un utente idoneo. Un utente idoneo è un insegnante del corso in cui stai tentando di creare compiti di Coursework e a cui è stata assegnata la licenza della versione Google Workspace for Education Teaching & Learning o Education Plus.

Punto chiave: l'idoneità a creare allegati aggiuntivi può essere diversa per ogni utente e può cambiare nel tempo. Controlla sempre l'idoneità dell'utente prima di tentare di creare allegati aggiuntivi.

Importante: i controlli di idoneità che utilizzano l'API Classroom sono in anteprima pubblica e disponibili nella versione di anteprima V1_20240930_PREVIEW e successive. Per utilizzare i metodi dell'API in anteprima pubblica, devi partecipare al programma Google Workspace Developer Preview e eseguire una configurazione aggiuntiva oltre all'utilizzo tipico dell'API Classroom.

Inizia determinando se l'utente può creare allegati dei componenti aggiuntivi. Puoi farlo inviando una richiesta all'endpoint userProfiles.checkUserCapability con il parametro di funzionalità CREATE_ADD_ON_ATTACHMENT. Controlla il campo booleano allowed nella risposta. Un valore true indica che l'utente è idoneo a creare allegati dei componenti aggiuntivi.

Avviso: non è garantito il buon esito delle richieste di creazione di allegati dei componenti aggiuntivi per gli utenti con la funzionalità CREATE_ADD_ON_ATTACHMENT. Ad esempio, un utente con la funzionalità riceverà un errore di risposta 403 se provi a creare allegati dei componenti aggiuntivi per suo conto in un corso in cui non è insegnante.

Python

eligibility_response = (
  classroom_service.userProfiles()
  .checkUserCapability(
    userId="me",
    capability="CREATE_ADD_ON_ATTACHMENT",
    # The previewVersion is necessary while the method is available in the
    # Workspace Developer Preview Program.
    previewVersion="V1_20240930_PREVIEW",
  ).execute()
)
is_create_attachment_eligible = (
  eligibility_response.get('allowed')
)
print(f'User eligibility for course {course_id}'
      f': {is_create_attachment_eligible}.')

Indirizzare l'utente in base alla sua idoneità

L'idoneità determina se puoi creare allegati di componenti aggiuntivi per un utente.

Importante: i componenti aggiuntivi offrono vantaggi significativi per l'esperienza utente. Crea sempre i componenti aggiuntivi per gli utenti idonei.

Utente non idoneo

Se l'utente non può creare allegati dei componenti aggiuntivi, crea una nuova CourseWork assegnazione con l'URL dei contenuti selezionati dall'utente come Link.

Python

if not is_create_attachment_eligible:
  coursework = {
    'title': 'My CourseWork Assignment with Link Material',
    'description': 'Created using the Classroom CourseWork API.',
    'workType': 'ASSIGNMENT',
    'state': 'DRAFT',  # Set to 'PUBLISHED' to assign to students.
    'maxPoints': 100,
    'materials': [
      {'link': {'url': my_content_url}}
    ]
  }

  assignment = (
    service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Link Material assignment created with ID: {assignment.get("id")}'
  )

La risposta contiene un compito nel corso richiesto con i contenuti allegati. Gli utenti possono fare clic su Link per aprire i contenuti del tuo sito in una nuova scheda.

Figura 1. Visualizzazione lato insegnante di una bozza di compito di CourseWork con materiale collegato.

Utente idoneo

Procedi nel seguente modo se l'utente può creare allegati dei componenti aggiuntivi.

1. Crea un nuovo compito CourseWork senza allegati.
2. Crea un allegato del componente aggiuntivo.
   • Imposta il valore itemId di AddOnAttachment sul valore id del compito appena creato.
   • Assicurati di fornire gli URL dei contenuti selezionati dall'utente per ogni visualizzazione supportata.

Python

if is_create_attachment_eligible:
  coursework = {
    'title': 'My CourseWork Assignment with Add-on Attachment',
    'description': 'Created using the Classroom CourseWork API.',
    'workType': 'ASSIGNMENT',
    'state': 'DRAFT',  # Set to 'PUBLISHED' to assign to students.
    'maxPoints': 100,
  }

  assignment = (
    classroom_service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Empty assignment created with ID: {assignment.get("id")}'
  )

  attachment = {
    'teacherViewUri': {'uri': teacher_view_url},
    'studentViewUri': {'uri': student_view_url},
    'studentWorkReviewUri': {'uri': grade_student_work_url},
    'title': f'Test Attachment {test_label}',
  }

  add_on_attachment = (
    service.courses()
    .courseWork()
    .addOnAttachments()
    .create(
      courseId=course_id,
      itemId=assignment.get("id"),  # ID of the new assignment.
      body=attachment,
    )
    .execute()
  )

  print(
    f'Add-on attachment created with ID: {add_on_attachment.get("id")}'
  )

Nota: non è necessario un token del componente aggiuntivo se crei un allegato per un compito che hai creato.

Il componente aggiuntivo viene visualizzato come scheda di allegato in Classroom. Gli URL specificati nella richiesta si aprono nell'iframe appropriato per ogni visualizzazione.