Descripción general
La API de Gmail proporciona notificaciones push del servidor que te permiten observar 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 involucrados en el sondeo de recursos para determinar si cambiaron. Cada vez que un buzón cambia, la API de Gmail notifica a la 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 una variedad de métodos, incluidos webhooks y sondeos en un único extremo de suscripción.
Requisitos previos
Para completar el resto de la 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 debe enviar notificaciones. El nombre del tema puede ser cualquier nombre que elijas en tu proyecto (es decir, que coincida con projects/myproject/topics/*, en el que myproject es el ID del proyecto que se muestra para tu proyecto en Google Developers Console).
Te recomendamos que uses un solo tema para todas las notificaciones push de la API de Gmail de tu aplicación, debido a los límites de Cloud Pub/Sub en la cantidad de temas.
Crea una suscripción
Sigue la Guía para suscriptores de Cloud Pub/Sub a fin de configurar una suscripción al tema que creaste. Configura el tipo de suscripción para que sea un push de webhook (es decir, una devolución de llamada HTTP POST) o de extracción (es decir, que inicie 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 si sigues las instrucciones de control de acceso a nivel de los recursos.
Obteniendo actualizaciones del buzón de Gmail
Una vez que finalice la configuración inicial de Cloud Pub/Sub, configura las cuentas de Gmail para que envíen notificaciones sobre las actualizaciones de los buzones.
Solicitud de observación
Si quieres configurar las cuentas de Gmail para enviar notificaciones a tu tema de Cloud Pub/Sub, solo debes usar el cliente de la API de Gmail para llamar a watch en el buzón de usuario de Gmail, de forma similar a cualquier otra llamada a la API de Gmail.
Para ello, proporciona el nombre del tema que creaste antes y cualquier otra opción en tu solicitud watch, como labels, para filtrar. Por ejemplo, para recibir una notificación cada vez que se realice un cambio en Recibidos:
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()
Mirar 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. Todos los cambios posteriores a historyId se notificarán a tu cliente. Si necesitas procesar cambios antes de este historyId, consulta la guía de sincronización.
Además, una llamada a watch exitosa debe enviar de inmediato una notificación a tu tema de Cloud Pub/Sub.
Si recibes un error de la llamada a watch, los detalles deberían explicar el origen del problema, que suele ser 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 con la depuración de problemas de temas y suscripciones.
Renovando el reloj del buzón
Debes volver a llamar a watch al menos cada 7 días. De lo contrario, dejarás de recibir actualizaciones para el usuario. Te recomendamos llamar a watch una vez al día. La respuesta watch también tiene un campo de vencimiento con la marca de tiempo del vencimiento watch.
Recibe notificaciones
Cada vez que se actualice el buzón de correo que coincida con tu watch, la aplicación recibirá un mensaje de notificación que describe el cambio.
Si configuraste una suscripción push, una notificación de webhook a tu servidor se ajustará 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 HTTP POST es JSON y la carga útil real de la notificación de Gmail se encuentra en el campo message.data. Ese campo message.data es una string 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, de acuerdo con la guía de sincronización.
En cambio, si configuraste una suscripción de extracción, consulta las muestras de código en la Guía de extracción del suscriptor 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 de envío de webhook, la respuesta correcta (p.ej., HTTP 200) confirmará la notificación.
Si usas la entrega de extracción (extracción de REST, extracción de RPC o RPC StreamingPull), debes realizar un seguimiento con una llamada de confirmación (REST o RPC). Consulta las muestras de código en la Guía de extracción del suscriptor de Cloud Pub/Sub para obtener más detalles sobre la confirmació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 de webhook muestra un error o se agota el tiempo de espera), Cloud Pub/Sub volverá a intentar la notificación más adelante.
Deteniendo las actualizaciones de los buzones
Para dejar de recibir actualizaciones en un buzón, llama a stop y todas las notificaciones nuevas deberían detenerse en unos minutos.
Limitaciones
Tasa máxima de notificaciones
Cada usuario de Gmail que se mira tiene una frecuencia de notificaciones máxima de 1 evento/s. Se descartarán todas las notificaciones de usuario que superen esa frecuencia. Ten cuidado cuando controles notificaciones, para asegurarte de no activar otra y, por lo tanto, iniciar un bucle de notificaciones.
Confiabilidad
Por lo general, todas las notificaciones deben entregarse de manera confiable en pocos segundos. Sin embargo, en algunas situaciones extremas, las notificaciones pueden retrasarse o descartarse.
Asegúrate de manejar esta posibilidad correctamente, para que la aplicación aún se sincronice, incluso si no se reciben mensajes push. Por ejemplo, vuelve a llamar de forma periódica a 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 pricing y quotas.