Créer des pièces jointes en dehors de Google Classroom

Ce guide explique comment créer des pièces jointes de modules complémentaires sur votre site Web ou dans votre application. Les interactions sont semblables à la création de devoirs à l'aide des points de terminaison de l'API CourseWork. Implémentez ce parcours pour permettre aux utilisateurs de créer des pièces jointes de modules complémentaires depuis votre site Web ou votre application.

Important : Nous vous recommandons vivement d'implémenter ce flux de création de pièces jointes si vous créez déjà des devoirs CourseWork. L'extension d'une implémentation CourseWork vous permet de convertir beaucoup plus d'utilisateurs à votre module complémentaire et nécessite peu de travail supplémentaire.

Workflow

Dans les grandes lignes, le parcours de création de pièces jointes suit cette séquence :

1. Un enseignant ouvre votre site Web ou votre application, puis sélectionne un contenu à attribuer à ses élèves.
2. Vérifiez que l'utilisateur peut créer des pièces jointes de modules complémentaires.
3. Si l'utilisateur ne peut pas créer de pièces jointes de module complémentaire, créez un devoir CourseWork avec l'URL du contenu sélectionné en tant que lien.
4. Si l'utilisateur peut créer des pièces jointes de modules complémentaires, procédez comme suit :
   1. Créez un devoir.
   2. Créez une pièce jointe de module complémentaire qui renvoie au contenu sélectionné et associez-la au nouveau devoir.
5. Indiquez à l'enseignant que le devoir a bien été créé.

Chaque action est décrite dans les sections suivantes.

Vérifier si un utilisateur peut créer des pièces jointes de modules complémentaires

Vous pouvez créer des pièces jointes de modules complémentaires au nom d'un utilisateur éligible. Un utilisateur éligible est un enseignant du cours dans lequel vous essayez de créer des devoirs et qui dispose d'une licence Teaching and Learning ou Education Plus de l'édition Google Workspace for Education.

Point clé : L'éligibilité à la création de pièces jointes complémentaires peut varier d'un utilisateur à l'autre et évoluer au fil du temps. Vérifiez toujours l'éligibilité de l'utilisateur avant de tenter de créer des pièces jointes de module complémentaire.

Important : Les vérifications de l'éligibilité à l'aide de l'API Classroom sont en version Preview publique et disponibles dans la version V1_20240930_PREVIEW et ultérieures. Pour utiliser les méthodes d'API en version Preview publique, vous devez participer au programme Preview développeur Google Workspace et effectuer une configuration supplémentaire par rapport à l'utilisation habituelle de l'API Classroom.

Commencez par déterminer si l'utilisateur peut créer des pièces jointes de module complémentaire. Pour ce faire, envoyez une requête au point de terminaison userProfiles.checkUserCapability avec le paramètre de capacité CREATE_ADD_ON_ATTACHMENT. Examinez le champ booléen allowed dans la réponse. Une valeur true indique que l'utilisateur est autorisé à créer des pièces jointes de modules complémentaires.

Avertissement : Il n'est pas garanti que les demandes de création de pièces jointes de modules complémentaires pour les utilisateurs disposant de la fonctionnalité CREATE_ADD_ON_ATTACHMENT aboutissent. Par exemple, un utilisateur disposant de cette fonctionnalité recevra une erreur de réponse 403 si vous tentez de créer des pièces jointes de modules complémentaires en son nom dans un cours dans lequel il n'est pas enseignant.

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}.')

Rediriger l'utilisateur en fonction de son éligibilité

L'éligibilité détermine si vous pouvez créer des pièces jointes de modules complémentaires pour un utilisateur.

Important : Les modules complémentaires offrent des avantages considérables en termes d'expérience utilisateur. Créez toujours des pièces jointes pour les utilisateurs éligibles.

Utilisateur non éligible

Si l'utilisateur ne peut pas créer de pièces jointes de modules complémentaires, créez un devoir CourseWork avec l'URL du contenu sélectionné par l'utilisateur en tant que 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 réponse contient un devoir dans le cours demandé, avec le contenu joint. Les utilisateurs peuvent cliquer sur Link pour ouvrir le contenu de votre site dans un nouvel onglet.

Figure 1. Vue enseignant d'un devoir de cours en brouillon avec un lien vers un support de cours.

Utilisateur éligible

Procédez comme suit si l'utilisateur peut créer des pièces jointes de modules complémentaires.

1. Créez un devoir CourseWork sans pièce jointe.
2. Créez une pièce jointe de module complémentaire.
   • Définissez le itemId de AddOnAttachment sur le id du devoir que vous venez de créer.
   • Assurez-vous de fournir des URL vers le contenu sélectionné par l'utilisateur pour chaque vue que vous acceptez.

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

Remarque : Un jeton de module complémentaire n'est pas nécessaire si vous créez une pièce jointe pour un devoir que vous avez créé.

Le module complémentaire apparaît sous la forme d'une fiche de pièce jointe dans Classroom. Les URL spécifiées dans la requête s'ouvrent dans l'iframe approprié pour chaque vue.