Cette page a été traduite par l'API Cloud Translation.

Configurer et recevoir des notifications push

Vous pouvez utiliser les méthodes de la collection Watches pour recevoir des notifications lorsque les données changent dans les formulaires. Cette page présente une présentation conceptuelle et des instructions pour configurer et recevoir des notifications push.

Présentation

La fonctionnalité de notifications push de l'API Google Forms permet aux applications de s'abonner aux notifications lorsque les données des formulaires changent. Les notifications sont envoyées à un sujet Cloud Pub/Sub, généralement dans les minutes qui suivent la modification.

Pour recevoir des notifications push, vous devez configurer un sujet Cloud Pub/Sub et indiquer son nom lorsque vous créez une surveillance pour le type d'événement approprié.

Vous trouverez ci-dessous les définitions des concepts clés utilisés dans cette documentation:

Une cible est un emplacement où des notifications sont envoyées. La seule cible acceptée est un sujet Cloud Pub/Sub.
Un type d'événement est une catégorie de notifications auxquelles une application tierce peut s'abonner.
Une surveillance est une instruction envoyée à l'API Forms pour envoyer des notifications pour un type d'événement particulier sur un formulaire particulier à une cible.

Une fois que vous avez créé une surveillance pour un type d'événement sur un formulaire particulier, la cible de cette surveillance (qui est un sujet Cloud Pub/Sub) reçoit des notifications de ces événements sur ce formulaire jusqu'à l'expiration de la surveillance. Votre montre dure une semaine, mais vous pouvez la prolonger à tout moment avant son expiration en envoyant une requête à watches.renew().

Votre sujet Cloud Pub/Sub ne reçoit que des notifications concernant les formulaires que vous pouvez afficher avec les identifiants que vous fournissez. Par exemple, si l'utilisateur révoque l'autorisation de votre application ou perd l'accès en modification à un formulaire surveillé, les notifications ne sont plus envoyées.

Types d'événements disponibles

L'API Google Forms propose actuellement deux catégories d'événements:

EventType.SCHEMA, qui envoie des notifications concernant les modifications apportées au contenu et aux paramètres d'un formulaire.
EventType.RESPONSES, qui envoie une notification lorsque des réponses au formulaire (nouvelles et mises à jour) sont envoyées.

Réponses aux notifications

Les notifications sont encodées en JSON et contiennent les éléments suivants:

ID du formulaire déclencheur
ID de la montre déclencheur
Type d'événement ayant déclenché la notification
Autres champs définis par Cloud Pub/Sub, tels que messageId et publishTime

Les notifications ne contiennent pas de données détaillées sur les formulaires ou les réponses. Une fois chaque notification reçue, un appel d'API distinct est nécessaire pour récupérer des données fraîches. Pour savoir comment procéder, consultez la section Utilisation suggérée.

L'extrait de code suivant présente un exemple de notification pour une modification de schéma:

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

L'extrait de code suivant illustre un exemple de notification pour une nouvelle réponse:

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

Configurer un sujet Cloud Pub/Sub

Les notifications sont envoyées aux sujets Cloud Pub/Sub. À partir de Cloud Pub/Sub, vous pouvez recevoir des notifications sur un webhook ou en interrogeant un point de terminaison d'abonnement.

Pour configurer un sujet Cloud Pub/Sub, procédez comme suit:

Remplissez les conditions préalables à Cloud Pub/Sub.
Configurez un client Cloud Pub/Sub.
Consultez les tarifs de Cloud Pub/Sub et activez la facturation pour votre projet dans la console du développeur.
Vous pouvez créer un sujet Cloud Pub/Sub de trois manières:
- à l'aide de la console du développeur (la méthode la plus simple) ;
- à l'aide de l'outil de ligne de commande (pour une utilisation programmatique simple) ou
- à l'aide de l'API Cloud Pub/Sub.
Remarque :Cloud Pub/Sub n'autorise qu'un nombre limité de sujets. Par conséquent, utiliser un seul sujet pour recevoir toutes vos notifications vous permet d'éviter les problèmes de mise à l'échelle si votre application devient populaire.
Créez un abonnement dans Cloud Pub/Sub pour indiquer à Cloud Pub/Sub comment diffuser vos notifications.
Enfin, avant de créer des veilles qui ciblent votre sujet, vous devez autoriser le compte de service des notifications Forms (forms-notifications@system.gserviceaccount.com) à publier sur votre sujet.

Créer une montre

Une fois que vous avez un sujet sur lequel le compte de service des notifications push de l'API Forms peut publier, vous pouvez créer des notifications à l'aide de la méthode watches.create(). Cette méthode vérifie que le sujet Cloud Pub/Sub fourni peut être atteint par le compte de service de notifications push et échoue s'il ne peut pas l'atteindre (par exemple, si le sujet n'existe pas ou si vous ne lui avez pas accordé l'autorisation de publication sur ce sujet).

PythonNode.js

forms/snippets/create_watch.py

Afficher sur 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

Afficher sur 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;

Supprimer une montre

PythonNode.js

forms/snippets/delete_watch.py

Afficher sur 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

Afficher sur 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;

Autorisation

Comme tous les appels à l'API Forms, les appels à watches.create() doivent être autorisés à l'aide d'un jeton d'autorisation. Le jeton doit inclure un champ d'application qui accorde un accès en lecture aux données sur les notifications envoyées.

Pour les modifications de schéma, il s'agit de toute portée qui accorde un accès en lecture aux formulaires à l'aide de forms.get().
Pour les réponses, il s'agit de toute portée qui accorde un accès en lecture aux réponses aux formulaires, par exemple à l'aide de forms.responses.list().

Pour que les notifications soient envoyées, l'application doit conserver une autorisation OAuth de l'utilisateur autorisé avec les champs d'application requis. Si l'utilisateur dissocie l'application, les notifications cessent et la montre peut être suspendue avec une erreur. Pour reprendre les notifications après avoir récupéré l'autorisation, consultez la section Renouveler une montre.

Lister les montres d'un formulaire

PythonNode.js

forms/snippets/list_watches.py

Afficher sur 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

Afficher sur 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;

Renouveler une montre

PythonNode.js

forms/snippets/renew_watch.py

Afficher sur 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

Afficher sur 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;

Limitations

Les notifications sont limitées : chaque montre ne peut recevoir qu'une notification toutes les 30 secondes. Ce seuil de fréquence est susceptible d'être modifié.

En raison du débit limité, une seule notification peut correspondre à plusieurs événements. En d'autres termes, une notification indique qu'un ou plusieurs événements se sont produits depuis la dernière notification.

Limites

À tout moment, pour un formulaire et un type d'événement donnés, chaque projet Cloud Console peut avoir:

jusqu'à 20 visionnages au total
une montre par utilisateur final ;

De plus, chaque formulaire est limité à 50 surveillances par type d'événement au total pour tous les projets de la console Cloud.

Une montre est associée à un utilisateur final lorsqu'elle est créée ou renouvelée avec les identifiants de cet utilisateur. Une montre est suspendue si l'utilisateur final associé perd l'accès au formulaire ou révoque l'accès de l'application au formulaire.

Fiabilité

Chaque montre reçoit une notification au moins une fois après chaque événement, sauf dans des circonstances exceptionnelles. Dans la grande majorité des cas, une notification est envoyée dans les minutes qui suivent un événement.

Erreurs

Si les notifications d'une montre ne sont pas toujours distribuées, son état devient SUSPENDED et son champ errorType est défini. Pour réinitialiser l'état d'une montre suspendue sur ACTIVE et reprendre les notifications, consultez la section Renouveler une montre.

Utilisation suggérée

Utilisez un seul sujet Cloud Pub/Sub comme cible de plusieurs surveillances.
Lorsque vous recevez une notification sur un sujet, l'ID de formulaire est inclus dans la charge utile de la notification. Utilisez-le avec le type d'événement pour savoir quelles données extraire et de quel formulaire.
Pour récupérer les données mises à jour après une notification avec EventType.RESPONSES, appelez forms.responses.list().
- Définissez le filtre de la requête sur timestamp > timestamp_of_the_last_response_you_fetched.
Pour extraire les données mises à jour après une notification avec EventType.SCHEMA, appelez forms.get().