Diese Seite wurde von der Cloud Translation API übersetzt.

Push-Benachrichtigungen einrichten und erhalten

Sie können die Methoden in der Watches-Sammlung verwenden, um Benachrichtigungen zu erhalten, wenn Daten in Formularen geändert werden. Diese Seite bietet eine konzeptionelle Übersicht und eine Anleitung zum Einrichten und Empfangen von Push-Benachrichtigungen.

Überblick

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

Um Push-Benachrichtigungen zu erhalten, müssen Sie ein Cloud Pub/Sub-Thema einrichten und den Namen dieses Themas angeben, wenn Sie eine Uhr für den entsprechenden Ereignistyp erstellen.

Im Folgenden finden Sie Definitionen der in dieser Dokumentation verwendeten Schlüsselkonzepte:

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 eine Drittanbieter-App abonnieren kann.
Eine Watch ist eine Anweisung an die Formulare API, Benachrichtigungen für einen bestimmten Ereignistyp in einem bestimmten Formular an ein Ziel zu senden.

Wenn Sie eine Überwachung für einen Ereignistyp in einem bestimmten Formular erstellen, erhält das Ziel dieser Uhr (bei dem es sich um ein Cloud Pub/Sub-Thema handelt) Benachrichtigungen von diesen Ereignissen in diesem Formular, bis die Uhr abläuft. Ihre Smartwatch hält eine Woche. Sie können sie jedoch jederzeit verlängern, bevor sie abläuft. Stellen Sie dazu eine Anfrage an watches.renew().

Ihr Cloud Pub/Sub-Thema erhält nur Benachrichtigungen zu Formularen, die Sie mit den von Ihnen angegebenen Anmeldedaten ansehen können. Wenn der Nutzer beispielsweise Ihrer Anwendung die Berechtigung widerruft oder den Bearbeitungszugriff auf ein überwachtes Formular verliert, werden keine Benachrichtigungen mehr gesendet.

Verfügbare Ereignistypen

Die Google Formulare API bietet derzeit zwei Ereigniskategorien:

EventType.SCHEMA: Benachrichtigt Sie über Änderungen am Inhalt und an den Einstellungen eines Formulars.
EventType.RESPONSES: Benachrichtigt dich, wenn Formularantworten (neue und aktualisierte) gesendet werden.

Antworten auf Benachrichtigungen

Benachrichtigungen sind mit JSON codiert und enthalten:

Die ID des auslösenden Formulars
ID der auslösenden Uhr
Der Typ des Ereignisses, das die Benachrichtigung ausgelöst hat
Andere Felder, die von Cloud Pub/Sub festgelegt werden, z. B. messageId und publishTime

Benachrichtigungen enthalten keine detaillierten Formular- oder Antwortdaten. Nach dem Empfang jeder Benachrichtigung ist ein separater API-Aufruf erforderlich, um aktuelle Daten abzurufen. 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 erhalten.

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

Sie müssen die Cloud Pub/Sub-Voraussetzungen erfüllen.
Cloud Pub/Sub-Client einrichten
Prüfen Sie die Cloud Pub/Sub-Preise 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 (einfachste Methode)
- mit dem Befehlszeilentool (für die einfache programmatische Verwendung) oder
- mithilfe der Cloud Pub/Sub API.
Hinweis: Cloud Pub/Sub lässt nur eine begrenzte Anzahl von Themen zu. Wenn Sie also ein Thema für alle Benachrichtigungen verwenden, vermeiden Sie Skalierungsprobleme, wenn Ihre Anwendung beliebt wird.
Erstellen Sie in Cloud Pub/Sub ein Abo, um Cloud Pub/Sub mitzuteilen, wie Ihre Benachrichtigungen gesendet werden sollen.
Bevor Sie Smartwatches erstellen, die auf Ihr Thema ausgerichtet sind, müssen Sie dem Dienstkonto für Formularbenachrichtigungen (forms-notifications@system.gserviceaccount.com) die Berechtigung erteilen, in Ihrem Thema zu veröffentlichen.

Smartwatch erstellen

Sobald Sie ein Thema haben, für das das Dienstkonto für Push-Benachrichtigungen der Formulare API Veröffentlichungen vornehmen kann, können Sie Benachrichtigungen mit der Methode watches.create() erstellen. Diese Methode validiert, dass das bereitgestellte Cloud Pub/Sub-Thema vom Dienstkonto für Push-Benachrichtigungen erreicht werden kann. Sie schlägt fehl, wenn das Thema nicht erreicht werden kann, z. B. wenn das Thema nicht existiert oder Sie ihm keine Veröffentlichungsberechtigung für dieses 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

'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

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

Formulare/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 Formulare API müssen auch watches.create()-Aufrufe mit einem Autorisierungstoken autorisiert werden. Das Token muss einen Bereich enthalten, der Lesezugriff auf die Daten gewährt, über die Benachrichtigungen gesendet werden.

Bei Schemaänderungen bedeutet dies jeder Bereich, der Lesezugriff auf Formulare über forms.get() gewährt.
Bei Antworten ist dies jeder Bereich, der Lesezugriff auf Formularantworten gewährt, z. B. über forms.responses.list().

Damit Benachrichtigungen gesendet werden können, muss die Anwendung eine OAuth-Zustimmung des autorisierten Nutzers mit den erforderlichen Bereichen beibehalten. Wenn der Nutzer die App trennt, werden keine Benachrichtigungen mehr angezeigt und die Uhr wird möglicherweise mit einem Fehler gesperrt. Wie du Benachrichtigungen erhältst, nachdem du die Autorisierung wiederhergestellt hast, erfährst du unter Smartwatch verlängern.

Smartwatches 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

Formulare/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

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

Formulare/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

Benachrichtigungen sind gedrosselt. Jede Uhr kann höchstens eine Benachrichtigung alle 30 Sekunden erhalten. Dieser Grenzwert kann sich ändern.

Aufgrund der Drosselung kann eine einzelne Benachrichtigung mehreren Ereignissen entsprechen. Mit anderen Worten: Eine Benachrichtigung zeigt an, dass ein oder mehrere Ereignisse seit der letzten Benachrichtigung aufgetreten sind.

Einschränkungen

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

bis zu 20 Wiedergaben insgesamt
Bis zu eine Smartwatch pro Endnutzer

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

Eine Smartwatch wird einem Endnutzer zugeordnet, wenn sie mit Anmeldedaten für diesen Nutzer 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 Uhr wird nach jedem Ereignis mindestens einmal in allen außer außergewöhnlichen Umständen benachrichtigt. In den meisten Fällen wird eine Benachrichtigung innerhalb weniger Minuten nach einem Ereignis zugestellt.

Fehler

Wenn Benachrichtigungen für eine Uhr dauerhaft nicht zugestellt werden, wechselt der Überwachungsstatus zu SUSPENDED und das Feld errorType der Uhr wird festgelegt. Informationen zum Zurücksetzen des Status einer gesperrten Smartwatch auf ACTIVE und zum Fortsetzen der Benachrichtigungen findest du unter Smartwatch verlängern.

Empfohlene Verwendung

Verwenden Sie ein einzelnes Cloud Pub/Sub-Thema als Ziel vieler Smartwatches.
Beim Empfang einer Benachrichtigung zu einem Thema wird die Formular-ID in die Benachrichtigungsnutzlast eingefügt. Verwenden Sie dieses Attribut zusammen mit dem Ereignistyp, um zu erfahren, welche Daten abgerufen werden sollen und von welchem Formular sie abgerufen werden sollen.
Wenn Sie nach einer Benachrichtigung mit EventType.RESPONSES aktualisierte Daten abrufen möchten, rufen Sie forms.responses.list() auf.
- Legen Sie den Filter in der 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.