Diese Seite wurde von der Cloud Translation API übersetzt.

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 allgemeinen Überblick und eine Anleitung zum Einrichten und Empfangen von Push-Benachrichtigungen.

Übersicht

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

Wenn Sie Push-Benachrichtigungen erhalten möchten, müssen Sie ein Cloud Pub/Sub-Thema einrichten und den Namen dieses Themas angeben, wenn Sie eine Beobachtung 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 Drittanbieter-App abonniert werden kann.
Eine Beobachtung ist eine Anweisung an die Forms API, Benachrichtigungen für einen bestimmten Ereignistyp in einem bestimmten Formular an ein Ziel zu senden.

Wenn Sie eine Beobachtung für einen Ereignistyp in einem bestimmten Formular erstellen, erhält das Ziel dieser Beobachtung (ein Cloud Pub/Sub-Thema) Benachrichtigungen von diesen Ereignissen in diesem Formular, bis die Beobachtung abläuft. Die Smartwatch hält eine Woche lang, kann aber jederzeit vor Ablauf verlängert werden. Dazu musst du eine watches.renew()-Anfrage senden.

Ihr Cloud Pub/Sub-Thema erhält 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 Ereigniskategorien:

EventType.SCHEMA, über die Sie benachrichtigt werden, wenn Inhalte und Einstellungen eines Formulars geändert werden.
EventType.RESPONSES, über die Sie benachrichtigt werden, wenn Formularantworten (sowohl neue als auch aktualisierte) gesendet werden.

Antworten auf Benachrichtigungen

Benachrichtigungen sind 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, z. B. messageId und publishTime

Benachrichtigungen enthalten keine detaillierten Formular- oder Antwortdaten. Nach jeder Benachrichtigung ist ein separater API-Aufruf erforderlich, um aktuelle Daten abzurufen. Weitere Informationen dazu finden Sie unter 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. Über Cloud Pub/Sub können Sie Benachrichtigungen über einen Webhook oder durch Abfragen eines Aboendpunkts empfangen.

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

Sie haben die Voraussetzungen für Cloud Pub/Sub erfüllt.
Richte einen Cloud Pub/Sub-Client ein.
Sehen Sie sich die Preise für Cloud Pub/Sub an und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.
Sie haben drei Möglichkeiten, ein Cloud Pub/Sub-Thema zu erstellen:
- über die Developer Console (am einfachsten)
- mit dem Befehlszeilentool (für die einfache programmatische Verwendung) oder
- mit der Cloud Pub/Sub API
Hinweis :Cloud Pub/Sub erlaubt nur eine begrenzte Anzahl von Themen. Wenn Sie also ein Thema verwenden, um alle Benachrichtigungen zu erhalten, können Sie Skalierungsprobleme vermeiden, wenn Ihre Anwendung populär wird.
Erstellen Sie ein Abo in Cloud Pub/Sub, um Cloud Pub/Sub mitzuteilen, wie Ihre Benachrichtigungen zugestellt werden sollen.
Bevor Sie Benachrichtigungen für Ihr Thema erstellen, müssen Sie dem Dienstkonto für Benachrichtigungen in Google Forms (forms-notifications@system.gserviceaccount.com) die Berechtigung zum Veröffentlichen in Ihrem Thema erteilen.

Smartwatch erstellen

Sobald Sie ein Thema haben, in dem das Dienstkonto für Push-Benachrichtigungen der Google Forms API veröffentlichen kann, können Sie mit der Methode watches.create() Benachrichtigungen erstellen. Mit dieser Methode wird geprüft, ob das angegebene Cloud Pub/Sub-Thema vom Dienstkonto für Push-Benachrichtigungen erreicht werden kann. Andernfalls schlägt die Prüfung fehl, z. B. wenn das Thema nicht existiert oder Sie ihm keine Veröffentlichungsberechtigung für das Thema erteilt haben.

PythonNode.js

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)

forms/snippets/create_watch.js

Auf GitHub ansehen

'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;

Smartwatch löschen

PythonNode.js

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)

forms/snippets/delete_watch.js

Auf GitHub ansehen

'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;

Autorisierung

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

Bei Schemaänderungen bedeutet das jeden Umfang, der Lesezugriff auf Formulare über forms.get() gewährt.
Bei Antworten bedeutet das jeden Umfang, der Lesezugriff auf Antworten auf Formulare gewährt, z. B. mit forms.responses.list().

Damit Benachrichtigungen gesendet werden können, muss die Anwendung eine OAuth-Berechtigung des autorisierten Nutzers mit den erforderlichen Bereichen haben. Wenn der Nutzer die Verbindung zur App trennt, werden keine Benachrichtigungen mehr gesendet und die Smartwatch wird möglicherweise mit einem Fehler beendet. Wie Sie Benachrichtigungen fortsetzen, nachdem Sie die Autorisierung wiedererlangt haben, erfahren Sie unter Smartwatch erneuern.

Smartwatches eines Formulars auflisten

PythonNode.js

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)

forms/snippets/list_watches.js

Auf GitHub ansehen

'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;

Smartwatch verlängern

PythonNode.js

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)

forms/snippets/renew_watch.js

Auf GitHub ansehen

'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;

Drosselung

Die Anzahl der Benachrichtigungen wird begrenzt: Jede Smartwatch kann alle 30 Sekunden maximal eine Benachrichtigung erhalten. Dieser Grenzwert kann sich ändern.

Aufgrund der Drosselung kann eine einzelne Benachrichtigung mehreren Ereignissen entsprechen. Mit anderen Worten: Eine Benachrichtigung gibt an, 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 Uhren insgesamt
bis zu eine Smartwatch pro Endnutzer

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

Eine Smartwatch wird mit einem Endnutzer verknüpft, wenn sie mit Anmeldedaten für diesen Nutzer erstellt oder verlängert wird. Eine Beobachtung wird ausgesetzt, wenn der zugehörige Endnutzer den Zugriff auf das Formular verliert oder den Zugriff der App auf das Formular widerruft.

Zuverlässigkeit

Außer bei außergewöhnlichen Umständen wird jede Smartwatch nach jedem Ereignis mindestens einmal benachrichtigt. In den allermeisten Fällen wird eine Benachrichtigung innerhalb weniger Minuten nach einem Ereignis gesendet.

Fehler

Wenn Benachrichtigungen für eine Smartwatch wiederholt nicht zugestellt werden können, ändert sich der Smartwatch-Status in SUSPENDED und das Feld errorType der Smartwatch wird festgelegt. Wie Sie den Status einer angehaltenen Smartwatch auf ACTIVE zurücksetzen und Benachrichtigungen fortsetzen, erfahren Sie unter Smartwatch erneuern.

Empfohlene Verwendung

Verwenden Sie ein einzelnes Cloud Pub/Sub-Thema als Ziel vieler Beobachtungen.
Wenn Sie eine Benachrichtigung zu einem Thema erhalten, ist die Formular-ID in der Benachrichtigungsnutzlast enthalten. Verwenden Sie ihn zusammen mit dem Ereignistyp, um zu erfahren, welche Daten abgerufen werden sollen und aus welchem Formular.
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.