En este documento, se explica cómo administrar las notificaciones push en la API de Gmail.
La API de Gmail proporciona notificaciones push del servidor que te permiten estar atento a los cambios en los buzones de Gmail. Usa esta función para mejorar el rendimiento de tu aplicación. Elimina los costos adicionales de red y procesamiento de los recursos de sondeo para determinar si cambiaron. Cada vez que cambia un buzón, la API de Gmail notifica a tu aplicación del 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 las notificaciones a través de varios métodos, incluidos los webhooks y el sondeo en un solo extremo de suscripción.
Requisitos previos
Para completar esta configuración, cumple 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 debe enviar notificaciones. El nombre del tema puede ser cualquiera que elijas en tu proyecto (por ejemplo, que coincida con projects/myproject/topics/*, donde myproject es el ID del proyecto que aparece en la consola de Google Cloud).
Crea una suscripción
Para configurar una suscripción al tema que creaste, sigue la guía sobre el tipo de suscripción de Cloud Pub/Sub. 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 recibe 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, otorga privilegios de publish a gmail-api-push@system.gserviceaccount.com. Para ello, sigue estas instrucciones de control de acceso en la consola de permisos de Cloud Pub/Sub de la consola de Google Cloud.
Es posible que la configuración de uso compartido restringido por dominio de tu organización te impida otorgar permisos de publicación. Para resolver este problema, puedes configurar una excepción para esta cuenta de servicio.
Recibe actualizaciones de la casilla 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 reloj
Para configurar las cuentas de Gmail para que envíen notificaciones a tu tema de Cloud Pub/Sub, usa tu cliente de la API de Gmail para llamar al método watch en el buzón de correo del usuario de Gmail. Esto es similar a cualquier otra llamada a la API de Gmail. Proporciona el nombre del tema que creaste y cualquier otra opción en tu solicitud de watch, como labels para filtrar. Por ejemplo, usa la siguiente solicitud para recibir una notificación cada vez que se realice un cambio en la bandeja de entrada:
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()
Respuesta del reloj
Si la solicitud de watch se realiza correctamente, recibirás una respuesta como la siguiente:
{ historyId: 1234567890 expiration: 1431990098200 }
La respuesta contiene el objeto historyId de buzón de correo actual del usuario. Tu cliente recibirá notificaciones de todos los cambios después de esa fecha historyId. Si necesitas procesar cambios antes de esta fecha historyId, consulta Cómo sincronizar clientes con la API de Gmail.
Además, una llamada watch exitosa hace que se envíe de inmediato una notificación a tu tema de Cloud Pub/Sub.
Si recibes un error de la llamada watch, los detalles deberían explicar la fuente del problema. Por lo general, este problema se debe a 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.
Renueva la observación del buzón
Debes llamar a watch al menos una vez cada 7 días, o dejarás de recibir actualizaciones para el usuario. Te recomendamos que llames a watch una vez al día. La respuesta del método watch también tiene un campo expiration con la marca de tiempo del vencimiento de watch.
Recibir notificaciones
Cada vez que se produce una actualización del buzón de correo que coincide con tu watch, tu aplicación recibe un mensaje de notificación que describe el cambio.
Si configuraste una suscripción de envío, una notificación de webhook a tu servidor se ajusta a 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 real de la notificación de Gmail se encuentra en el campo message.data. El 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 el método history.list para obtener los detalles de los cambios del usuario desde su última ubicación conocida
historyId, como se describe en Cómo sincronizar clientes con la API de Gmail.
Por ejemplo, usa el método history.list para identificar los cambios que se produjeron entre tu solicitud inicial de watch y la recepción del mensaje de notificación que se compartió en el ejemplo anterior. Pasa 1234567890 como startHistoryId a history.list. Luego, puedes conservar 9876543210 como el historyId conocido más reciente para casos de uso futuros.
Si configuraste una suscripción de extracción, consulta los ejemplos de código en la guía de suscripciones de extracción de Cloud Pub/Sub para obtener más detalles sobre la recepción de mensajes.
Responder notificaciones
Se deben confirmar todas las notificaciones. Si usas la entrega push de webhook, responder correctamente (por ejemplo, con HTTP 200) confirma la recepción de la notificación.
Si usas la entrega de extracción (REST Pull, RPC Pull o RPC StreamingPull), debes hacer un seguimiento con una llamada de confirmación (REST o RPC). Consulta los ejemplos de código de la guía de suscripciones de extracción 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 confirmas la recepción de las notificaciones (por ejemplo, si 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 del buzón
Para dejar de recibir actualizaciones sobre un buzón, llama al método stop. Todas las notificaciones nuevas deberían detenerse en unos minutos.
Limitaciones
A continuación, se indican las limitaciones para trabajar con notificaciones push del servidor:
Frecuencia máxima de notificaciones
Cada usuario de Gmail supervisado tiene una tasa máxima de notificaciones de un evento por segundo. Se descartan las notificaciones de usuario que superen esa tasa. Cuando manejes notificaciones, ten cuidado de no activar otra notificación, ya que esto puede iniciar un bucle de notificaciones.
Confiabilidad
Por lo general, todas las notificaciones se entregan de forma confiable en cuestión de segundos. Sin embargo, en algunas situaciones extremas, es posible que se retrasen o se pierdan.
Controla esta posibilidad con elegancia para que la aplicación se siga sincronizando incluso si no se reciben mensajes push. Por ejemplo, vuelve a llamar periódicamente al método history.list 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.