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 la sondeo de 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 varios métodos, incluidos los webhooks y la sondeo 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 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 aparece en tu proyecto en Google Play 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 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 POST HTTP) o un envío de extracción (es decir, que inicie tu app). De esta manera, 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 publish a gmail-api-push@system.gserviceaccount.com. Puedes hacerlo con la interfaz de permisos de la consola de 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 se complete la configuración inicial de Cloud Pub/Sub, configura las cuentas de Gmail para que envíen notificaciones de actualizaciones de buzón.
Solicitud de reproducción
Para configurar cuentas de Gmail para que envíen notificaciones a tu tema de Cloud Pub/Sub,
solo usa tu cliente de la API de Gmail para llamar a
watch
en el buzón de usuario de Gmail, de manera similar a cualquier otra llamada a la API de Gmail.
Para ello, proporciona el nombre del tema creado anteriormente 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, 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()
Cómo ver la respuesta
Si la solicitud watch se realiza correctamente, recibirás una respuesta como la siguiente:
{
historyId: 1234567890
expiration: 1431990098200
}
con el buzón historyId actual del usuario. Se notificarán a tu cliente todos los cambios después de ese historyId. Si necesitas procesar cambios antes de este historyId, consulta la guía de sincronización.
Además, una llamada watch correcta debería hacer que se envíe una notificación de inmediato a tu tema de Cloud Pub/Sub.
Si recibes un error de la llamada a watch, los detalles deberían 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 con la depuración de problemas de temas y suscripciones.
Cómo renovar 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 del 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 de watch.
Recibe notificaciones
Cada vez que se produzca una actualización de buzón que coincida con tu watch, tu aplicación recibirá un mensaje de notificación en el que se describirá 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 de 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 cadena codificada en base64url que se decodifica en un objeto JSON que contiene la dirección de correo electrónico y el nuevo ID de historial de buzón del usuario:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Luego, puedes usar history.list para obtener los detalles de los cambios del usuario desde su último historyId conocido, según la guía de sincronización.
Si, en cambio, 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 cómo recibir mensajes.
Cómo responder notificaciones
Se deben confirmar todas las notificaciones. Si usas la entrega mediante webhook, la notificación se confirmará si respondes correctamente (p.ej., HTTP 200).
Si usas la entrega de extracción (REST Pull, RPC Pull o RPC StreamingPull), debes realizar un seguimiento con una llamada de confirmación (REST o RPC). Consulta las muestras de código de la Guía de extracción para suscriptores de Cloud Pub/Sub para obtener más detalles sobre cómo confirmar mensajes de forma asíncrona o de forma síncrona con las bibliotecas cliente oficiales basadas en RPC.
Si no se confirman las notificaciones (p.ej., la devolución de llamada de tu webhook muestra un error o se agota el tiempo de espera), Cloud Pub/Sub volverá a intentar la notificación más adelante.
Cómo detener 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
Frecuencia máxima de notificaciones
Cada usuario de Gmail que se supervisa tiene una tasa máxima de notificaciones de 1 evento por segundo. Se descartarán todas las notificaciones del usuario que superen esa tasa. Ten cuidado cuando administres las notificaciones para asegurarte de no activar otra y, de esta manera, iniciar un bucle de notificaciones.
Confiabilidad
Por lo general, todas las notificaciones deben entregarse de forma confiable en unos segundos.
Sin embargo, en algunas situaciones extremas, es posible que las notificaciones se retrasen o se pierdan.
Asegúrate de controlar esta posibilidad de forma fluida, de modo que la aplicación
se sincronice incluso si no se reciben mensajes push. Por ejemplo, recurre a llamar periódicamente 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 específicamente en la documentación de precios y cuotas.