Pièces jointes externes et remise

Il s'agit du septième tutoriel de la série de tutoriels sur les modules complémentaires Classroom.

Dans ce tutoriel, vous allez ajouter un comportement à une application Web pour créer des pièces jointes de module complémentaire en dehors de Google Classroom. Utilisez ce comportement pour permettre à vos utilisateurs de créer des pièces jointes de module complémentaire à partir de votre produit ou site Web existant. Il s'agit également d'un excellent ajout à une intégration CourseWork, car vous dirigez le trafic existant vers l'expérience utilisateur améliorée offerte par votre module complémentaire sans modifier son flux. Le processus suggéré est présenté sur la page de notre guide Créer des pièces jointes en dehors de Classroom.

Vous allez également ajouter un comportement à votre module complémentaire pour modifier un devoir avec des pièces jointes de module complémentaire par programmation. Vous pouvez modifier n'importe quel devoir comportant l'une des pièces jointes de votre module complémentaire, quel que soit l'auteur du devoir. Cela est particulièrement utile pour rendre des devoirs une fois qu'un élève a terminé une activité, en signalant à l'enseignant que les tâches attribuées sont terminées et que le travail de l'élève est prêt à être examiné.

Vous allez étendre la version finale de votre module complémentaire qui accepte les pièces jointes de type de contenu ou type d'activité. La pièce jointe de type de contenu est utilisée dans ce guide.

Ajouter l'habilitation OAuth de gestion des devoirs

Assurez-vous que votre application demande les habilitations suivantes :

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

L'habilitation classroom.coursework.students n'était pas nécessaire auparavant et permet de créer ou de modifier des devoirs CourseWork. Ajoutez cette habilitation aux listes d'habilitations du projet Cloud dans le SDK Google Workspace Marketplace, l'écran de consentement OAuth et le code de votre serveur.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

Créer un devoir dans Classroom

Ajouter des boutons à une page Web non intégrée dans un iframe

Le flux décrit dans ce tutoriel permet à un utilisateur de créer des devoirs et des pièces jointes Google Classroom à partir d'un produit non Google. En pratique, il s'agit probablement de votre site Web ou application existant. Pour cet exemple, vous devez créer une page Web factice qui servira de site externe. Vous avez besoin d'un bouton ou d'un lien qui, lorsque vous cliquez dessus, ouvre une nouvelle route qui exécute le flux suggéré CourseWork pour créer un devoir.

Vous devrez également ajouter un bouton ou un lien pour permettre à l'utilisateur de se connecter si vous n'en avez pas déjà un. Vous aurez besoin des identifiants de l'utilisateur pour effectuer les requêtes API suivantes. L'utilisateur doit donc effectuer l'établissement de liaison OAuth 2.0. Pour obtenir des instructions spécifiques, consultez le tutoriel sur la connexion.

Python

L'exemple Python fourni modifie la route /index qui a été introduite lors de la première étape du tutoriel.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

Ajoutez un modèle HTML pour représenter une destination sur votre site Web. Cette page représentera le contenu qui sera joint à votre devoir CourseWork.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

Créez un fichier de module Python pour gérer les routes liées à CourseWork. Il s'agit de coursework_routes.py dans l'exemple fourni. Ajoutez les trois routes suivantes. Notez que vous remplirez une partie du contenu ultérieurement.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

Vérifier si un utilisateur est autorisé à créer des pièces jointes

Un utilisateur doit remplir plusieurs conditions préalables avant que vous puissiez créer des pièces jointes de module complémentaire en son nom. Pour plus de commodité, Google fournit la userProfiles.checkUserCapability méthode pour déterminer si un utilisateur remplit ces conditions préalables. Un utilisateur qui remplit les conditions préalables est appelé utilisateur autorisé.

Ajoutez la vérification d'autorisation à l'implémentation de la route de création CourseWork. Testez ensuite le champ allowed dans la réponse. Pour les utilisateurs autorisés, suivez la logique pour créer un devoir avec une pièce jointe de module complémentaire. Sinon, créez un support de cours avec un lien. Vous devrez connaître l'ID du cours dans lequel l'utilisateur souhaite créer un devoir. En règle générale, vous demandez à l'utilisateur de spécifier le cours à utiliser. Pour simplifier, nous utilisons une valeur codée en dur dans cet exemple.

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # Check whether the user can create add-on attachments.
  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")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

Créer un devoir avec une pièce jointe de module complémentaire pour les utilisateurs autorisés

Si l'utilisateur est autorisé à créer des pièces jointes de module complémentaire, procédez comme suit :

  1. Envoyez une requête API pour créer un devoir courseWork dans Google Classroom sans pièce jointe.
  2. Extrayez l'id du devoir que vous venez de créer.
  3. Créez un CourseWork AddOnAttachment.
  4. Envoyez une requête pour créer une pièce jointe de module complémentaire sur le devoir que vous venez de créer dans Google Classroom.

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  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.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

Si l'utilisateur n'est pas autorisé à créer des pièces jointes de module complémentaire, créez plutôt un support de cours avec un lien en procédant comme suit :

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

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.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

Modifier un devoir déjà créé

Vous pouvez accéder à n'importe quel élément de flux Google Classroom comportant au moins une des pièces jointes de votre module complémentaire, le modifier, le rendre, le récupérer ou le renvoyer, quel que soit l'auteur de l'élément de flux. Les éléments de flux sont des Announcement, des devoirs CourseWork ou des CourseWorkMaterial.

Pour illustrer cela, vous allez ajouter une route pour modifier un élément de flux donné. Utilisez cette méthode pour vérifier que vous pouvez accéder aux éléments de flux que vous avez créés à l'aide de l'API et à ceux créés par un enseignant via l'interface utilisateur de Google Classroom, et les modifier.

Ajoutez un lien ou un bouton supplémentaire à la page Web que vous avez modifiée pour la première fois dans ce tutoriel. Il doit ouvrir une nouvelle route pour modifier un devoir CourseWork.

Python

L'exemple Python fourni modifie la route /index qui a été modifiée précédemment dans ce tutoriel.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

Créez une route pour gérer les routes liées à CourseWork. Elle se trouve dans le fichier coursework_routes.py de l'exemple fourni.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

Tester le module complémentaire

Pour simplifier, les exemples fournis utilisent des identifiants de cours et de devoirs codés en dur. Vous pouvez obtenir ces identifiants en effectuant des requêtes avec des identifiants d'enseignant auprès des méthodes get et list des ressources courses et courseWork. Ils sont également renvoyés dans la réponse lors de la création de devoirs courseWork.

Exécutez votre serveur, puis accédez à votre page d'index et connectez-vous en tant qu'utilisateur enseignant sans licence Google Workspace for Education Teaching and Learning ou Plus. Vous pouvez activer ou désactiver l' état de la licence d'un utilisateur depuis la console d'administration de votre domaine de test.Cliquez sur le bouton Créer un devoir CourseWork, puis ouvrez l'interface utilisateur de Google Classroom et vérifiez qu'un devoir avec une pièce jointe de support de cours avec un lien a été créé. La pièce jointe doit afficher le titre de la page Web associée et une URL.

Tester la création de pièces jointes de module complémentaire

Revenez à la page d'index et connectez-vous en tant qu'utilisateur enseignant avec une licence Google Workspace for Education Teaching and Learning ou Plus. Cliquez sur le bouton Créer un devoir CourseWork, puis ouvrez l'interface utilisateur de Google Classroom et vérifiez qu'un devoir avec une pièce jointe de module complémentaire a été créé. La pièce jointe doit afficher le nom de votre application de module complémentaire et le titre spécifié dans votre code.

Tester la modification d'un devoir

Revenez à la page d'index et assurez-vous d'être connecté en tant qu'utilisateur enseignant avec une licence Teaching and Learning ou Plus. Cliquez sur le bouton Modifier un devoir CourseWork, puis revenez à l'interface utilisateur de Google Classroom et vérifiez que le titre du devoir a été modifié.

Félicitations ! Vous avez terminé la série de tutoriels.