Este es el séptimo instructivo de la serie de instructivos sobre los complementos de Classroom.
En este recorrido, agregarás comportamiento a una aplicación web para crear archivos 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 excelente incorporació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 Crea archivos adjuntos fuera de Classroom.
También puedes agregar comportamiento a tu complemento para modificar una tarea con archivos adjuntos del complemento de forma programática. Puedes modificar cualquier tarea que tenga uno de tus archivos adjuntos de complemento, independientemente de quién haya creado la tarea. Esto es especialmente útil para entregar tareas después de que un estudiante completó 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.
Extiendes la versión final de tu complemento que admite adjuntos de tipo de contenido o tipo de actividad. En esta guía, se usa el adjunto content-type.
Agrega el permiso de OAuth de administración de tareas
Asegúrate de que tu aplicación solicite los siguientes permisos:
https://www.googleapis.com/auth/classroom.addons.teacherhttps://www.googleapis.com/auth/classroom.addons.studenthttps://www.googleapis.com/auth/classroom.coursework.students
El alcance de classroom.coursework.students no se necesitó anteriormente y se usa para crear o modificar asignaciones de CourseWork. Agrega este alcance a las listas de alcances 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
Agrega botones a una página web que no esté dentro de un 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 es 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 simulada que actúe como un sitio externo. Necesitas un botón o un vínculo que, cuando se haga clic en él, abra una nueva ruta que realice el flujo de CourseWork sugerido para crear una nueva tarea.
También deberás agregar un botón o un vínculo para permitir que el usuario acceda si aún no tienes uno. Necesitarás credenciales de usuario para realizar las solicitudes posteriores a la API, por lo que deberán completar el protocolo de enlace de OAuth 2.0. Consulta la guía de inicio de sesión para obtener orientación específica.
Python
El ejemplo de Python proporcionado modifica la ruta /index que se introdujo en el primer paso de la guía.
<!-- /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 tarea 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 archivo de módulo de Python nuevo para controlar las rutas relacionadas con CourseWork.
En nuestro ejemplo, es coursework_routes.py. Agrega las siguientes tres rutas. Ten en cuenta que completarás parte del contenido 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")
Verifica si un usuario cumple con los requisitos para crear archivos adjuntos
Existen varios requisitos previos que debe cumplir un usuario antes de que puedas crear archivos adjuntos de complementos en su nombre. Para mayor comodidad, Google proporciona el método userProfiles.checkUserCapability para 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 allowed 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 LinkMaterial. Deberás conocer 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, usamos un valor codificado de forma rígida en este ejemplo.
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.
Crea una tarea con un archivo adjunto de complemento para los usuarios aptos
Si el usuario cumple con los requisitos para crear archivos adjuntos de complementos, haz lo siguiente:
- Envía una solicitud a la API para crear una tarea
courseWorken Google Classroom sin archivos adjuntos. - Extrae el
idde la tarea recién creada. - Construye un nuevo CourseWork
AddOnAttachment. - Envía una solicitud para crear un archivo adjunto del complemento en la tarea recién creada en 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()
)
Crea un material de vínculo
Si el usuario no cumple con los requisitos para crear adjuntos de complementos, crea un objeto LinkMaterial. Para ello, haz lo siguiente:
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()
)
Cómo modificar una tarea ya creada
Puedes acceder, modificar, entregar, reclamar o devolver cualquier elemento del flujo de Google Classroom que tenga al menos uno de tus archivos adjuntos del complemento, independientemente de quién haya creado el elemento del flujo. Los elementos de la Novedades son cualquier Announcement, tarea CourseWork o CourseWorkMaterial.
Para demostrarlo, agregarás una ruta para modificar un elemento de transmisión determinado. Usa este método para verificar que puedes acceder a los elementos de la transmisión que creaste y modificarlos con la API y los que creó un profesor a través de la IU de Google Classroom.
Agrega un vínculo o botón más a la página web que editaste por primera vez en este recorrido. Se debería abrir una ruta nueva para modificar una tarea.CourseWork
Python
El ejemplo de Python proporcionado modifica la ruta /index que se modificó anteriormente en este instructivo.
<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>
Crea una ruta nueva para controlar las rutas relacionadas con CourseWork. Esto se encuentra en el archivo coursework_routes.py de nuestro 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 las cosas, los ejemplos proporcionados usan identificadores de cursos y tareas codificados. Puedes obtener estos identificadores realizando solicitudes con credenciales de profesor a los métodos get y list de los recursos courses y courseWork. También se devuelven en la respuesta cuando se crean tareas de courseWork.
Creación de material de vínculo de prueba
Ejecuta tu servidor, navega a la página de índice y accede como usuario profesor sin una licencia de Google Workspace for Education Teaching & Learning o Plus. Puedes activar o desactivar el estado de la licencia de un usuario desde la Consola del administrador de tu dominio de prueba.Haz clic en el botón Crear una tarea de CourseWork, 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 adjunto debe mostrar el título de la página web vinculada y una URL.
Prueba la creación de archivos adjuntos de complementos
Vuelve a la página de índice y accede como usuario profesor con una licencia de Google Workspace for Education Teaching & Learning o Plus. Haz clic en el botón Create a CourseWork Assignment, luego abre la IU de Google Classroom y verifica que se haya creado una tarea con un archivo adjunto del complemento. El adjunto debe mostrar el nombre de tu aplicación de complemento y el título especificado en tu código.
Modificación de la asignación de la 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 Modificar una tarea de CourseWork, luego vuelve a la IU de Google Classroom y verifica que se haya modificado el título de la tarea.
¡Felicitaciones! Completaste la serie de explicaciones.