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 modules complémentaires en dehors de Google Classroom. Utilisez ce comportement pour permettre à vos utilisateurs de créer des pièces jointes de modules complémentaires à partir de votre produit ou site Web existants. Il s'agit également d'un excellent ajout à l'intégration de 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. La procédure suggérée est présentée sur la page du guide Créer des pièces jointes en dehors de Classroom.
Vous pouvez également ajouter un comportement à votre module complémentaire pour modifier un devoir avec des pièces jointes de modules complémentaires par programmation. Vous pouvez modifier tous les devoirs comportant l'une des pièces jointes de modules complémentaires, quel que soit leur auteur. Cela est particulièrement utile pour rendre les devoirs une fois qu'un élève a terminé une activité, pour signaler à l'enseignant que les tâches attribuées sont terminées et que le travail de l'élève est prêt à être corrigé.
Étendez la version finale de votre module complémentaire qui accepte les pièces jointes content-type ou activity-type. La pièce jointe de type contenu est utilisée dans ce guide.
Ajouter le champ d'application OAuth de gestion des attributions
Assurez-vous que votre application demande les champs d'application suivants:
https://www.googleapis.com/auth/classroom.addons.teacherhttps://www.googleapis.com/auth/classroom.addons.studenthttps://www.googleapis.com/auth/classroom.coursework.students
Le champ d'application classroom.coursework.students n'était pas nécessaire auparavant. Il permet de créer ou de modifier des attributions CourseWork. Ajoutez ce champ d'application aux listes des champs d'application du SDK Google Workspace Marketplace de votre projet Cloud, de l'écran de consentement OAuth et de votre code de 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 iFrame
La procédure décrite dans ce tutoriel permet à un utilisateur de créer des devoirs et des pièces jointes Google Classroom à partir d'un produit autre que Google. En pratique, il s'agit probablement de votre site Web ou application existants. Dans cet exemple, vous devez créer une page Web fictive qui servira de site externe. Vous avez besoin d'un bouton ou d'un lien qui, lorsque vous cliquez dessus, ouvre un nouvel itinéraire qui exécute le flux CourseWork suggéré pour créer une attribution.
Vous devez également ajouter un bouton ou un lien permettant à l'utilisateur de se connecter si vous n'en avez pas déjà un. Vous aurez besoin des identifiants utilisateur pour effectuer les requêtes API suivantes. Ils devront donc mener à bien le handshake OAuth 2.0. Pour en savoir plus, consultez le tutoriel sur la connexion.
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 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 itinéraires associés à CourseWork.
Il s'agit de coursework_routes.py dans l'exemple fourni. Ajoutez les trois itinéraires suivants. 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")
Vérifier l'éligibilité d'un utilisateur à créer des modules complémentaires
Un utilisateur doit remplir plusieurs conditions préalables pour que vous puissiez créer des pièces jointes de modules complémentaires en son nom. Pour plus de commodité, Google fournit 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é utilisateur éligible.
Ajoutez le contrôle d'éligibilité à l'implémentation du routage de création CourseWork.
Testez ensuite le champ isCreateAttachmentEligible dans la réponse. Pour les utilisateurs éligibles, suivez la logique pour créer une attribution avec pièce jointe de module complémentaire. Sinon, créez un Link Material. Vous devrez connaître l'ID du cours dans
lequel l'utilisateur souhaite créer un devoir. Normalement, vous inviterez l'utilisateur
à spécifier le cours à utiliser. Pour plus de simplicité, nous utilisons dans cet exemple une valeur codée en dur.
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 pièce jointe de module complémentaire pour les utilisateurs éligibles
Si l'utilisateur est autorisé à créer des pièces jointes de modules complémentaires, procédez comme suit:
- Envoyez une requête API pour créer un devoir
courseWorkdans Google Classroom sans pièce jointe. - Extrayez le
iddu devoir que vous venez de créer. - Créez un CourseWork
AddOnAttachment. - Envoyez une demande de création de pièce jointe de module complémentaire pour le devoir que vous venez de créer dans Google Classroom.
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
Si l'utilisateur n'est pas éligible à la création de pièces jointes de modules complémentaires, 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
Vous pouvez accéder, modifier, rendre, récupérer ou renvoyer tout élément de flux Google Classroom associé à au moins une de ses pièces jointes de module complémentaire, indépendamment de l'utilisateur qui l'a créé. Les éléments de flux sont n'importe quel élément Announcement, CourseWork ou CourseWorkMaterial.
Pour illustrer cela, vous allez ajouter une route pour modifier un élément de flux donné. Cette méthode vous permet de vérifier que vous pouvez accéder aux éléments de flux que vous avez créés avec l'API et par un enseignant via l'interface utilisateur de Google Classroom, et que vous pouvez 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. Elle doit ouvrir une nouvelle route pour modifier une attribution CourseWork.
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 un parcours pour gérer les itinéraires associés à CourseWork. Cette valeur 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 plus de simplicité, les exemples fournis utilisent des identifiants de cours et d'attributions codés en dur. Pour obtenir ces identifiants, envoyez des requêtes avec les identifiants d'enseignant aux méthodes get et list des ressources courses et courseWork. Elles sont également renvoyées dans la réponse lors de la création d'attributions courseWork.
Tester la création du lien Material
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 Upgrade ou Plus. Vous pouvez activer/désactiver l'état de la licence d'un utilisateur dans la console d'administration de votre domaine test.Cliquez sur le bouton Créer un devoir CourseWork, puis ouvrez l'interface Google Classroom et vérifiez qu'un devoir avec une pièce jointe Link Material a été créé. La pièce jointe doit montrer le titre de la page Web liée et une URL.
Tester la création de pièces jointes de modules complémentaires
Revenez à la page d'index et connectez-vous en tant qu'utilisateur enseignant avec une licence Google Workspace for Education Teaching and Learning Upgrade 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 un module complémentaire en pièce jointe a été créé. La pièce jointe doit indiquer le nom de votre module complémentaire et le titre spécifié dans votre code.
Tester la modification des devoirs
Revenez à la page d'index et vérifiez que vous êtes connecté en tant qu'utilisateur enseignant avec une licence Teaching and Learning Upgrade 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.