Esta es la séptima explicación de la serie de explicaciones de complementos de Classroom.
En esta explicación, agregarás comportamiento a una aplicación web para crear adjuntos de complementos desde fuera de Google Classroom. Usa este comportamiento para permitir que los usuarios creen archivos adjuntos de complementos desde tu producto o sitio web existentes. Esta también es una gran adición a una integración de CourseWork, ya que diriges el tráfico existente a la experiencia del usuario mejorada que ofrece tu complemento sin cambiar su flujo. El proceso sugerido se presenta en nuestra página de guía Cómo crear archivos adjuntos fuera de Classroom.
También debes agregar un comportamiento a tu complemento para modificar una tarea con archivos adjuntos de complemento de manera programática. Puedes modificar cualquier tarea que tenga uno de tus archivos adjuntos de complementos, sin importar quién la haya creado. Esto es particularmente útil para entregar las tareas después de que un estudiante completa una actividad, lo que le indica al profesor que las tareas asignadas están completas y que el trabajo del estudiante está listo para su revisión.
Extiende la versión final de tu complemento que admite content-type o archivos adjuntos de tipo de actividad. En esta guía, se usa el archivo adjunto de tipo de contenido.
Agrega el permiso de OAuth para la administración de tareas
Asegúrate de que tu aplicación solicite los siguientes alcances:
https://www.googleapis.com/auth/classroom.addons.teacherhttps://www.googleapis.com/auth/classroom.addons.studenthttps://www.googleapis.com/auth/classroom.coursework.students
El permiso classroom.coursework.students no era necesario anteriormente y se usa para crear o modificar asignaciones CourseWork. Agrega este permiso a las listas de permisos en el SDK de Google Workspace Marketplace, la pantalla de consentimiento de OAuth y el código del servidor de tu proyecto de 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",
]
Cómo crear una tarea en Classroom
Cómo agregar botones a una página web sin iframe
El flujo que se describe en esta explicación permite que un usuario cree tareas y archivos adjuntos de Google Classroom desde un producto que no sea de Google. En la práctica, es probable que se trate de tu sitio web o aplicación existentes. Para este ejemplo, debes crear una página web ficticia para que actúe como sitio externo. Necesitas un botón o vínculo que, cuando se haga clic en él, abre una ruta nueva que realice el flujo de CourseWork sugerido para crear una tarea nueva.
También deberás agregar un botón o vínculo para permitir que el usuario acceda, si aún no tienes uno. Necesitarás credenciales de usuario para realizar las solicitudes a la API posteriores, por lo que deben completar el protocolo de enlace de OAuth 2.0. Consulta la explicación de acceso para obtener orientación específica.
Python
En el ejemplo de Python proporcionado, se modifica la ruta /index que se introdujo
en el primer paso de la explicación.
<!-- /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>
Agrega una plantilla HTML para representar un destino en tu sitio web. Esta página representará el contenido que se adjuntará a tu asignación de 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>
Crea un nuevo archivo de módulo de Python para controlar las rutas relacionadas con CourseWork.
En el ejemplo que proporcionamos, es coursework_routes.py. Agrega las siguientes tres rutas; ten en cuenta que completarás algunos de los contenidos más adelante.
# /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")
Cómo verificar la elegibilidad de un usuario para crear complementos
Existen varios requisitos previos que un usuario debe cumplir para que puedas crear archivos adjuntos de complementos en su nombre. Para mayor comodidad, Google proporciona el método courses.checkAddOnCreationEligibility a fin de determinar si un usuario cumple con estos requisitos previos. Un usuario que cumple con los requisitos previos se denomina usuario apto.
Agrega la verificación de elegibilidad a la implementación de la ruta de creación de CourseWork.
Luego, prueba el campo isCreateAttachmentEligible en la respuesta. En el caso de los usuarios aptos, sigue la lógica para crear una tarea con un archivo adjunto de complemento. De lo contrario, crea un Link Material. Necesitarás saber el ID del curso
en el que el usuario quiere crear una tarea. Por lo general, le pedirás al usuario
que especifique qué curso usar. Para simplificar, en este ejemplo usamos un valor hard-coded.
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.
Cómo crear una tarea con un archivo adjunto de complemento para los usuarios aptos
Si el usuario es apto para crear archivos adjuntos de complementos, haga lo siguiente:
- Envía una solicitud a la API para crear una tarea
courseWorken Google Classroom sin archivos adjuntos. - Extrae el
idde la asignación recién creada. - Crea un nuevo CourseWork
AddOnAttachment. - Envía una solicitud para crear un archivo adjunto de complemento en la tarea recién creada en 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()
)
Cómo crear un material de vínculo
Si el usuario no es apto para crear archivos adjuntos de complementos, crea un Material de vínculo de la siguiente manera:
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()
)
Cómo modificar una tarea ya creada
Puedes acceder, modificar, entregar, reclamar o mostrar cualquier elemento de transmisión de Google Classroom que tenga al menos uno de tus archivos adjuntos de complemento, sin importar quién creó el elemento de transmisión. Los elementos de flujo pueden ser cualquier asignación Announcement, CourseWork o CourseWorkMaterial.
Para demostrarlo, agregarás una ruta para modificar un elemento de flujo determinado. Usa este método para verificar que puedes acceder a los elementos de las novedades que creaste con la API y que un profesor creó en la IU de Google Classroom, y los modifica.
Agrega un vínculo o botón más a la página web que editaste por primera vez en esta explicación. Se debería abrir una ruta nueva para modificar una asignación CourseWork.
Python
En el ejemplo de Python proporcionado, se modifica la ruta /index que se modificó antes en esta explicación.
<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>
Crea una ruta nueva para administrar las rutas relacionadas con CourseWork. Se encuentra en el archivo coursework_routes.py del ejemplo proporcionado.
# 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()
)
Prueba el complemento
Para simplificar el proceso, en los ejemplos proporcionados se usan identificadores de asignación y cursos codificados. Para obtener estos identificadores, realiza solicitudes con credenciales de profesor a los métodos get y list de los recursos courses y courseWork. También se muestran en la respuesta cuando se crean asignaciones de courseWork.
Cómo probar la creación de materiales para vínculos
Ejecuta el servidor y, luego, navega a la página de índice y accede como usuario profesor sin una licencia Teaching & Learning o Plus de Google Workspace for Education. Puedes activar o desactivar el estado de la licencia de un usuario desde la Consola del administrador del dominio de prueba.Haz clic en el botón Create a CourseWork Assignment y, luego, abre la IU de Google Classroom y verifica que se haya creado una tarea con un archivo adjunto de Material de vínculo. El archivo adjunto debe mostrar el título de la página web vinculada y una URL.
Probar la creación de archivos adjuntos de complementos
Regresa a la página de índice y accede como usuario profesor con una licencia Teaching & Learning o Plus de Google Workspace for Education. Haz clic en el botón Create a CourseWork Assignment y, luego, abre la IU de Google Classroom y verifica que se haya creado una tarea con un archivo adjunto de complemento. El archivo adjunto debería mostrar el nombre de la aplicación de tu complemento y el título especificado en tu código.
Modificación de una tarea de prueba
Regresa a la página de índice y asegúrate de haber accedido como usuario profesor con una licencia de Teaching & Learning o Plus. Haz clic en el botón Modify a CourseWorkAssignment, luego, regresa a la IU de Google Classroom y verifica que se haya modificado el título de la tarea.
¡Felicitaciones! Completaste la serie de explicaciones.