Pièces jointes externes et remise

Il s'agit du septième tutoriel des modules complémentaires Classroom cette série de tutoriels.

Dans ce tutoriel, vous allez ajouter un comportement à une application Web pour créer un module complémentaire pièces jointes provenant d'autres sources que Google Classroom. Utilisez ce comportement les utilisateurs créent des pièces jointes de module complémentaire à partir de votre produit ou site Web existant. C'est C'est aussi un excellent ajout à l'intégration CourseWork, car vous dirigez vers l'expérience utilisateur améliorée offerte par votre module complémentaire, sans la modifier leur flux. La procédure suggérée est présentée dans la section Créer des pièces jointes en dehors de Classroom.

Vous pouvez également ajouter un comportement à votre module complémentaire pour modifier un devoir à l'aide d'un module complémentaire. pièces jointes par programmation. Vous pouvez modifier les attributions associées à l'une des les pièces jointes du module complémentaire, quel que soit le créateur du devoir. C'est particulièrement utile pour rendre son devoir après qu'un élève a terminé activité, signalant à l'enseignant que les tâches assignées sont terminées et que le travail de l'élève est prêt à être corrigé.

Vous étendez la version finale de votre module complémentaire, qui prend en charge content-type ou pièces jointes liées au type d'activité. La pièce jointe content-type est utilisée dans ce guide.

Important :Avant de suivre ce tutoriel, terminez les précédents. de la série. Ce tutoriel développe l'application Web développée dans l'atelier des tutoriels vidéo. Vous pouvez télécharger le code source complet de tous les tutoriels sur la page "Vue d'ensemble". Le code de cette présentation est disponible dans le répertoire /07-external-attachments/.

Ajouter le champ d'application OAuth pour la gestion des attributions

Assurez-vous que votre application demande les champs d'application suivants:

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

Le champ d'application classroom.coursework.students n'était pas nécessaire auparavant et est utilisée pour créer ou modifier des attributions CourseWork. Ajouter ce champ d'application aux listes de champs d'application le SDK Google Workspace Marketplace, l'écran de consentement OAuth et vos le code du 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

Important :Ne modifiez aucune de vos expériences iFrame dans ce tutoriel étape. À la place, ajoutez un comportement pour créer des pièces jointes de module complémentaire à partir d'une page Web située en dehors de Classroom.

Ajouter des boutons à une page Web non iFrame

Le flux décrit dans ce tutoriel permet à un utilisateur de créer Devoirs et pièces jointes Google Classroom à partir d'un produit autre que Google. Dans il s'agit probablement de votre site Web ou application existant. Pour cet exemple, vous devez créer une page web fictive qui fera office de site externe. Vous avez besoin d'un bouton ou lien qui, lorsque vous cliquez dessus, ouvre une nouvelle route qui exécute les suggestions flux CourseWork pour créer un devoir.

Vous devez également ajouter un bouton ou un lien permettant à l'utilisateur de se connecter si vous n'en avez pas encore. Vous aurez besoin des identifiants de l'utilisateur pour effectuer les Requêtes API. Elles doivent donc effectuer le handshake OAuth 2.0. Consultez la page de connexion tutoriel pour obtenir des conseils spécifiques.

Python

L'exemple Python fourni modifie la route /index introduite à 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 associé à votre CourseWork l'attribution.

<!-- /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 associées à CourseWork. Dans notre exemple, il s'agit de coursework_routes.py. Ajoutez les éléments suivants : trois itinéraires, notez que vous remplirez une partie du contenu plus tard.

# /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")

Important :Ajoutez de nouvelles routes de rappel OAuth à vos ID client OAuth. URI de redirection autorisés sur la page Identifiants de votre projet Google Cloud. Pour l'exemple fourni, vous devez ajouter https://<<your server>>/index et https://<<your server>>/coursework-assignment-callback.

Vérifier si un utilisateur peut créer un module complémentaire

Important :Vérifiez toujours si un utilisateur peut créer des pièces jointes de modules complémentaires. avant d'essayer de créer des pièces jointes de module complémentaire. Les critères d'éligibilité peuvent être différents en fonction de l'utilisateur, du cours et de votre projet Cloud.

Un utilisateur doit remplir plusieurs conditions préalables avant de pouvoir créer des pièces jointes de module complémentaire en leur nom. Pour plus de commodité, Google propose La méthode courses.checkAddOnCreationEligibility pour déterminer si un utilisateur remplit ces conditions préalables. Un utilisateur qui remplit les conditions préalables est appelé Un utilisateur éligible

Ajoutez la vérification d'éligibilité à l'implémentation de la route de création CourseWork. Testez ensuite le champ isCreateAttachmentEligible dans la réponse. Pour les utilisateurs éligibles les utilisateurs, suivez la logique pour créer un devoir avec un module complémentaire pièce jointe. Sinon, créez un Lien Support de cours. Vous devez connaître l'ID du cours dans pour laquelle l'utilisateur souhaite créer une attribution. Normalement, vous demanderez à l'utilisateur pour spécifier le cours à utiliser. Pour plus de simplicité, nous utilisons une valeur codée en dur dans cet exemple.

Important :Créez toujours des pièces jointes de module complémentaire si l'utilisateur est éligible. Modules complémentaires offrent aux utilisateurs et aux développeurs une expérience de qualité supérieure pour les éléments de lien.

Remarque :Le champ isCreateAttachmentEligible n'est renseigné que lorsque le l'utilisateur est éligible. Il est possible qu'il ne soit pas présent dans la réponse.

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 ...

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

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  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 éligibles

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

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

Important :Vous devez envoyer les deux requêtes séparément. CourseWork l'attribution doit avoir été créée correctement pour que la nouvelle pièce jointe de module complémentaire puisse être associé à un ID d'attribution.

Python

# /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()
  )

Créer un support de lien

Important :Si votre produit crée déjà des attributions CourseWork, il est probable suit déjà le flux présenté ici.

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

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.
        # 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 une attribution déjà créée

Important :L'un des principaux avantages des modules complémentaires est qu'ils vous procurent possibilité d'envoyer des requêtes API sur l'élément de flux parent

Vous pouvez accéder à n'importe quel compte Google Classroom, le modifier, le rendre ou l'annuler élément de flux comportant au moins une pièce jointe de votre module complémentaire, peu importe qui a créé l'élément de flux. Les éléments de flux sont de type Announcement ou CourseWork. attribution, ou CourseWorkMaterial.

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

Ajoutez un autre lien ou bouton à la page Web que vous avez initialement modifiée sur dans ce tutoriel. Il doit ouvrir une nouvelle route pour modifier un CourseWork l'attribution.

Python

L'exemple Python fourni modifie la route /index qui a été modifiée plus tôt 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 associées à CourseWork. C'est dans coursework_routes.py dans 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

Important :À ce stade du développement, vous ne pouvez tester votre application que dans les iFrames des modules complémentaires Classroom. Lisez notre guide sur les iFrames et les requêtes des paramètres pour obtenir une description de chaque iFrame. Toutes les instructions fournies dans ce tutoriel supposent que le module complémentaire est utilisable dans le contexte d'une iFrame.

Pour plus de simplicité, les exemples fournis utilisent un cours et les identifiants d'attribution. Vous pouvez obtenir ces identifiants en envoyant des requêtes avec identifiants d'enseignant aux méthodes get et list de la courses et courseWork ressources. Elles sont également renvoyées dans la réponse lors de la création courseWork devoirs.

Tester la création de Material Links

Exécutez votre serveur, puis accédez à votre page d'index et connectez-vous en tant qu'utilisateur enseignant sans Google Workspace for Education Teaching and Licence Learning ou Plus. Vous pouvez activer/désactiver l'état de la licence de l'utilisateur de votre domaine test dans la console d'administration. Cliquez sur Create a CourseWork Assignment (Créer un devoir CourseWork). , puis ouvrez l'interface utilisateur de Google Classroom et vérifiez qu'un devoir avec La pièce jointe Material du lien a été créée. La pièce jointe doit afficher le titre la page Web lié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'enseignant avec un compte Google Workspace for Education Teaching & Licence Learning ou Plus. Cliquez sur le bouton Create a CourseWork Assignment (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éée. La pièce jointe doit indiquer le nom de votre et le titre spécifié dans votre code.

Modifier un devoir de test

Revenez à la page d'index et vérifiez que vous êtes connecté en tant qu'utilisateur enseignant avec un cours Licence Learning ou Plus. Cliquez sur le bouton Modify a CourseWork Devoir, puis revenez à l'UI de Google Classroom et vérifiez que le titre du devoir a été modifié.

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