Il s'agit du septième tutoriel de la série 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 existant. Il s'agit également d'un excellent complément à une intégration CourseWork, car vous redirigez 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 ajoutez également un comportement à votre module complémentaire pour modifier un devoir avec des pièces jointes de module complémentaire de manière programmatique. Vous pouvez modifier n'importe quel devoir auquel est associé l'un de vos modules complémentaires, quel que soit l'auteur du devoir. Cette fonctionnalité est particulièrement utile pour rendre des devoirs une fois qu'un élève a terminé une activité. Elle permet de signaler à 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 étendez la version finale de votre module complémentaire compatible avec les pièces jointes de type contenu ou pièces jointes de type activité. La pièce jointe de type "content-type" est utilisée dans ce guide.
Ajouter le champ d'application OAuth de gestion des devoirs
Assurez-vous que votre application demande les autorisations suivantes :
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 est utilisé pour créer ou modifier des attributions CourseWork. Ajoutez ce champ d'application aux listes de champs d'application dans le SDK Google Workspace Marketplace, l'écran d'autorisation OAuth et le code de votre serveur dans votre projet Cloud.
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 existants. Pour 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, lorsqu'il est cliqué, ouvre une nouvelle route qui exécute le flux CourseWork suggéré 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 d'API suivantes. Il doit donc effectuer l'établissement de liaison OAuth 2.0. Pour obtenir des instructions spécifiques, consultez la procédure de connexion.
Python
L'exemple Python fourni modifie la route /index qui a été introduite dans 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ésente 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 aux devoirs.
Dans l'exemple fourni, il s'agit de coursework_routes.py. Ajoutez les trois routes suivantes. Notez que vous remplirez certains contenus 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 pièces jointes
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 userProfiles.checkUserCapability pour déterminer si un utilisateur remplit ces conditions préalables. Un utilisateur qui remplit les conditions préalables est appelé utilisateur éligible.
Ajoutez la vérification de l'éligibilité à l'implémentation du chemin de création CourseWork.
Testez ensuite le champ allowed dans la réponse. Pour les utilisateurs éligibles, suivez la logique pour créer un devoir avec un complément en pièce jointe. Sinon, créez un Link
Material. Vous devez connaître l'ID du cours dans lequel l'utilisateur souhaite créer un devoir. En règle générale, vous invitez l'utilisateur à spécifier le cours à utiliser. Par souci de simplicité, 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 é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èces jointes. - Extrayez l'
iddu devoir que vous venez de créer. - Construit un CourseWork
AddOnAttachment. - Envoyez une requête pour créer une pièce jointe de module complémentaire dans le devoir nouvellement créé 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()
)
Créer un support de cours avec un lien
Si l'utilisateur n'est pas éligible à la création de pièces jointes de modules complémentaires, créez plutôt un élément de cours "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 du flux Google Classroom qui comporte au moins une pièce jointe de votre module complémentaire, le modifier, le rendre, le récupérer ou le renvoyer, quel que soit l'utilisateur qui l'a créé. Les éléments du flux sont des Announcement, des CourseWork ou des CourseWorkMaterial.
Pour ce faire, vous allez ajouter un itinéraire permettant de modifier un élément de flux donné. Utilisez cette méthode pour vérifier que vous pouvez accéder aux éléments du flux que vous avez créés et les modifier à l'aide de l'API et que vous avez créés à l'aide de l'interface utilisateur Google Classroom.
Ajoutez un lien ou un bouton à la page Web que vous avez modifiée en premier dans ce tutoriel. Une nouvelle route doit s'ouvrir pour modifier une affectation 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 itinéraire pour gérer les itinéraires liés aux devoirs. C'est 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 choses, les exemples fournis utilisent des identifiants de cours et de devoirs codés en dur. Vous pouvez obtenir ces identifiants en envoyant des requêtes avec des 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'courseWork devoirs.
Création de supports de cours avec des liens de test
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 dans la console d'administration de votre domaine de test.Cliquez sur le bouton Créer un devoir, puis ouvrez l'interface utilisateur Google Classroom et vérifiez qu'un devoir avec une pièce jointe de type "Lien vers un document" 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 modules complémentaires
Revenez à la page d'index et connectez-vous en tant qu'enseignant avec une licence Google Workspace for Education Teaching and Learning ou Plus. Cliquez sur le bouton Créer un devoir, puis ouvrez l'interface utilisateur Google Classroom et vérifiez qu'un devoir avec un complément a été créé. La pièce jointe doit indiquer le nom de votre application de module complémentaire et le titre spécifié dans votre code.
Modification de l'attribution des tests
Revenez à la page d'index et assurez-vous d'être connecté en tant qu'enseignant disposant d'une licence Teaching and Learning ou Plus. Cliquez sur le bouton Modifier un devoir, puis revenez à l'interface utilisateur Google Classroom et vérifiez que le titre du devoir a été modifié.
Félicitations ! Vous avez terminé la série de tutoriels.