Esta página foi traduzida pela API Cloud Translation.

Configurar e receber notificações push

É possível usar os métodos na coleção Watches para receber notificações quando os dados mudarem nos formulários. Esta página oferece uma visão geral conceitual e instruções para configurar e receber notificações push.

Visão geral

O recurso de notificações push da API Google Forms permite que os aplicativos se inscrevam em notificações quando os dados mudarem nos formulários. As notificações são enviadas para um tópico do Cloud Pub/Sub, geralmente em minutos após a alteração.

Para receber notificações push, configure um tópico do Cloud Pub/Sub e informe o nome dele ao criar uma observação para o tipo de evento adequado.

Confira abaixo as definições dos principais conceitos usados nesta documentação:

Um destino é um lugar para onde as notificações são enviadas. O único destino aceito é um tópico do Cloud Pub/Sub.
Um tipo de evento é uma categoria de notificações em que um aplicativo de terceiros pode se inscrever.
Um watch é uma instrução para a API Forms enviar notificações para um tipo de evento específico em um formulário específico para um destino.

Depois de criar uma observação para um tipo de evento em um formulário específico, o destino dessa observação (que é um tópico do Cloud Pub/Sub) recebe notificações desses eventos no formulário até que a observação expire. O relógio dura uma semana, mas você pode estender esse período a qualquer momento antes do vencimento fazendo uma solicitação para watches.renew().

Seu tópico do Cloud Pub/Sub só recebe notificações sobre formulários que você pode visualizar com as credenciais fornecidas. Por exemplo, se o usuário revogar a permissão do seu app ou perder o acesso de edição a um formulário assistido, as notificações não serão mais enviadas.

Tipos de evento disponíveis

No momento, a API Google Forms oferece duas categorias de eventos:

EventType.SCHEMA, que notifica sobre edições no conteúdo e nas configurações de um formulário.
EventType.RESPONSES, que notifica quando as respostas do formulário (novas e atualizadas) são enviadas.

Respostas de notificação

As notificações são codificadas com JSON e contêm:

O ID do formulário acionado
O ID do relógio que acionou o erro
O tipo de evento que acionou a notificação
Outros campos definidos pelo Cloud Pub/Sub, como messageId e publishTime

As notificações não contêm dados detalhados de formulário ou resposta. Depois que cada notificação é recebida, uma chamada de API separada é necessária para buscar dados novos. Consulte Uso sugerido para saber como fazer isso.

O snippet a seguir demonstra um exemplo de notificação para uma mudança de esquema:

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

O snippet a seguir demonstra um exemplo de notificação para uma nova resposta:

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

Configurar um tópico do Cloud Pub/Sub

As notificações são enviadas para os tópicos do Cloud Pub/Sub. No Cloud Pub/Sub, você pode receber notificações em um webhook ou pesquisando um endpoint de assinatura.

Para configurar um tópico do Cloud Pub/Sub, faça o seguinte:

Conclua os Pré-requisitos do Cloud Pub/Sub.
Configure um cliente do Cloud Pub/Sub.
Consulte os preços do Pub/Sub do Cloud e ative o faturamento no seu projeto do console do desenvolvedor.
Crie um tópico do Cloud Pub/Sub de três maneiras:
- usando o console para desenvolvedores (mais fácil)
- usando a ferramenta de linha de comando (para uso programático simples) ou
- usando a API Cloud Pub/Sub.
Observação: o Cloud Pub/Sub permite apenas um número limitado de tópicos. Portanto, use um tópico para receber todas as notificações e evitar problemas de escalonamento se o aplicativo se tornar popular.
Crie uma assinatura no Cloud Pub/Sub para informar ao Cloud Pub/Sub como entregar suas notificações.
Por fim, antes de criar visualizações que segmentam seu tópico, é necessário conceder permissão à conta de serviço de notificações do Forms (forms-notifications@system.gserviceaccount.com) para publicar no tópico.

Criar um relógio

Depois de ter um tópico em que a conta de serviço de notificações por push da API Forms possa publicar, você poderá criar notificações usando o método watches.create(). Esse método valida se o tópico do Cloud Pub/Sub fornecido pode ser acessado pela conta de serviço de notificações push e falha se não puder acessar o tópico. Por exemplo, se o tópico não existir ou se você não tiver concedido a ele permissão de publicação.

PythonNode.js

forms/snippets/create_watch.py

Ver no 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 no 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;

Excluir um relógio

PythonNode.js

forms/snippets/delete_watch.py

Ver no 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 no 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;

Autorização

Como todas as chamadas para a API Forms, as chamadas para watches.create() precisam ser autorizadas com um token de autorização. O token precisa incluir um escopo que conceda acesso de leitura aos dados sobre quais notificações estão sendo enviadas.

Para mudanças de esquema, isso significa qualquer escopo que conceda acesso de leitura a forms usando forms.get().
Para respostas, isso significa qualquer escopo que conceda acesso de leitura a respostas de formulário, por exemplo, usando forms.responses.list().

Para que as notificações sejam enviadas, o app precisa reter uma concessão OAuth do usuário autorizado com os escopos necessários. Se o usuário desconectar o app, as notificações serão interrompidas, e o relógio poderá ser suspenso com um erro. Para retomar as notificações depois de recuperar a autorização, consulte Renovar um relógio.

Listar os relógios de um formulário

PythonNode.js

forms/snippets/list_watches.py

Ver no 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 no 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;

Renovar um relógio

PythonNode.js

forms/snippets/renew_watch.py

Ver no 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 no 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;

Limitação

As notificações são limitadas. Cada relógio pode receber no máximo uma notificação a cada 30 segundos. Esse limite de frequência está sujeito a mudanças.

Devido ao controle de taxa, uma única notificação pode corresponder a vários eventos. Em outras palavras, uma notificação indica que um ou mais eventos ocorreram desde a última notificação.

Limites

A qualquer momento, para um determinado formulário e tipo de evento, cada projeto do Console do Cloud pode ter:

até 20 visualizações no total
até um relógio por usuário final

Além disso, a qualquer momento, cada formulário é limitado a 50 visualizações por tipo de evento no total em todos os projetos do Console do Cloud.

Um relógio é associado a um usuário final quando é criado ou renovado com as credenciais desse usuário. Um relógio é suspenso se o usuário final associado perder o acesso ao formulário ou revogar o acesso do app ao formulário.

Confiabilidade

Cada relógio é notificado pelo menos uma vez após cada evento, exceto em circunstâncias extraordinárias. Na grande maioria dos casos, uma notificação é enviada minutos após um evento.

Erros

Se as notificações de um relógio falharem constantemente, o estado do relógio passará a ser SUSPENDED e o campo errorType do relógio será definido. Para redefinir o estado de um relógio suspenso para ACTIVE e retomar as notificações, consulte Renovar um relógio.

Uso sugerido

Use um único tópico do Cloud Pub/Sub como destino de muitos monitoramentos.
Ao receber uma notificação sobre um tópico, o ID do formulário é incluído no payload da notificação. Use-o com o tipo de evento para saber quais dados buscar e de qual formulário.
Para buscar dados atualizados após uma notificação com EventType.RESPONSES, chame forms.responses.list().
- Defina o filtro na solicitação como timestamp > timestamp_of_the_last_response_you_fetched.
Para buscar dados atualizados após uma notificação com EventType.SCHEMA, chame forms.get().