Чтобы предоставить создателям форм больше контроля над тем, кто может отвечать, мы вводим детальные настройки для респондентов. Формы, созданные с помощью API после 31 марта 2026 года, по умолчанию будут иметь статус «не опубликовано». Подробнее см. в разделе «Изменения API в Google Forms» .

Эта страница переведена с помощью Cloud Translation API.

Настройте и получайте push-уведомления

Вы можете использовать методы из коллекции Watches для получения уведомлений об изменении данных в формах. На этой странице представлен общий обзор и инструкции по настройке и получению push-уведомлений.

Обзор

Функция push-уведомлений API Google Forms позволяет приложениям подписываться на уведомления об изменении данных в формах. Уведомления доставляются в топик Cloud Pub/Sub , как правило, в течение нескольких минут после изменения.

Для получения push-уведомлений необходимо настроить тему Cloud Pub/Sub и указать её имя при создании отслеживания для соответствующего типа событий.

Ниже приведены определения ключевых понятий, используемых в данной документации:

Цель — это место, куда отправляются уведомления. Единственной поддерживаемой целью является тема Cloud Pub/Sub.
Тип события — это категория уведомлений, на которые может подписаться стороннее приложение.
« Отслеживание» — это инструкция для API форм, указывающая на необходимость отправки уведомлений о событии определенного типа в определенной форме целевому объекту .

После создания наблюдения за определенным типом события в конкретной форме, целевой объект этого наблюдения (который является темой Cloud Pub/Sub) будет получать уведомления об этих событиях в данной форме до истечения срока действия наблюдения. Срок действия наблюдения составляет неделю, но вы можете продлить его в любой момент до истечения срока действия, отправив запрос на watches.renew() .

В вашу тему Cloud Pub/Sub поступают уведомления только о формах, которые вы можете просматривать с помощью предоставленных вами учетных данных. Например, если пользователь отзывает разрешение у вашего приложения или теряет доступ к редактированию отслеживаемой формы, уведомления больше не будут доставляться.

Доступные типы событий

В настоящее время API Google Forms предлагает две категории событий:

EventType.SCHEMA — это событие, уведомляющее об изменениях содержимого и настроек формы.
EventType.RESPONSES это событие, которое уведомляет о том, когда были отправлены ответы на форму (как новые, так и обновленные).

Ответы на уведомления

Уведомления закодированы в формате JSON и содержат:

Идентификатор формы, запускающей процесс
Идентификатор запускающих часов
Тип события, вызвавшего уведомление.
Другие поля, устанавливаемые Cloud Pub/Sub, такие как messageId и publishTime

Уведомления не содержат подробных данных формы или ответа. После получения каждого уведомления требуется отдельный вызов API для получения актуальных данных. См. раздел «Рекомендуемое использование» для получения информации о том, как это сделать.

Следующий фрагмент кода демонстрирует пример уведомления об изменении схемы:

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

Следующий фрагмент кода демонстрирует пример уведомления о новом ответе:

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

Настройте тему Cloud Pub/Sub.

Уведомления доставляются в темы Cloud Pub/Sub. Из Cloud Pub/Sub вы можете получать уведомления через веб-перехватчик или путем опроса конечной точки подписки.

Для настройки темы Cloud Pub/Sub выполните следующие действия:

Выполните необходимые предварительные условия для работы с Cloud Pub/Sub .
Настройте клиент Cloud Pub/Sub .
Ознакомьтесь с ценами Cloud Pub/Sub и включите выставление счетов для вашего проекта в консоли Google Cloud.
Создать тему Cloud Pub/Sub можно одним из трех способов:
- используя консоль Google Cloud
- используя инструмент командной строки (для простого программного использования) или
- используя API Cloud Pub/Sub .
Примечание: Cloud Pub/Sub позволяет использовать только ограниченное количество тем , поэтому использование одной темы для получения всех уведомлений гарантирует отсутствие проблем с масштабированием, если ваше приложение станет популярным.
Создайте подписку в Cloud Pub/Sub , чтобы указать Cloud Pub/Sub, как доставлять ваши уведомления.
Наконец, прежде чем создавать уведомления, нацеленные на вашу тему, необходимо предоставить учетной записи службы уведомлений Forms (forms-notifications@system.gserviceaccount.com) разрешение на публикацию уведомлений в вашей теме.

Создать часы

После того как вы выбрали тему, в которую может публиковать данные учетная запись службы push-уведомлений Forms API, вы можете создавать уведомления, используя метод watches.create() . Этот метод проверяет, доступна ли предоставленная тема Cloud Pub/Sub для учетной записи службы push-уведомлений, и завершается с ошибкой, если доступ к теме невозможен; например, если тема не существует или вы не предоставили ей разрешение на публикацию в этой теме.

Python

forms/nippets/create_watch.py

Посмотреть на 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)

Node.js

forms/snippets/create_watch.js

Посмотреть на GitHub

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

Удалить часы

Python

forms/snippets/delete_watch.py

Посмотреть на 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)

Node.js

forms/snippets/delete_watch.js

Посмотреть на GitHub

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

Авторизация

Как и все вызовы к API форм, вызовы watches.create() должны быть авторизованы с помощью токена авторизации. Токен должен включать область действия, предоставляющую доступ на чтение к данным, о которых отправляются уведомления.

В случае изменений схемы это означает любую область видимости, предоставляющую доступ на чтение к формам с помощью метода forms.get() .
В случае ответов это означает любую область видимости, предоставляющую доступ на чтение к ответам форм , например, с помощью forms.responses.list() .

Для доставки уведомлений приложению необходимо сохранить разрешение OAuth от авторизованного пользователя с необходимыми правами доступа. Если пользователь отключит приложение, уведомления прекратятся, и наблюдение может быть приостановлено с ошибкой. Чтобы возобновить уведомления после восстановления авторизации, см. раздел «Обновление наблюдения» .

Перечислите часы из формы.

Python

forms/nippets/list_watches.py

Посмотреть на 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)

Node.js

forms/snippets/list_watches.js

Посмотреть на GitHub

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

Обновить часы

Python

forms/nippets/renew_watch.py

Посмотреть на 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)

Node.js

forms/snippets/renew_watch.js

Посмотреть на GitHub

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

Регулирование скорости

Частота уведомлений ограничена — каждые тридцать секунд каждые часы могут получать не более одного уведомления. Этот порог частоты может быть изменен.

Из-за ограничения скорости обработки уведомлений одно уведомление может соответствовать нескольким событиям. Другими словами, уведомление указывает на то, что с момента последнего уведомления произошло одно или несколько событий.

Пределы

В любой момент времени для заданной формы и типа события каждый проект Cloud Console может содержать:

до 20 часов всего
до одних часов на одного конечного пользователя

Кроме того, в любой момент времени каждая форма ограничена 50 просмотрами каждого типа события в общей сложности по всем проектам Cloud Console.

Часы связываются с конечным пользователем при их создании или продлении с использованием учетных данных этого пользователя. Часы приостанавливаются, если связанный с ними конечный пользователь теряет доступ к форме или отзывает доступ приложения к форме.

Надежность

За исключением исключительных случаев, каждые часы получают уведомление как минимум один раз после каждого события. В подавляющем большинстве случаев уведомление приходит в течение нескольких минут после события.

Ошибки

Если уведомления для часов постоянно не доставляются, состояние часов меняется на SUSPENDED , и поле errorType в часах устанавливается в значение. Чтобы вернуть приостановленное состояние часов в ACTIVE и возобновить уведомления, см. раздел «Обновление часов» .

Настройте и получайте push-уведомления Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Обзор

Доступные типы событий

Ответы на уведомления

Настройте тему Cloud Pub/Sub.

Создать часы

Python

Node.js

Удалить часы

Python

Node.js

Авторизация

Перечислите часы из формы.

Python

Node.js

Обновить часы

Python

Node.js

Регулирование скорости

Пределы

Надежность

Ошибки

Рекомендуемое использование

Настройте и получайте push-уведомления