Push-Benachrichtigungen einrichten und erhalten

Mit den Methoden in der Sammlung Watches können Sie Benachrichtigungen erhalten, wenn sich Daten in Formularen ändern. Auf dieser Seite finden Sie einen konzeptionellen Überblick und eine Anleitung zum Einrichten und Empfangen von Push-Benachrichtigungen.

Übersicht

Mit der Funktion für Push-Benachrichtigungen der Google Forms API können Anwendungen Benachrichtigungen abonnieren, wenn sich Daten in Formularen ändern. Benachrichtigungen werden an ein Cloud Pub/Sub-Thema gesendet, in der Regel innerhalb von Minuten nach der Änderung.

Wenn Sie Push-Benachrichtigungen erhalten möchten, müssen Sie ein Cloud Pub/Sub-Thema einrichten und den Namen dieses Themas angeben, wenn Sie einen Watch für den entsprechenden Ereignistyp erstellen.

Im Folgenden finden Sie Definitionen der wichtigsten Konzepte, die in dieser Dokumentation verwendet werden:

• Ein Ziel ist ein Ort, an den Benachrichtigungen gesendet werden. Das einzige unterstützte Ziel ist ein Cloud Pub/Sub-Thema.
• Ein Ereignistyp ist eine Kategorie von Benachrichtigungen, die von einer Drittanbieteranwendung abonniert werden kann.
• Ein Watch ist eine Anweisung an die Forms API, Benachrichtigungen für einen bestimmten Ereignistyp für ein bestimmtes Formular an ein Ziel zu senden.

Wenn Sie eine Überwachung für einen Ereignistyp in einem bestimmten Formular erstellen, erhält das Ziel dieser Überwachung (ein Cloud Pub/Sub-Thema) Benachrichtigungen zu diesen Ereignissen in diesem Formular, bis die Überwachung abläuft. Die Gültigkeit Ihrer Smartwatch-Lizenz beträgt eine Woche. Sie können sie jedoch jederzeit vor Ablauf verlängern, indem Sie eine Anfrage an watches.renew() senden.

Ihr Cloud Pub/Sub-Thema empfängt nur Benachrichtigungen zu Formularen, die Sie mit den von Ihnen angegebenen Anmeldedaten aufrufen können. Wenn der Nutzer beispielsweise die Berechtigung für Ihre Anwendung widerruft oder den Bearbeitungszugriff auf ein beobachtetes Formular verliert, werden keine Benachrichtigungen mehr gesendet.

Verfügbare Ereignistypen

Die Google Forms API bietet derzeit zwei Kategorien von Ereignissen:

• EventType.SCHEMA, die über Änderungen am Inhalt und an den Einstellungen eines Formulars informiert.
• EventType.RESPONSES: Benachrichtigung, wenn Formularantworten (sowohl neue als auch aktualisierte) eingereicht werden.

Antworten auf Benachrichtigungen

Benachrichtigungen werden mit JSON codiert und enthalten Folgendes:

• Die ID des auslösenden Formulars
• Die ID der auslösenden Smartwatch
• Der Ereignistyp, der die Benachrichtigung ausgelöst hat
• Andere von Cloud Pub/Sub festgelegte Felder wie messageId und publishTime

Benachrichtigungen enthalten keine detaillierten Formular- oder Antwortdaten. Nachdem eine Benachrichtigung empfangen wurde, ist ein separater API-Aufruf erforderlich, um aktuelle Daten abzurufen. Empfohlene Verwendung

Das folgende Snippet zeigt eine Beispielbenachrichtigung für eine Schemaänderung:

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

Das folgende Snippet zeigt eine Beispielbenachrichtigung für eine neue Antwort:

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

Cloud Pub/Sub-Thema einrichten

Benachrichtigungen werden an Cloud Pub/Sub-Themen gesendet. Von Cloud Pub/Sub können Sie Benachrichtigungen über einen Webhook oder durch Abrufen eines Abo-Endpunkts empfangen.

So richten Sie ein Cloud Pub/Sub-Thema ein:

1. Erfüllen Sie die Cloud Pub/Sub-Voraussetzungen.
2. Cloud Pub/Sub-Client einrichten
3. Sehen Sie sich die Cloud Pub/Sub-Preise an und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.

4. Sie können ein Cloud Pub/Sub-Thema auf drei Arten erstellen:

   • über die Developer Console (am einfachsten)
   • mit dem Befehlszeilentool (für die einfache programmatische Verwendung) oder
   • über die Cloud Pub/Sub API.
   Hinweis :Cloud Pub/Sub lässt nur eine begrenzte Anzahl von Themen zu. Wenn Sie also ein Thema verwenden, um alle Benachrichtigungen zu empfangen, vermeiden Sie Skalierungsprobleme, falls Ihre Anwendung beliebt wird.

5. Erstellen Sie ein Abo in Cloud Pub/Sub, um Cloud Pub/Sub mitzuteilen, wie Ihre Benachrichtigungen zugestellt werden sollen.

6. Bevor Sie Benachrichtigungen für Ihr Thema erstellen, müssen Sie dem Dienstkonto für Forms-Benachrichtigungen ([e-mail]) die Berechtigung erteilen, in Ihrem Thema zu veröffentlichen.

Smartwatch erstellen

Sobald Sie ein Thema haben, in dem das Dienstkonto für Push-Benachrichtigungen der Forms API veröffentlichen kann, können Sie Benachrichtigungen mit der Methode watches.create() erstellen. Mit dieser Methode wird geprüft, ob das angegebene Cloud Pub/Sub-Thema vom Dienstkonto für Push-Benachrichtigungen erreicht werden kann. Wenn das Thema nicht erreicht werden kann, schlägt die Methode fehl. Das kann beispielsweise der Fall sein, wenn das Thema nicht vorhanden ist oder Sie dem Dienstkonto keine Berechtigung zum Veröffentlichen in diesem Thema erteilt haben.

Python

forms/snippets/create_watch.py

Auf GitHub ansehen

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)

Node.js

forms/snippets/create_watch.js

Auf GitHub ansehen

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Creates a watch on a form to get notifications for new responses.
 */
async function createWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // The request body to create a watch.
  const watchRequest = {
    watch: {
      target: {
        topic: {
          // TODO: Replace with a valid Cloud Pub/Sub topic name.
          topicName: 'projects/<YOUR_TOPIC_PATH>',
        },
      },
      // The event type to watch for. 'RESPONSES' is the only supported type.
      eventType: 'RESPONSES',
    },
  };

  // Send the request to create the watch.
  const result = await formsClient.forms.watches.create({
    formId: formID,
    requestBody: watchRequest,
  });

  console.log(result.data);
  return result.data;
}

Smartwatch löschen

Python

forms/snippets/delete_watch.py

Auf GitHub ansehen

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)

Node.js

forms/snippets/delete_watch.js

Auf GitHub ansehen

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Deletes a watch from a form.
 */
async function deleteWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to delete the watch.
  const result = await formsClient.forms.watches.delete({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

Autorisierung

Wie alle Aufrufe der Forms API müssen Aufrufe von watches.create() mit einem Autorisierungstoken autorisiert werden. Das Token muss einen Bereich enthalten, der Lesezugriff auf die Daten gewährt, zu denen Benachrichtigungen gesendet werden.

• Bei Schemaänderungen bedeutet das, dass jeder Bereich, der Lesezugriff auf Formulare mit forms.get() gewährt, betroffen ist.
• Für Antworten bedeutet das, dass jeder Bereich, der Lesezugriff auf Formularantworten gewährt, z. B. mit forms.responses.list(),

Damit Benachrichtigungen zugestellt werden können, muss die Anwendung eine OAuth-Gewährung vom autorisierten Nutzer mit den erforderlichen Bereichen beibehalten. Wenn der Nutzer die Verbindung zur App trennt, werden keine Benachrichtigungen mehr gesendet und die Smartwatch wird möglicherweise mit einem Fehler angehalten. Informationen dazu, wie Sie Benachrichtigungen wieder aktivieren, nachdem Sie die Autorisierung wiedererlangt haben, finden Sie unter Smartwatch erneuern.

Beobachtungen eines Formulars auflisten

Python

forms/snippets/list_watches.py

Auf GitHub ansehen

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)

Node.js

forms/snippets/list_watches.js

Auf GitHub ansehen

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Lists the watches for a given form.
 */
async function listWatches() {
  // Authenticate with Google and get an authorized client.
  const auth = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/forms.responses.readonly',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth,
  });

  // Get the list of watches for the form.
  const result = await formsClient.forms.watches.list({
    formId: formID,
  });

  console.log(result.data);
  return result.data;
}

Smartwatch erneuern

Python

forms/snippets/renew_watch.py

Auf GitHub ansehen

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)

Node.js

forms/snippets/renew_watch.js

Auf GitHub ansehen

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Renews a watch on a form.
 */
async function renewWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to renew the watch.
  const result = await formsClient.forms.watches.renew({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

Drosselung

Benachrichtigungen werden gedrosselt. Jede Smartwatch kann höchstens alle 30 Sekunden eine Benachrichtigung empfangen. Dieser Schwellenwert für die Häufigkeit kann sich ändern.

Aufgrund der Drosselung kann eine einzelne Benachrichtigung mehreren Ereignissen entsprechen. Eine Benachrichtigung bedeutet also, dass seit der letzten Benachrichtigung ein oder mehrere Ereignisse eingetreten sind.

Limits

Für ein bestimmtes Formular und einen bestimmten Ereignistyp kann jedes Cloud Console-Projekt jederzeit Folgendes haben:

• Bis zu 20 Smartwatches insgesamt
• bis zu einer Smartwatch pro Endnutzer

Außerdem ist jedes Formular jederzeit auf insgesamt 50 Beobachtungen pro Ereignistyp in allen Cloud Console-Projekten beschränkt.

Eine Smartwatch wird einem Endnutzer zugeordnet, wenn sie mit den Anmeldedaten dieses Nutzers erstellt oder verlängert wird. Eine Smartwatch wird gesperrt, wenn der zugehörige Endnutzer den Zugriff auf das Formular verliert oder den Zugriff der App auf das Formular widerruft.

Zuverlässigkeit

Jede Smartwatch wird nach jedem Ereignis mindestens einmal benachrichtigt, außer unter außergewöhnlichen Umständen. In den meisten Fällen wird eine Benachrichtigung innerhalb weniger Minuten nach einem Ereignis zugestellt.

Fehler

Wenn Benachrichtigungen für eine Smartwatch wiederholt nicht zugestellt werden können, ändert sich der Status der Smartwatch zu SUSPENDED und das Feld errorType der Smartwatch wird festgelegt. Informationen zum Zurücksetzen des Status einer gesperrten Smartwatch auf ACTIVE und zum Fortsetzen von Benachrichtigungen finden Sie unter Smartwatch erneuern.

Empfohlene Verwendung

• Verwenden Sie ein einzelnes Cloud Pub/Sub-Thema als Ziel für viele Beobachtungen.
• Wenn Sie eine Benachrichtigung zu einem Thema erhalten, ist die Formular-ID in der Benachrichtigungsnutzlast enthalten. Damit lässt sich in Kombination mit dem Ereignistyp ermitteln, welche Daten abgerufen werden müssen und aus welchem Formular sie abgerufen werden.
• Wenn Sie nach einer Benachrichtigung mit EventType.RESPONSES aktualisierte Daten abrufen möchten, rufen Sie forms.responses.list() auf.
  • Legen Sie den Filter für die Anfrage auf timestamp > timestamp_of_the_last_response_you_fetched fest.
• Wenn Sie nach einer Benachrichtigung mit EventType.SCHEMA aktualisierte Daten abrufen möchten, rufen Sie forms.get() auf.