Se usó la API de Cloud Translation para traducir esta página.

Explicaciones

Esta serie de explicaciones ilustran todas las partes móviles de un complemento de trabajo de Classroom. Cada paso de la explicación aborda conceptos específicos y los implementa en una sola aplicación web. El objetivo es ayudarte a configurar, establecer e iniciar 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. Administra las credenciales, el acceso a la API y el SDK de GWM en la consola de Google Cloud. Para obtener más información sobre el SDK de GWM, visita la página de la guía de ficha 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 en 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.
Abordar los requisitos clave de envío de complementos y las funciones obligatorias

En esta guía, se da por sentado 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 del proyecto antes de comenzar con las explicaciones. Esta página contiene detalles de configuración importantes que no se abordan por completo en las explicaciones.

Implementaciones de ejemplo

Hay ejemplos de referencias completas disponibles en JavaScript, Python y Java. Estas implementaciones son las fuentes del código de ejemplo que se encuentran en las páginas posteriores.

Dónde descargar la app

Puedes descargar los archivos completos con nuestros ejemplos a través de los vínculos que aparecen a continuación.

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 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 se deben 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 nuevas de OAuth:

Ve a la página Credenciales de Google Cloud. Asegúrate de haber seleccionado el proyecto correcto en la parte superior de la pantalla.
Haz clic en CREAR CREDENCIALES y elige ID de cliente de OAuth en el menú desplegable.
En la página siguiente, sigue estos pasos:
- 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 para una ruta de devolución de llamada para tu aplicación. Por ejemplo, https://my.domain.com/auth-callback o https://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 para un lenguaje específico

Consulta el archivo readme en cada archivo para obtener la lista de requisitos previos más actualizada.

Python

En nuestro ejemplo de Python, se usa el framework de Flask. Puedes descargar el código fuente completo desde el vínculo anterior.

Si es necesario, instala Python 3.7+ y asegúrate de que pip esté disponible.

python3 -m ensurepip --upgrade

También te recomendamos que configures y actives un entorno virtual nuevo de Python.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

Hay un requirements.txt en cada subdirectorio de 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

En nuestro ejemplo de Node.js, se usa el framework de Express. Puedes descargar el código fuente completo desde el vínculo anterior.

En este ejemplo, se requiere Node.js v16.13 o una versión posterior.

Instala los módulos de nodo necesarios con npm.

npm install

Java

En nuestro ejemplo de Java, se usa el framework de Spring Boot. Puedes descargar el código fuente completo desde el vínculo anterior.

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 compilaciones y administrar dependencias. En este ejemplo, se incluye el wrapper de Maven que garantiza una compilación exitosa sin necesidad de que instales Maven.

En el directorio donde descargaste o clonaste el proyecto, ejecuta los siguientes comandos para asegurarte de que cuentas con los requisitos previos para ejecutar el proyecto.

java --version
./mvnw --version

O en Windows:

java -version
mvnw.cmd --version

Comprende los archivos

En las siguientes secciones, se describe el diseño de los directorios de ejemplo.

Nombres de directorios

Cada archivo contiene varios directorios cuyos nombres comienzan con un número, como /01-basic-app/. Los números corresponden a los pasos específicos de la explicación. Cada directorio contiene una app web completamente funcional que implementa las características descritas en una explicación en particular. Por ejemplo, el directorio /01-basic-app/ contiene la implementación final para la explicación Cómo crear un complemento.

Contenido del directorio

El contenido del directorio difiere según el lenguaje de implementación:

Python

La raíz del directorio contiene los siguientes archivos:
- main.py: el punto de entrada de la aplicación de Python. Especifica la configuración del servidor que deseas usar en este archivo y, luego, ejecútala para iniciar el servidor.
- requirements.txt: Son los módulos de Python necesarios para ejecutar la app web. Se pueden instalar automáticamente mediante pip install -r requirements.txt.
- client_secret.json: Es el archivo de secreto del cliente descargado de Google Cloud. Ten en cuenta que esto no se incluye en el archivo de ejemplo; debes cambiar el nombre de tu archivo de credenciales descargado y copiarlo en cada raíz del directorio.
  
  Importante: Debes proporcionar el archivo de secretos del cliente de tu proyecto de Google Cloud antes de ejecutar los ejemplos.
config.py: opciones de configuración para el servidor 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áginas
El directorio /static/ con imágenes, CSS y archivos de JavaScript complementarios
routes.py: Son los métodos del controlador para las rutas de aplicaciones web.
__init__.py: Es el inicializador del módulo webapp. Este inicializador inicia el servidor Flask y carga las opciones de configuración establecidas en config.py.
Archivos adicionales requeridos para un paso específico de la explicación.

Node.js

Cada paso de la explicación 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 exprés 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 correctamente. Este directorio incluye lo siguiente: + java.com.addons.spring contiene los archivos Application.java y Controller.java. El archivo Application.java es responsable de ejecutar el servidor de aplicaciones, mientras que el archivo Controller.java controla la lógica del extremo. + resources contiene el directorio templates con archivos HTML y JavaScript. También contiene el archivo application.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 directorio templates. En este ejemplo, se incluye el archivo de almacén de claves en el directorio resources. Puedes almacenarlo donde prefieras, pero asegúrate de actualizar el archivo application.properties con la ruta de acceso correspondiente.
- pom.xml contiene la información necesaria para compilar el proyecto y definir las dependencias requeridas.
- .gitignore contiene nombres de archivo que no se deben subir a Git. Asegúrate de agregar la ruta de acceso a tu almacén de claves en este .gitignore. En el ejemplo que se proporciona, es secrets/*.p12 (el propósito del almacén de claves se analiza en la siguiente sección). Para la explicación 2 y más allá, también debes incluir la ruta de acceso a tu archivo client_secret.json a fin de asegurarte de no incluir tus secretos en un repositorio remoto. Para la explicación 3 y posteriores, debes agregar la ruta de acceso al archivo de base de datos H2 y a la fábrica de almacén de datos de archivos. Puedes encontrar más información sobre la configuración de estos almacenes de datos en la tercera explicación sobre cómo controlar las visitas repetidas.
- mvnw y mvnw.cmd son los wrappers ejecutables de Maven para Unix y Windows, respectivamente. Por ejemplo, ejecutar ./mvnw --version en Unix da como resultado la versión de Apache Maven, entre otra información.
- El directorio .mvn contiene la configuración para el wrapper de Maven.

Ejecuta el servidor de muestra

Debes iniciar tu servidor para probarlo. Sigue las instrucciones que aparecen a continuación para ejecutar el servidor de ejemplo en el lenguaje que prefieras:

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 con el 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 uno de los siguientes elementos:

localhost no es seguro. Ten en cuenta que esto es adecuado para realizar pruebas directas solo 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 argumento ssl_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 para un servidor listo para la producción o una implementación en la nube. Recomendamos configurar una variable de entorno PORT para usarla 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 la 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 la cadena de claves del SO para que el navegador las acepte.

Asegúrate de que *.pem esté en tu 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 para 02-sign-in).

npm run step01

npm run step02

Esto iniciará el servidor web en https://localhost:3000.

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 desarrollo local. Una vez que instalas mkcert, los siguientes comandos generan un certificado almacenado de forma local para ejecutarse a través de HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Este ejemplo 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 correspondiente. El nombre de dominio es el dominio en el que ejecutas el proyecto (por ejemplo, localhost).

Asegúrate de que *.p12 esté en tu 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. Por ejemplo, en IntelliJ, 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.