Este documento describe cómo usar notificaciones push que informen a tus cuando un recurso cambia.
Descripción general
La API de Google Drive proporciona notificaciones push cambios en los recursos. Puedes usar esta función para mejorar el rendimiento de tu aplicación. Te permite eliminar la red adicional y el procesamiento los costos relacionados con los recursos de sondeo para determinar si cambiaron. Cada vez que un recurso supervisado cambia, la API de Google Drive le notifica a tu y mantener la integridad de su aplicación.
Para usar las notificaciones push, debes hacer dos cosas:
Cómo configurar tu URL de recepción o "webhook" receptor de devolución de llamada.
Esta es un servidor HTTPS que controla los mensajes de notificación de la API que se que se activa cuando cambia un recurso.
Configura un (canal de notificación) para cada extremo de recurso que desees. reloj.
Un canal especifica la información de enrutamiento para la notificación mensajes nuevos. Como parte de la configuración del canal, debes identificar la URL específica donde quieres recibir notificaciones. Cuando cambia el recurso de un canal, la API de Google Drive envía un mensaje de notificación como
POST
a esa URL.
Actualmente, la API de Google Drive admite notificaciones de cambios en
los métodos files
y changes
Crea canales de notificaciones
Para solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que quieras supervisar. Después de configurar los canales de notificaciones la API de Google Drive informa a tu aplicación cuando se detecta cambios.
Cómo realizar solicitudes de supervisión
Cada recurso de la API de Google Drive para mirar tiene un
watch
en un URI con el siguiente formato:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Si deseas configurar un canal de notificaciones para los mensajes sobre los cambios en una
recurso específico, envía una solicitud POST
al
Método watch
para el recurso.
Cada canal de notificaciones se asocia con un usuario en particular y
de un recurso (o conjunto de recursos) en particular. Una solicitud watch
no tendrá éxito, a menos que el usuario actual
o cuenta de servicio
es propietario de este recurso o tiene 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 esto de forma única nuevo canal de notificaciones dentro de tu proyecto. Recomendamos usar un identificador único a nivel universal (UUID) o cualquier opción similar o una cadena única. Longitud máxima: 64 caracteres.El valor de ID que establezcas se replicará en la Encabezado HTTP
X-Goog-Channel-Id
de cada notificación que recibas 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. Este es la URL de devolución de llamada del webhook que debe usar HTTPS.Ten en cuenta que la API de Google Drive puede enviar notificaciones a esta dirección HTTPS solo si hay instalado un certificado SSL válido 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 con un asunto que no coincide con el objetivo nombre de host.
Propiedades opcionales
También puedes especificar estos campos opcionales con tu
Solicitud de watch
:
-
Una propiedad
token
que especifica una cadena arbitraria valor para usar como token del canal. Puedes usar el canal de notificaciones los tokens para varios fines. Por ejemplo, puedes usar el token para verificar que cada mensaje entrante sea para un canal al que tu para garantizar que la notificación no se envíe de identidad, o para enrutar el mensaje al destino correcto en la postulación en función del objetivo de este canal. Longitud máxima: 256 caracteres.El token se incluye en el Encabezado HTTP
X-Goog-Channel-Token
en cada notificación mensaje 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 una consulta de URL parámetros. Ejemplo:
forwardTo=hr&createdBy=mobile
No incluyas datos sensibles, como tokens de OAuth.
-
Una cadena de propiedad
expiration
establecida en un Marca de tiempo Unix (en milisegundos) de la fecha y hora en que deseas que la API de Google Drive dejar de enviar mensajes para este canal de notificaciones.Si un canal tiene un período de vencimiento, se incluye como valor del encabezado HTTP
X-Goog-Channel-Expiration
(en formato legible formato) en todos los mensajes de notificación que recibe la aplicación para este canal.
Para 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 una notificación correctamente
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
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 devuelta a otro canal de notificaciones operaciones, como cuando quieres dejar de recibir notificaciones.
Para obtener más detalles sobre la respuesta, consulta el 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, el
La API de Google Drive envía un mensaje sync
para indicar que
están empezando las notificaciones. El HTTP X-Goog-Resource-State
el valor del encabezado para estos mensajes es sync
. Debido a la red
problemas de tiempo, es posible recibir el mensaje sync
incluso antes de recibir la respuesta del método watch
.
Puedes omitir la notificación sync
, pero puedes
que también la usan. Por ejemplo, si decides que no quieres mantener
el canal, puedes usar X-Goog-Channel-ID
y
valores de X-Goog-Resource-ID
en una llamada a
dejar de recibir notificaciones. También puedes usar
sync
para realizar una inicialización y prepararse
eventos posteriores.
El formato de los mensajes de sync
que envía la API de Google Drive
tu URL de recepción se muestra debajo.
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 HTTP X-Goog-Message-Number
valor de encabezado de 1
. Cada notificación posterior para este canal tiene
un número de mensaje mayor que el anterior, aunque el mensaje
los números no aparecerán en orden secuencial.
Renovar canales de notificaciones
Un canal de notificaciones puede tener una fecha de vencimiento, con un valor
determinados por tu solicitud o por cualquier límite interno de la API de Google Drive
o valores predeterminados (se usa el valor más restrictivo). El vencimiento del canal
hora, si tiene una, se incluye como una marca de tiempo Unix
(en milisegundos) en la información que muestra el método watch
. Además, el
se incluyen la fecha y hora de vencimiento (en un 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. Cuándo
un canal está por vencer, debes reemplazarlo por uno nuevo llamando
el método watch
Como siempre, debes usar un valor único para
la propiedad id
del canal nuevo Ten en cuenta que probablemente
como una "superposición" período en el que los dos canales de notificación del
mismo recurso estén activos.
Recepción de notificaciones
Cada vez que cambia un recurso observado, tu aplicación recibe
de notificación en la que se describe el cambio. La API de Google Drive envía estas
como solicitudes POST
HTTPS a la URL que especificaste como el
Hay address
propiedad para esta notificación
canal.
Interpreta el formato del mensaje de notificación
Todos los mensajes de notificación incluyen un conjunto de encabezados HTTP que tienen
X-Goog-
.
Algunos tipos de notificaciones también pueden incluir un
cuerpo del mensaje.
Encabezados
Mensajes de notificación publicados por la API de Google Drive al destinatario Las URL incluyen los siguientes encabezados HTTP:
Encabezado | Descripción |
---|---|
Siempre presente | |
|
UUID o alguna otra cadena única que hayas proporcionado para identificarlo canal de notificaciones. |
|
Número entero que identifica el mensaje de esta notificación
canal. El valor es siempre 1 para los mensajes de sync . Mensaje
aumentan para cada mensaje posterior en el canal, pero son
y no secuencial. |
|
Valor opaco que identifica el recurso observado. Este ID es estable entre las versiones de API. |
|
El nuevo estado del recurso que activó la notificación.
Valores posibles:
sync , add , remove y update
trash , untrash o change
de Google Cloud.
|
|
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
de Google Cloud.
No se proporcionó con sync mensajes. |
|
Fecha y hora de vencimiento del canal de notificación, expresadas en en un formato legible por humanos. Solo está presente si está definido. |
|
El token del canal de notificaciones que estableció tu aplicación. que puedes usar para verificar la fuente de notificación. Solo está presente si 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
reintentos con 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 use 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.
Tipo de cambio | 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
decide dejar de recibir notificaciones de un canal en particular antes de que
expira 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, el nombre de tu canal
id
y las propiedades resourceId
, como se muestra en
ejemplo a continuación. Ten en cuenta que si la API de Google Drive tiene varios tipos de
recursos que tienen métodos watch
, solo hay uno
stop
.
Solo los usuarios que tienen el permiso adecuado pueden detener un canal. En particular:
- Si el canal se creó con una cuenta de usuario común, solo se admitirá usuario del mismo cliente (tal como lo identifican los IDs de cliente de OAuth 2.0 del tokens de autenticación) que crearon el canal pueden detenerlo.
- Si el canal se creó con una cuenta de servicio, cualquier usuario de la misma 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" }