Se usó la API de Cloud Translation para traducir esta página.

Configurar y recibir notificaciones push

Puedes usar los métodos de la colección Watches para recibir notificaciones cuando cambien los datos en los formularios. En esta página, se proporciona una descripción general conceptual y las instrucciones para configurar y recibir notificaciones push.

Descripción general

La función de notificaciones push de la API de Formularios de Google permite que las aplicaciones se suscriban a notificaciones cuando cambian los datos en los formularios. Las notificaciones se entregan a un tema de Cloud Pub/Sub, por lo general, en minutos después del cambio.

Para recibir notificaciones push, debes configurar un tema de Cloud Pub/Sub y proporcionar su nombre cuando crees un objeto de supervisión para el tipo de evento adecuado.

A continuación, se incluyen las definiciones de los conceptos clave que se usan en esta documentación:

Un destino es un lugar al que se envían las notificaciones. El único objetivo compatible es un tema de Cloud Pub/Sub.
Un tipo de evento es una categoría de notificaciones a la que se puede suscribir una aplicación de terceros.
Un objeto de supervisión es una instrucción para la API de Formularios para enviar notificaciones de un tipo de evento en un formulario en particular a un destino.

Una vez que creas un objeto de supervisión para un tipo de evento en un formulario en particular, el objetivo de ese objeto de supervisión (que es un tema de Cloud Pub/Sub) recibe notificaciones de esos eventos en ese formulario hasta que venza el objeto de supervisión. El reloj dura una semana, pero puedes extenderlo en cualquier momento antes de que venza realizando una solicitud a watches.renew().

Tu tema de Cloud Pub/Sub solo recibe notificaciones sobre los formularios que puedes ver con las credenciales que proporciones. Por ejemplo, si el usuario revoca el permiso de tu aplicación o pierde el acceso de edición a un formulario supervisado, ya no se envían notificaciones.

Tipos de eventos disponibles

Actualmente, la API de Formularios de Google ofrece dos categorías de eventos:

EventType.SCHEMA, que notifica sobre los cambios en el contenido y la configuración de un formulario.
EventType.RESPONSES, que notifica cuando se envían respuestas de formularios (nuevas y actualizadas).

Respuestas a notificaciones

Las notificaciones se codifican con JSON y contienen lo siguiente:

El ID del formulario de activación
El ID del reloj de activación
Es el tipo de evento que activó la notificación.
Otros campos que establece Cloud Pub/Sub, como messageId y publishTime

Las notificaciones no contienen datos detallados de formularios ni respuestas. Después de recibir cada notificación, se requiere una llamada a la API independiente para recuperar datos actualizados. Consulta Uso sugerido para saber cómo hacerlo.

En el siguiente fragmento, se muestra una notificación de muestra para un cambio de esquema:

{
  "attributes": {
    "eventType": "SCHEMA",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "892515d1-a902-444f-a2fe-42b718fe8159"
  },
  "messageId": "767437830649",
  "publishTime": "2021-03-31T01:34:08.053Z"
}

En el siguiente fragmento, se muestra una notificación de muestra para una respuesta nueva:

{
  "attributes": {
    "eventType": "RESPONSES",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "5d7e5690-b1ff-41ce-8afb-b469912efd7d"
  },
  "messageId": "767467004397",
  "publishTime": "2021-03-31T01:43:57.285Z"
}

Configurar un tema de Cloud Pub/Sub

Las notificaciones se entregan a temas de Cloud Pub/Sub. Desde Cloud Pub/Sub, puedes recibir notificaciones en un webhook o sondeando un extremo de suscripción.

Para configurar un tema de Cloud Pub/Sub, haz lo siguiente:

Completa los requisitos previos de Cloud Pub/Sub.
Configura un cliente de Cloud Pub/Sub.
Revisa los precios de Cloud Pub/Sub y habilita la facturación para tu proyecto de Play Console.
Crea un tema de Cloud Pub/Sub de una de las siguientes tres maneras:
- con Developers Console (la opción más fácil)
- con la herramienta de línea de comandos (para un uso programático simple) o
- con la API de Cloud Pub/Sub.
Nota: Cloud Pub/Sub solo permite una cantidad limitada de temas, por lo que usar un tema para recibir todas tus notificaciones te garantiza que no encuentres problemas de escalamiento si tu aplicación se vuelve popular.
Crea una suscripción en Cloud Pub/Sub para indicarle a Cloud Pub/Sub cómo entregar tus notificaciones.
Por último, antes de crear objetos de supervisión que se orienten a tu tema, debes otorgar permiso a la cuenta de servicio de notificaciones de Formularios (forms-notifications@system.gserviceaccount.com) para que publique en tu tema.

Cómo crear un reloj

Una vez que tengas un tema al que la cuenta de servicio de notificaciones push de la API de Forms pueda publicar, puedes crear notificaciones con el método watches.create(). Este método valida que la cuenta de servicio de notificaciones push pueda acceder al tema de Cloud Pub/Sub proporcionado y falla si no puede hacerlo, por ejemplo, si el tema no existe o no le otorgaste permiso de publicación en ese tema.

PythonNode.js

forms/snippets/create_watch.py

Ver en GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)

service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

watch = {
    "watch": {
        "target": {"topic": {"topicName": "<YOUR_TOPIC_PATH>"}},
        "eventType": "RESPONSES",
    }
}

form_id = "<YOUR_FORM_ID>"

# Print JSON response after form watch creation
result = service.forms().watches().create(formId=form_id, body=watch).execute()
print(result)

forms/snippets/create_watch.js

Ver en GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const watchRequest = {
    watch: {
      target: {
        topic: {
          topicName: 'projects/<YOUR_TOPIC_PATH>',
        },
      },
      eventType: 'RESPONSES',
    },
  };
  const res = await forms.forms.watches.create({
    formId: formID,
    requestBody: watchRequest,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

Cómo borrar un reloj

PythonNode.js

forms/snippets/delete_watch.py

Ver en GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after deleting a form watch
result = (
    service.forms().watches().delete(formId=form_id, watchId=watch_id).execute()
)
print(result)

forms/snippets/delete_watch.js

Ver en GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';
const watchID = '<YOUR_FORMS_WATCH_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const res = await forms.forms.watches.delete({
    formId: formID,
    watchId: watchID,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

Autorización

Al igual que todas las llamadas a la API de Forms, las llamadas a watches.create() deben estar autorizadas con un token de autorización. El token debe incluir un permiso que otorgue acceso de lectura a los datos sobre las notificaciones que se envían.

En el caso de los cambios de esquema, esto significa cualquier alcance que otorgue acceso de lectura a los formularios con forms.get().
En el caso de las respuestas, esto significa cualquier permiso que otorgue acceso de lectura a las respuestas del formulario, por ejemplo, con forms.responses.list().

Para que se entreguen las notificaciones, la aplicación debe retener una concesión de OAuth del usuario autorizado con los permisos necesarios. Si el usuario desconecta la aplicación, las notificaciones cesan y es posible que el reloj se suspenda con un error. Para reanudar las notificaciones después de recuperar la autorización, consulta Cómo renovar un reloj.

Cómo enumerar los relojes de un formulario

PythonNode.js

forms/snippets/list_watches.py

Ver en GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"

# Print JSON list of form watches
result = service.forms().watches().list(formId=form_id).execute()
print(result)

forms/snippets/list_watches.js

Ver en GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';

async function runSample(query) {
  const auth = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/forms.responses.readonly',
  });
  const forms = google.forms({
    version: 'v1',
    auth: auth,
  });
  const res = await forms.forms.watches.list({formId: formID});
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

Cómo renovar un reloj

PythonNode.js

forms/snippets/renew_watch.py

Ver en GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after renewing a form watch
result = (
    service.forms().watches().renew(formId=form_id, watchId=watch_id).execute()
)
print(result)

forms/snippets/renew_watch.js

Ver en GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';
const watchID = '<YOUR_FORMS_WATCH_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const res = await forms.forms.watches.renew({
    formId: formID,
    watchId: watchID,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

Regulación

Las notificaciones se regulan, por lo que cada reloj puede recibir una notificación como máximo cada treinta segundos. Este umbral de frecuencia está sujeto a cambios.

Debido a la limitación, una sola notificación puede corresponder a varios eventos. En otras palabras, una notificación indica que se produjeron uno o más eventos desde la última notificación.

Límites

En cualquier momento, para un tipo de formulario y evento determinado, cada proyecto de Cloud Console puede tener lo siguiente:

hasta 20 vistas en total
hasta un reloj por usuario final

Además, en cualquier momento, cada formulario se limita a 50 objetos de supervisión por tipo de evento en total en todos los proyectos de la consola de Cloud.

Un reloj se asocia con un usuario final cuando se crea o se renueva con credenciales para ese usuario. Se suspende un reloj si el usuario final asociado pierde el acceso al formulario o revoca el acceso de la app al formulario.

Confiabilidad

Cada reloj recibe una notificación al menos una vez después de cada evento, excepto en circunstancias extraordinarias. En la gran mayoría de los casos, se entrega una notificación en minutos después de un evento.

Errores

Si las notificaciones de un reloj no se entregan de forma persistente, el estado del reloj se convierte en SUSPENDED y se establece el campo errorType del reloj. Para restablecer el estado de un reloj suspendido a ACTIVE y reanudar las notificaciones, consulta Cómo renovar un reloj.

Uso sugerido

Usa un solo tema de Cloud Pub/Sub como destino de muchos objetos de supervisión.
Cuando recibes una notificación sobre un tema, el ID del formulario se incluye en la carga útil de la notificación. Úsalo con el tipo de evento para saber qué datos recuperar y de qué formulario.
Para recuperar datos actualizados después de una notificación con EventType.RESPONSES, llama a forms.responses.list().
- Establece el filtro en la solicitud en timestamp > timestamp_of_the_last_response_you_fetched.
Para recuperar datos actualizados después de una notificación con EventType.SCHEMA, llama a forms.get().