En este documento, se describe cómo usar notificaciones push que informan a tu aplicación cuando cambia un recurso.
Descripción general
La API de Google Drive proporciona notificaciones push que te permiten supervisar los cambios en los recursos. Puedes usar esta función para mejorar el rendimiento de tu aplicación. Te permite eliminar los costos adicionales de red y procesamiento relacionados con los recursos de sondeo para determinar si cambiaron. Cada vez que cambia un recurso supervisado, la API de Google Drive notifica a tu aplicación.
Para usar las notificaciones push, debes hacer dos cosas:
Configura la URL de recepción o el receptor de devolución de llamada de "webhook".
Este es un servidor HTTPS que controla los mensajes de notificación de la API que se activan cuando cambia un recurso.
Configura un (canal de notificación) para cada extremo del recurso que desees mirar.
Un canal especifica la información de enrutamiento para los mensajes de notificación. Como parte de la configuración del canal, debes identificar la URL específica en la que deseas recibir notificaciones. Cada vez que cambia el recurso de un canal, la API de Google Drive envía un mensaje de notificación como una solicitud
POST
a esa URL.
Actualmente, la API de Google Drive admite notificaciones sobre cambios en los métodos files
y changes
.
Crea canales de notificaciones
Si quieres solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que quieras supervisar. Una vez configurados los canales de notificaciones, la API de Google Drive informa a tu aplicación cuando cambia algún recurso supervisado.
Cómo realizar solicitudes de supervisión
Cada recurso de la API de Google Drive para mirar tiene un método watch
asociado en un URI de la siguiente forma:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Si quieres configurar un canal de notificaciones para mensajes sobre cambios en un recurso en particular, envía una solicitud POST
al método watch
del recurso.
Cada canal de notificaciones está asociado a un usuario en particular y a un recurso (o conjunto de recursos) particular. Una solicitud watch
no se realizará correctamente, a menos que el usuario o la cuenta de servicio actuales sean propietarios de este recurso o tengan permiso para acceder a él.
Ejemplos
En la siguiente muestra de código, se indica cómo usar un recurso channels
para comenzar a observar cambios en un solo recurso files
con el método files.watch
:
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
En la siguiente muestra de código, se indica cómo usar un recurso channels
para comenzar a observar todos los changes
con el método changes.watch
:
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
Propiedades obligatorias
Con cada solicitud watch
, debes completar estos campos:
-
Una cadena de propiedad
id
que identifica de forma única este canal de notificaciones nuevo dentro del proyecto. Recomendamos usar un identificador único universal (UUID) o cualquier cadena única similar. Longitud máxima: 64 caracteres.El valor de ID que estableces se repite en el encabezado HTTP
X-Goog-Channel-Id
de cada mensaje de notificación que recibes para este canal. -
Una cadena de propiedad
type
configurada en el valorweb_hook
. -
Una cadena de propiedad
address
configurada en la URL que escucha y responde las notificaciones de este canal de notificaciones. Esta es la URL de devolución de llamada de tu webhook y debe usar HTTPS.Ten en cuenta que la API de Google Drive puede enviar notificaciones a esta dirección HTTPS solo si hay un certificado SSL válido instalado en tu servidor web. Entre los certificados no válidos, se incluyen los siguientes:
- Certificados autofirmados
- Certificados firmados por una fuente no confiable
- Certificados revocados
- Certificados que tienen un asunto que no coincide con el nombre de host de destino.
Propiedades opcionales
También puedes especificar estos campos opcionales con tu solicitud watch
:
-
Una propiedad
token
que especifica un valor de cadena arbitrario para usar como un token del canal. Puedes usar tokens del canal de notificaciones para varios fines. Por ejemplo, puedes usar el token para verificar que cada mensaje entrante corresponda a un canal que creó tu aplicación (a fin de garantizar que la notificación no se falsifique) o para enrutar el mensaje al destino correcto dentro de tu aplicación según el propósito de este canal. Longitud máxima: 256 caracteres.El token se incluye en el encabezado HTTP
X-Goog-Channel-Token
en cada mensaje de notificación que tu aplicación recibe para este canal.Si usas tokens del canal de notificaciones, te recomendamos lo siguiente:
Usa un formato de codificación extensible, como los parámetros de consulta de URL. Ejemplo:
forwardTo=hr&createdBy=mobile
No incluyas datos sensibles, como tokens de OAuth.
-
Una cadena de propiedad
expiration
configurada en una marca de tiempo Unix (en milisegundos) que corresponde a la fecha y hora en las que quieres que la API de Google Drive deje de enviar mensajes para este canal de notificaciones.Si un canal tiene una fecha de vencimiento, se incluye como el valor del encabezado HTTP
X-Goog-Channel-Expiration
(en un formato legible) en cada mensaje de notificación que recibe tu aplicación para este canal.
Si deseas obtener más detalles sobre la solicitud, consulta el método watch
para los métodos files
y changes
en la Referencia de la API.
Mirar respuesta
Si la solicitud watch
crea correctamente un canal de notificaciones, muestra un código de estado HTTP 200 OK
.
El cuerpo del mensaje de la respuesta de observación proporciona información sobre el canal de notificaciones que acabas de crear, como se muestra en el siguiente ejemplo.
{ "kind": "api#channel", "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
Además de las propiedades que enviaste como parte de tu solicitud, la información que se muestra también incluye resourceId
y resourceUri
para identificar el recurso que se está mirando en este canal de notificaciones.
Puedes pasar la información que se muestra a otras operaciones del canal de notificaciones, como cuando deseas dejar de recibir notificaciones.
Si deseas obtener más detalles sobre la respuesta, consulta el método watch
para los métodos files
y changes
en la Referencia de la API.
Sincronizar mensaje
Después de crear un canal de notificaciones para ver un recurso, la API de Google Drive envía un mensaje sync
para indicar que comienzan las notificaciones. El valor del encabezado HTTP X-Goog-Resource-State
para estos mensajes es sync
. Debido a problemas de sincronización de la red, es posible recibir el mensaje sync
incluso antes de recibir la respuesta del método watch
.
Puedes ignorar la notificación sync
, pero también puedes usarla. Por ejemplo, si decides que no quieres conservar el canal, puedes usar los valores X-Goog-Channel-ID
y X-Goog-Resource-ID
en una llamada para dejar de recibir notificaciones. También puedes usar la notificación sync
para realizar la inicialización y prepararte para los eventos posteriores.
A continuación, se muestra el formato de los mensajes de sync
que la API de Google Drive envía a tu URL de destino.
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
Los mensajes de sincronización siempre tienen un valor de encabezado HTTP X-Goog-Message-Number
de 1
. Cada notificación posterior de este canal tiene un número de mensaje mayor que la anterior, aunque los números de mensaje no serán secuenciales.
Renovar canales de notificaciones
Un canal de notificaciones puede tener una fecha de vencimiento, con un valor determinado por tu solicitud o por cualquier límite interno o predeterminado de la API de Google Drive (se usa el valor más restrictivo). El tiempo de vencimiento del canal, si tiene uno, se incluye como una marca de tiempo Unix (en milisegundos) en la información que muestra el método watch
. Además, la fecha y hora de vencimiento se incluyen (en formato legible) en cada mensaje de notificación que recibe tu aplicación para este canal en el encabezado HTTP X-Goog-Channel-Expiration
.
Actualmente, no existe una manera automática de renovar un canal de notificaciones. Cuando esté por vencer un canal, deberás reemplazarlo por uno nuevo llamando al método watch
. Como siempre, debes usar un valor único para la propiedad id
del canal nuevo. Ten en cuenta que es probable que haya un período de “superposición” en el que los dos canales de notificaciones para el mismo recurso están activos.
Recepción de notificaciones
Cada vez que cambia un recurso supervisado, la aplicación recibe un mensaje de notificación que describe el cambio. La API de Google Drive envía estos mensajes como solicitudes POST
HTTPS a la URL que especificaste como la propiedad address
para este canal de notificaciones.
Interpreta el formato del mensaje de notificación
Todos los mensajes de notificación incluyen un conjunto de encabezados HTTP que tienen prefijos X-Goog-
.
Algunos tipos de notificaciones también pueden incluir el cuerpo del mensaje.
Encabezados
Los mensajes de notificación que publica la API de Google Drive en tu URL de recepción incluyen los siguientes encabezados HTTP:
Encabezado | Descripción |
---|---|
Siempre presente | |
|
UUID o cualquier otra cadena única que hayas proporcionado para identificar este canal de notificaciones. |
|
Es el número entero que identifica este mensaje para este canal de notificaciones. El valor es siempre 1 para los mensajes de sync . Los números de mensajes aumentan para cada mensaje posterior en el canal, pero no son secuenciales. |
|
Valor opaco que identifica el recurso observado. Este ID es estable en todas las versiones de la API. |
|
El nuevo estado del recurso que activó la notificación.
Valores posibles: sync , add , remove , update , trash , untrash o change .
|
|
Un identificador específico de la versión de la API para el recurso observado. |
A veces está presente | |
|
Detalles adicionales sobre los cambios.
Valores posibles: content , parents , children o permissions .
No se proporcionó con sync mensajes. |
|
Es la fecha y hora de vencimiento del canal de notificación, expresadas en un formato legible. Solo está presente si está definido. |
|
Es el token del canal de notificaciones que estableció tu aplicación y que puedes usar para verificar la fuente de notificaciones. Solo está presente si está definido. |
Los mensajes de notificación para files
y changes
están vacíos.
Ejemplos
Cambia el mensaje de notificación para los recursos files
, que no incluye un cuerpo de solicitud:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
Cambia el mensaje de notificación para los recursos changes
, que incluye un cuerpo de solicitud:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
Responder notificaciones
Para indicar que la operación se realizó correctamente, puedes mostrar cualquiera de los siguientes códigos de estado: 200
, 201
, 202
, 204
o 102
.
Si tu servicio usa la biblioteca cliente de la API de Google y muestra 500
, 502
, 503
o 504
, la API de Google Drive vuelve a intentarlo con una retirada exponencial.
Todos los demás códigos de estado de retorno se consideran como errores de mensaje.
Información sobre los eventos de notificación de la API de Google Drive
En esta sección, se proporcionan detalles sobre los mensajes de notificación que puedes recibir cuando usas notificaciones push con la API de Google Drive.
Se entrega cuando | ||
---|---|---|
sync |
files , changes |
Se creó correctamente un canal. Puedes comenzar a recibir notificaciones sobre este tema. |
add |
files |
Se creó o se compartió un recurso. |
|
files |
Se borró o dejó de compartir un recurso existente. |
|
files |
Se actualizaron una o más propiedades (metadatos) de un recurso. |
|
files |
Se movió un recurso a la papelera. |
|
files |
Se quitó un recurso de la papelera. |
|
changes |
Se han agregado uno o más elementos de registro de cambios. |
Para los eventos update
, se puede proporcionar el encabezado HTTP X-Goog-Changed
. Ese encabezado contiene una lista separada por comas que describe los tipos de cambios que se produjeron.
Change type | Qué indica |
---|---|
content |
Se actualizó el contenido del recurso. |
properties |
Se actualizaron una o más propiedades del recurso. |
parents |
Se agregaron o quitaron uno o más recursos superiores. |
children |
Se agregaron o quitaron uno o más recursos secundarios. |
permissions |
Se actualizaron los permisos del recurso. |
Ejemplo con encabezado X-Goog-Changed
:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
Detener notificaciones
La propiedad expiration
controla cuándo se detienen automáticamente las notificaciones. Puedes optar por dejar de recibir notificaciones de un canal en particular antes de su vencimiento llamando al método stop
en el siguiente URI:
https://www.googleapis.com/drive/v3/channels/stop
Este método requiere que proporciones al menos las propiedades id
y resourceId
del canal, como se muestra en el siguiente ejemplo. Ten en cuenta que si la API de Google Drive tiene varios tipos de recursos que tienen métodos watch
, solo hay un método stop
.
Solo los usuarios que tienen el permiso adecuado pueden detener un canal. En particular, considera lo siguiente:
- Si el canal se creó con una cuenta de usuario normal, solo el mismo usuario del mismo cliente (identificado por los ID de cliente OAuth 2.0 de los tokens de autenticación) que creó el canal puede detenerlo.
- Si el canal se creó con una cuenta de servicio, cualquier usuario del mismo cliente puede detener el canal.
En la siguiente muestra de código, se indica cómo dejar de recibir notificaciones:
POST https://www.googleapis.com/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }