Creare allegati al di fuori di Google Classroom

Questa guida spiega come creare allegati aggiuntivi sul tuo sito web o nella tua applicazione. Le interazioni sono simili a creare 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 crei già compiti CourseWork. L'estensione di un'implementazione di CourseWork ti consente di convertire molti più utenti al tuo componente aggiuntivo e richiede poco lavoro aggiuntivo.

Flusso di lavoro

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

1. Un 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 aggiuntivi.
3. Se l'utente non può creare allegati aggiuntivi, crea un compito CourseWork con l'URL del contenuto selezionato come materiale di tipo Link.
4. Se l'utente può creare allegati aggiuntivi:
   1. Crea un compito.
   2. Crea un allegato aggiuntivo che rimandi al contenuto selezionato e associa questo allegato al nuovo compito.
5. Informa l'insegnante che il compito è stato creato correttamente.

Ogni azione è descritta nelle sezioni seguenti.

Verificare se un utente può creare allegati aggiuntivi

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

Punto chiave: l'idoneità alla creazione di allegati aggiuntivi può variare da utente a utente e può cambiare nel tempo. Controlla sempre l'idoneità dell'utente prima di tentare di creare allegati aggiuntivi.

Importante: i controlli di idoneità tramite l'API Classroom sono in anteprima pubblica e disponibili nella versione di anteprima V1_20240930_PREVIEW e successive. Per utilizzare i metodi API in anteprima pubblica, devi far parte del Programma Anteprima per sviluppatori di Google Workspace ed eseguire una configurazione aggiuntiva rispetto al normale utilizzo dell'API Classroom.

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

Avviso: non è garantito che le richieste di creazione di allegati aggiuntivi per gli utenti con la funzionalità CREATE_ADD_ON_ATTACHMENT vadano a buon fine. Ad esempio, un utente con la funzionalità riceverà un errore di risposta 403 se tenti di creare allegati aggiuntivi per suo conto in un corso in cui l'utente non è un 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('User eligibility for add-on attachment creation: '
      f'{is_create_attachment_eligible}.')

Instradare l'utente in base alla sua idoneità

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

Importante: i componenti aggiuntivi offrono notevoli vantaggi in termini di esperienza utente. Crea sempre allegati aggiuntivi per gli utenti idonei.

Utente non idoneo

Se l'utente non può creare allegati aggiuntivi, crea un nuovo CourseWork compito con l'URL del contenuto selezionato 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 il contenuto allegato. Gli utenti possono fare clic sul Link per aprire il contenuto nel tuo sito in una nuova scheda.

Figura 1. Visualizzazione da parte dell'insegnante di una bozza di compito CourseWork con materiale di tipo Link.

Utente idoneo

Se l'utente può creare allegati aggiuntivi:

1. Crea un nuovo compito CourseWork senza allegati.
2. Crea un allegato aggiuntivo.
   • Imposta AddOnAttachment's itemId sull'id del compito appena creato.
   • Assicurati di fornire gli URL al contenuto selezionato dall'utente per ogni visualizzazione che supporti.

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 a un compito che hai creato tu.

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