En esta serie de explicaciones, se ilustran todas las partes móviles de un complemento de Classroom en funcionamiento. En cada paso de la explicación, se abordan conceptos específicos para implementarlos en una sola aplicación web. El objetivo es ayudarte a configurar y lanzar un complemento funcional.
Tu complemento debe interactuar con un proyecto de Google Cloud. Si no estás familiarizado con Google Cloud, te recomendamos que leas las guías de introducción. Puedes administrar las credenciales, el acceso a la API y el SDK de Google Workspace Marketplace en la consola de Google Cloud. Para obtener más información sobre el SDK de Marketplace, visita la página de la guía de fichas de Google Workspace Marketplace.
En esta guía, se abarcan los siguientes temas:
- Usa Google Cloud para crear una página que se mostrará en un iframe de Classroom.
- Agregar el inicio de sesión único (SSO) de Google y permitir que los usuarios accedan
- Realiza llamadas a la API para adjuntar tu complemento a una tarea.
- Aborda los requisitos clave de envío de complementos y las funciones requeridas.
En esta guía, se supone que estás familiarizado con la programación y los conceptos fundamentales del desarrollo web. Te recomendamos que leas la guía de configuración de proyectos antes de comenzar con las explicaciones. En esta página, se incluyen detalles de configuración importantes que no se tratan por completo en las explicaciones.
Implementaciones de ejemplo
Hay un ejemplo de referencia completo disponible en Python. Las implementaciones parciales también están disponibles en Java y Node.js. Estas implementaciones son las fuentes del código de ejemplo que se encuentra en las páginas posteriores.
Dónde descargar
Los ejemplos de Python y Java están disponibles en repositorios de GitHub:
La muestra de Node.js se puede descargar como un archivo ZIP:
Requisitos previos
Revisa las siguientes secciones para preparar un nuevo proyecto de complementos.
Certificado HTTPS
Si bien puedes alojar tu app en cualquier entorno de desarrollo, el complemento de Classroom solo está disponible a través de https://
. Por lo tanto, necesitas un servidor con encriptación SSL para implementar tu app o probarla dentro del iframe del complemento.
Es posible usar localhost
con un certificado SSL. Considera usar mkcert si necesitas crear un certificado para desarrollo local.
Proyecto de Google Cloud
Debes configurar un proyecto de Google Cloud para usarlo con estos ejemplos. Consulta la guía de creación de proyectos de Google Cloud a fin de obtener una descripción general de los pasos necesarios para comenzar. En la sección Configura un proyecto de Google Cloud de la primera explicación, también se explican las acciones de configuración específicas que debes realizar.
Cuando termines, descarga tu ID de cliente de OAuth 2.0 como un archivo JSON. Debes agregar este archivo de credenciales al directorio de ejemplo descomprimido. Consulta Cómo interpretar los archivos para conocer las ubicaciones específicas.
Credenciales de OAuth
Sigue estos pasos para crear credenciales de OAuth nuevas:
- Navega a la página Credenciales de Google Cloud. Asegúrate de tener seleccionado el proyecto correcto en la parte superior de la pantalla.
- Haz clic en CREAR CREDENCIALES y elige el ID de cliente de OAuth del menú desplegable.
- En la siguiente página, haz lo siguiente:
- Configura el Tipo de aplicación como Aplicación web.
- En URI de redireccionamiento autorizados, haz clic en AGREGAR URI. Agrega la ruta de acceso completa a fin de obtener una ruta de devolución de llamada para tu aplicación. Por ejemplo,
https://my.domain.com/auth-callback
ohttps://localhost:5000/callback
. Crearás y controlarás esta ruta más adelante en esta explicación. Puedes editar o agregar más rutas de este tipo en cualquier momento. - Haz clic en CREAR.
- Luego, recibirás un diálogo con tus credenciales recién creadas. Elige la opción DESCARGAR JSON. Copia el archivo JSON descargado en el directorio del servidor.
Requisitos previos específicos para cada idioma
Consulta el archivo README en cada repositorio para obtener la lista más actualizada de los requisitos previos.
Python
Nuestro ejemplo de Python utiliza el framework de Flask. Puedes descargar el código fuente completo desde los vínculos proporcionados.
Si es necesario, instala Python 3.7+ y asegúrate de que pip
esté disponible.
python3 -m ensurepip --upgrade
También te recomendamos configurar y activar un nuevo entorno virtual de Python.
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
Hay un requirements.txt
en cada subdirectorio de la explicación en los ejemplos descargados. Puedes instalar rápidamente las bibliotecas requeridas con pip
. Usa los siguientes comandos a fin de instalar las bibliotecas necesarias para la primera explicación.
cd flask/01-basic-app
pip install -r requirements.txt
Node.js
Nuestro ejemplo de Node.js usa el framework Express. Puedes descargar el código fuente completo desde los vínculos proporcionados.
Este ejemplo requiere Node.js 16.13 o versiones posteriores.
Instala los módulos de nodo obligatorios con npm
.
npm install
Java
Nuestro ejemplo de Java usa el framework de Spring Boot. Puedes descargar el código fuente completo desde los vínculos proporcionados.
Instala Java 11+ si aún no lo tienes instalado en tu máquina.
Las aplicaciones de Spring Boot pueden usar Gradle o Maven para controlar las compilaciones y administrar las dependencias. En este ejemplo, se incluye el wrapper de Maven que garantiza una compilación exitosa sin que debas instalar Maven.
En el directorio en el que tienes el proyecto descargado o clonado, ejecuta los siguientes comandos para asegurarte de que tienes los requisitos previos para ejecutar el proyecto.
java --version
./mvnw --version
O en Windows:
java -version
mvnw.cmd --version
Cómo interpretar los archivos
En las siguientes secciones, se describe el diseño de los directorios de ejemplo.
Nombres de directorios
Cada repositorio contiene varios directorios cuyos nombres comienzan con un número, como /01-basic-app/
. Los números corresponden a pasos específicos de la explicación.
Cada directorio contiene una app web completamente funcional que implementa las características que se describen en una explicación en particular. Por ejemplo, el directorio /01-basic-app/
contiene la implementación final de la explicación Cómo crear un complemento.
Contenido del directorio
Los contenidos del directorio difieren según el lenguaje de implementación:
Python
La raíz del directorio contiene los siguientes archivos:
main.py
: Es el punto de entrada de la aplicación de Python. Especifica la configuración del servidor que quieres usar en este archivo y ejecútala para iniciar el servidor.requirements.txt
: Son los módulos de Python necesarios para ejecutar la app web. Se pueden instalar de forma automática mediantepip install -r requirements.txt
.client_secret.json
: Es el archivo de secretos del cliente que se descarga de Google Cloud. Ten en cuenta que esto no se incluye en el archivo de ejemplo; debes cambiar el nombre del archivo de credenciales descargado y copiarlo en la raíz de cada directorio.
config.py
: Son las opciones de configuración para el servidor de Flask.El directorio
webapp
incluye el contenido de la aplicación web. incluye lo siguiente:El directorio
/templates/
con plantillas de Jinja para varias páginasEl directorio
/static/
con imágenes, CSS y archivos JavaScript auxiliaresroutes.py
: Son los métodos de controlador de las rutas de la aplicación web.__init__.py
: El inicializador para el módulowebapp
. Este inicializador inicia el servidor Flask y carga las opciones de configuración establecidas enconfig.py
.Archivos adicionales según sea necesario para un paso de explicación en particular.
Node.js
Cada paso del recorrido se puede encontrar en su propia subcarpeta <step>
. Cada paso contiene lo siguiente:
- Los archivos estáticos, como JavaScript, CSS y las imágenes, se encuentran en la carpeta
./<step>/public
. - Los routers Express se encuentran en las carpetas
./<step>/routes
. - Las plantillas HTML se encuentran en las carpetas
./<step>/views
. - La aplicación del servidor es
./<step>/app.js
.
Java
El directorio del proyecto incluye lo siguiente:
- El directorio
src.main
contiene el código fuente y la configuración para ejecutar la aplicación de forma correcta. Este directorio incluye lo siguiente: + el directoriojava.com.addons.spring
contiene los archivosApplication.java
yController.java
. El archivoApplication.java
es responsable de ejecutar el servidor de aplicaciones, mientras que el archivoController.java
controla la lógica del extremo. +resources
contiene el directoriotemplates
con archivos HTML y JavaScript. También contiene el archivoapplication.properties
que especifica el puerto para ejecutar el servidor, la ruta de acceso al archivo del almacén de claves y la ruta de acceso al directoriotemplates
. En este ejemplo, se incluye el archivo de almacén de claves en el directorioresources
. Puedes almacenarlo donde lo desees, pero asegúrate de actualizar el archivoapplication.properties
con la ruta de acceso según corresponda.pom.xml
contiene la información necesaria para compilar el proyecto y definir las dependencias requeridas..gitignore
contiene nombres de archivo que no deben subirse a Git. Asegúrate de agregar la ruta de acceso al almacén de claves en este.gitignore
. En el ejemplo proporcionado, essecrets/*.p12
(el propósito del almacén de claves se analiza en la siguiente sección). Para la Explicación 2 y los posteriores, también debes incluir la ruta de acceso a tu archivoclient_secret.json
para asegurarte de no incluir tus secretos en un repositorio remoto. Para la Explicación 3 y las versiones posteriores, debes agregar la ruta de acceso al archivo de base de datos de H2 y a la fábrica de almacenamiento de archivos. Puedes obtener más información sobre la configuración de estos almacenes de datos en la tercera explicación sobre cómo manejar las visitas repetidas.mvnw
ymvnw.cmd
son los ejecutables del wrapper de Maven para Unix y Windows, respectivamente. Por ejemplo, si ejecutas./mvnw --version
en Unix, se genera la versión de Apache Maven, entre otra información.- El directorio
.mvn
contiene la configuración del wrapper de Maven.
Ejecuta el servidor de muestra
Debes iniciar tu servidor para probarlo. Sigue estas instrucciones para ejecutar el servidor de ejemplo en el lenguaje que elijas:
Python
Credenciales de OAuth
Crea y descarga tus credenciales de OAuth como se describió anteriormente. Coloca el archivo JSON en el directorio raíz junto al archivo de inicio del servidor de tu aplicación.
Configura el servidor
Tienes varias opciones para ejecutar el servidor web. Al final del archivo de Python, agrega una de las siguientes opciones:
localhost
no seguro. Ten en cuenta que esto solo es adecuado para realizar pruebas directamente en una ventana del navegador. Los dominios no seguros no se pueden cargar en el iframe del complemento de Classroom.if __name__ == "__main__": # Disable OAuthlib's HTTPs verification. os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1" # Run the web app at http://localhost:5000. app.run(debug=True)
Protege
localhost
. Debes especificar una tupla de archivos de claves SSL para el argumentossl_context
.if __name__ == "__main__": # Run the web app at https://localhost:5000. app.run(host="localhost", ssl_context=("localhost.pem", "localhost-key.pem"), debug=True)
Gunicorn. Esto es adecuado en un servidor listo para la producción o en una implementación en la nube. Recomendamos configurar una variable de entorno
PORT
para usar con esta opción de inicio.if __name__ == "__main__": # Run the web app at https://<your domain>:<server_port>. # Defaults to https://<your domain>:8080. server_port = os.environ.get("PORT", "8080") app.run(debug=True, port=server_port, host="0.0.0.0")
Inicia el servidor
Ejecuta tu aplicación de Python para iniciar el servidor como se configuró en el paso anterior.
python main.py
Haz clic en la URL que aparece para ver la aplicación web en un navegador y confirmar que se esté ejecutando correctamente.
Node.js
Configura el servidor
Para ejecutar el servidor con HTTPS, debes crear un autocertificado que se use para ejecutar la aplicación con HTTPS. Estas credenciales deben guardarse como sslcert/cert.pem
y sslcert/key.pem
en la carpeta raíz del repositorio. Es posible que debas agregar estas claves a tu cadena de claves del SO para que el navegador las acepte.
Asegúrate de que *.pem
esté en el archivo .gitignore
, ya que no quieres confirmar el archivo en Git.
Inicia el servidor
Puedes ejecutar la aplicación con el siguiente comando y sustituir step01
por el paso correcto que deseas ejecutar como servidor (por ejemplo, step01
para 01-basic-app y step02
por 02-sign-in).
npm run step01
o
npm run step02
Esto inicia el servidor web en https://localhost:5000
.
Puedes finalizar el servidor con Control + C
en tu terminal.
Java
Configura el servidor
Para ejecutar el servidor con HTTPS, debes crear un autocertificado que se use para ejecutar la aplicación con HTTPS.
Considera usar mkcert para el desarrollo local. Una vez que instalas mkcert
, los siguientes comandos generan un certificado almacenado de forma local para ejecutar a través de HTTPS.
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
En este ejemplo, se incluye el archivo de almacén de claves en el directorio de recursos. Puedes almacenarlo donde prefieras, pero asegúrate de actualizar el archivo application.properties
con la ruta de acceso según corresponda. El nombre de dominio es aquel en el que ejecutas el proyecto (por ejemplo, localhost
).
Asegúrate de que *.p12
esté en el archivo .gitignore
, ya que no quieres confirmar el archivo en Git.
Inicia el servidor
Ejecuta el método main
en el archivo Application.java
para iniciar el servidor. En IntelliJ, por ejemplo, puedes hacer clic con el botón derecho en Application.java
> Run 'Application'
en el directorio src/main/java/com/addons/spring
o abrir el archivo Application.java
para hacer clic en la flecha verde a la izquierda de la firma del método main(String[] args)
. Como alternativa, puedes ejecutar el proyecto en una ventana de terminal:
./mvnw spring-boot:run
En Windows:
mvnw.cmd spring-boot:run
Esto inicia el servidor en https://localhost:5000
o en el puerto que especificaste en application.properties
.