Descripción general
La API de Gmail proporciona notificaciones push del servidor que te permiten estar atento a los cambios en los buzones de Gmail. Puedes usar esta función para mejorar el rendimiento de tu aplicación. Te permite eliminar los costos adicionales de red y procesamiento que implica sondear los recursos para determinar si cambiaron. Cada vez que cambia un buzón, la API de Gmail notifica a tu aplicación de servidor de backend.
Configuración inicial de Cloud Pub/Sub
La API de Gmail usa la API de Cloud Pub/Sub para entregar notificaciones push. Esto permite la notificación a través de diversos métodos, como webhooks y sondeos en un solo extremo de suscripción.
Requisitos previos
Para completar el resto de esta configuración, asegúrate de cumplir con los requisitos previos de Cloud Pub/Sub y, luego, configura un cliente de Cloud Pub/Sub.
Crea un tema
Con tu cliente de Cloud Pub/Sub, crea el tema al que la API de Gmail debería enviar notificaciones. El nombre del tema puede ser cualquiera que elijas en tu proyecto (es decir, que coincida con projects/myproject/topics/*, donde myproject es el ID del proyecto que aparece en tu proyecto en Google Developers Console).
Crea una suscripción
Sigue la Guía de suscriptores de Cloud Pub/Sub para configurar una suscripción al tema que creaste. Configura el tipo de suscripción para que sea un envío de webhook (es decir, una devolución de llamada HTTP POST) o una extracción (es decir, iniciada por tu app). Así es como tu aplicación recibirá notificaciones de actualizaciones.
Cómo otorgar derechos de publicación en tu tema
Cloud Pub/Sub requiere que otorgues privilegios a Gmail para publicar notificaciones en tu tema.
Para ello, debes otorgar privilegios de publish a gmail-api-push@system.gserviceaccount.com. Puedes hacerlo con la interfaz de permisos de la consola para desarrolladores de Cloud Pub/Sub siguiendo las instrucciones de control de acceso a nivel del recurso.
Cómo recibir actualizaciones del buzón de Gmail
Una vez que finalice la configuración inicial de Cloud Pub/Sub, configura las cuentas de Gmail para enviar notificaciones sobre las actualizaciones del buzón.
Solicitud de visualización
Para configurar las cuentas de Gmail para que envíen notificaciones a tu tema de Cloud Pub/Sub, simplemente usa tu cliente de la API de Gmail para llamar a watch en el buzón de correo del usuario de Gmail de manera similar a cualquier otra llamada a la API de Gmail.
Para ello, proporciona el nombre del tema que creaste anteriormente y cualquier otra opción en tu solicitud de watch, como labels para filtrar. Por ejemplo, para recibir una notificación cada vez que se realice un cambio en la Bandeja de entrada, haz lo siguiente:
Protocolo
POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json
{
topicName: "projects/myproject/topics/mytopic",
labelIds: ["INBOX"],
labelFilterBehavior: "INCLUDE",
}
Python
request = {
'labelIds': ['INBOX'],
'topicName': 'projects/myproject/topics/mytopic',
'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()
Ver respuesta
Si la solicitud watch se realiza correctamente, recibirás una respuesta como la siguiente:
{
historyId: 1234567890
expiration: 1431990098200
}
con el buzón de correo actual historyId para el usuario. Se le notificará a tu cliente todos los cambios que se realicen después de esa fecha.historyId Si necesitas procesar cambios antes de este historyId, consulta la guía de sincronización.
Además, una llamada watch exitosa debería provocar que se envíe de inmediato una notificación a tu tema de Cloud Pub/Sub.
Si recibes un error de la llamada a watch, los detalles deben explicar la fuente del problema, que suele estar relacionada con la configuración del tema y la suscripción de Cloud Pub/Sub. Consulta la documentación de Cloud Pub/Sub para confirmar que la configuración sea correcta y obtener ayuda para depurar problemas relacionados con temas y suscripciones.
Cómo renovar la observación del buzón
Debes volver a llamar a watch al menos cada 7 días; de lo contrario, dejarás de recibir actualizaciones sobre el usuario. Te recomendamos que llames a watch una vez al día. La respuesta watch también tiene un campo de vencimiento con la marca de tiempo del vencimiento de watch.
Recibe notificaciones
Cada vez que se produzca una actualización del buzón que coincida con tu watch, tu aplicación recibirá un mensaje de notificación que describa el cambio.
Si configuraste una suscripción push, la notificación de webhook a tu servidor cumplirá con un PubsubMessage:
POST https://yourserver.example.com/yourUrl
Content-type: application/json
{
message:
{
// This is the actual notification data, as base64url-encoded JSON.
data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",
// This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
"messageId": "2070443601311540",
// This is the publish time of the message.
"publishTime": "2021-02-26T19:13:55.749Z",
}
subscription: "projects/myproject/subscriptions/mysubscription"
}
El cuerpo de la solicitud HTTP POST es JSON y la carga útil de notificación real de Gmail se encuentra en el campo message.data. Ese campo message.data es una cadena codificada en base64url que se decodifica en un objeto JSON que contiene la dirección de correo electrónico y el nuevo ID del historial del buzón del usuario:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Luego, puedes usar history.list para obtener los detalles del cambio del usuario desde su historyId conocido más reciente, según la guía de sincronización.
Por ejemplo, para usar history.list y, así, identificar los cambios que se produjeron entre tu llamada inicial a watch y la recepción del mensaje de notificación compartido en el ejemplo anterior, pasa 1234567890 como startHistoryId a history.list.
Luego,9876543210 se puede conservar como el historyId conocido más reciente para casos de uso futuros.
Si configuraste una suscripción de extracción, consulta las muestras de código en la Guía de extracción para suscriptores de Cloud Pub/Sub para obtener más detalles sobre la recepción de mensajes.
Cómo responder notificaciones
Se deben confirmar todas las notificaciones. Si usas la entrega push de webhook, responder correctamente (p.ej., HTTP 200) confirmará la notificación.
Si usas la entrega de extracción (REST Pull, RPC Pull o RPC StreamingPull), debes realizar una llamada de confirmación (REST o RPC). Consulta las muestras de código en la Guía de extracción de suscriptores de Cloud Pub/Sub para obtener más detalles sobre cómo confirmar la recepción de mensajes de forma asíncrona o síncrona con las bibliotecas cliente oficiales basadas en RPC.
Si no se confirman las notificaciones (p.ej., la devolución de llamada del webhook muestra un error o se agota el tiempo de espera), Cloud Pub/Sub volverá a intentar enviar la notificación más adelante.
Cómo detener las actualizaciones de buzones
Para dejar de recibir actualizaciones sobre un buzón de correo, llama a stop y todas las notificaciones nuevas deberían detenerse en unos minutos.
Limitaciones
Frecuencia máxima de notificaciones
Cada usuario de Gmail observado tiene una tasa máxima de notificaciones de 1 evento/s. Se descartarán las notificaciones de usuario que superen esa tasa. Ten cuidado cuando manipules las notificaciones para asegurarte de no activar otra y, de ese modo, iniciar un bucle de notificaciones.
Confiabilidad
Por lo general, todas las notificaciones se deben entregar de forma confiable en unos segundos. Sin embargo, en algunas situaciones extremas, es posible que se retrasen o se pierdan.
Asegúrate de controlar esta posibilidad con facilidad para que la aplicación se siga sincronizando incluso si no se reciben mensajes push. Por ejemplo, recurre a llamar a history.list de forma periódica después de un período sin notificaciones para un usuario.
Limitaciones de Cloud Pub/Sub
La API de Cloud Pub/Sub también tiene sus propias limitaciones, que se detallan en su documentación de precios y cuotas.