フォーム作成者が回答者をより細かく制御できるように、回答者向けのきめ細かい制御機能が導入されます。2026 年 3 月 31 日以降に API で作成されたフォームは、デフォルトで非公開の状態になります。詳しくは、Google フォームの API の変更をご覧ください。

このページは Cloud Translation API によって翻訳されました。

プッシュ通知の設定と受信

Watches コレクションのメソッドを使用すると、フォーム内のデータが変更されたときに通知を受け取ることができます。このページでは、プッシュ通知の設定と受信に関するコンセプトの概要と手順について説明します。

概要

Google Forms API のプッシュ通知機能を使用すると、フォームのデータが変更されたときに通知を受け取るようにアプリケーションを登録できます。通知は、通常、変更から数分以内に Cloud Pub/Sub トピックに配信されます。

プッシュ通知を受け取るには、Cloud Pub/Sub トピックを設定し、適切なイベントタイプのウォッチを作成するときにそのトピックの名前を指定する必要があります。

このドキュメントで使用されている主なコンセプトの定義は次のとおりです。

ターゲットは、通知の送信先です。サポートされているターゲットは Cloud Pub/Sub トピックのみです。
イベントタイプは、サードパーティアプリケーションが登録できる通知のカテゴリです。
ウォッチは、特定のフォームの特定のイベントタイプに関する通知を特定のターゲットに配信するようフォーム API に指示するものです。

特定のフォームでイベントタイプの監視を作成すると、その監視のターゲット（Cloud Pub/Sub トピック）は、監視の有効期限が切れるまで、そのフォームのイベントから通知を受け取ります。ウォッチは 1 週間有効ですが、有効期限が切れる前に watches.renew() にリクエストを送信することで、いつでも延長できます。

Cloud Pub/Sub トピックは、指定した認証情報で表示できるフォームに関する通知のみを受信します。たとえば、ユーザーがアプリの権限を取り消したり、監視対象のフォームに対する編集権限を失ったりすると、通知は配信されなくなります。

使用可能なイベントタイプ

現在、Google Forms API では次の 2 つのカテゴリのイベントが提供されています。

EventType.SCHEMA: フォームのコンテンツと設定の編集について通知します。
EventType.RESPONSES: フォームの回答（新規と更新の両方）が送信されたときに通知します。

通知の応答

通知は JSON でエンコードされ、次の情報が含まれます。

トリガーするフォームの ID
トリガーされたウォッチの ID
通知をトリガーしたイベントのタイプ
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 から、Webhook で通知を受信するか、サブスクリプションエンドポイントをポーリングできます。

Cloud Pub/Sub トピックを設定する手順は次のとおりです。

Cloud Pub/Sub の前提条件を満たします。
Cloud Pub/Sub クライアントを設定する。
Cloud Pub/Sub の料金を確認し、Developer Console プロジェクトの課金を有効にします。
Cloud Pub/Sub トピックを作成するには、次の 3 つの方法があります。
- デベロッパーコンソールを使用する（最も簡単）
- コマンドラインツールを使用する（簡単なプログラムでの使用の場合）。
- Cloud Pub/Sub API を使用します。
注: Cloud Pub/Sub で許可されるトピックの数には上限があります。そのため、1 つのトピックを使用してすべての通知を受信することで、アプリが人気になった場合にスケーリングの問題が発生しないようにします。
Cloud Pub/Sub でサブスクリプションを作成して、通知の配信方法を Cloud Pub/Sub に指示します。
最後に、トピックをターゲットとするウォッチを作成する前に、フォーム通知サービスアカウント（forms-notifications@system.gserviceaccount.com）にトピックへのパブリッシュ権限を付与する必要があります。

ウォッチを作成する

Forms API プッシュ通知サービスアカウントが公開できるトピックを作成したら、watches.create() メソッドを使用して通知を作成できます。このメソッドは、指定された Cloud Pub/Sub トピックに push 通知サービスアカウントがアクセスできることを検証します。トピックにアクセスできない場合（トピックが存在しない場合や、そのトピックに対するパブリッシュ権限が付与されていない場合など）は、失敗します。

Python

forms/snippets/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;
}

承認

Forms API へのすべての呼び出しと同様に、watches.create() への呼び出しは認証トークンで承認される必要があります。トークンには、通知の送信対象となるデータへの読み取りアクセス権を付与するスコープを含める必要があります。

スキーマの変更の場合、これは forms.get() を使用してフォームへの読み取りアクセス権を付与するすべてのスコープを意味します。
回答の場合、これは forms.responses.list() などのフォームの回答への読み取りアクセス権を付与するスコープを意味します。

通知を配信するには、アプリケーションが、必要なスコープを持つ承認済みユーザーからの OAuth 権限付与を保持している必要があります。ユーザーがアプリの接続を解除すると、通知は停止し、エラーが発生してスマートウォッチが一時停止することがあります。権限を回復した後に通知を再開するには、スマートウォッチを更新するをご覧ください。

フォームのウォッチを一覧表示する

Python

forms/snippets/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/snippets/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;
}

スロットル処理

通知はスロットリングされます。各スマートウォッチは 30 秒ごとに最大 1 件の通知を受信できます。この頻度のしきい値は変更されることがあります。

スロットリングにより、1 つの通知が複数のイベントに対応している場合があります。つまり、通知は、前回の通知以降に 1 つ以上のイベントが発生したことを示します。

上限

特定のフォームとイベントタイプについて、各 Cloud Console プロジェクトには次のいずれかを含めることができます。

合計 20 個まで
エンドユーザー 1 人につき 1 台のスマートウォッチ

また、各フォームは、すべての Cloud コンソールプロジェクトでイベントタイプごとに合計 50 個のモニタリングに制限されます。

スマートウォッチは、そのユーザーの認証情報を使用して作成または更新されたときに、エンドユーザーに関連付けられます。関連付けられたエンドユーザーがフォームへのアクセス権を失うか、アプリのフォームへのアクセス権を取り消すと、スマートウォッチは一時停止されます。

信頼性

例外的な状況を除き、各ウォッチは各イベントの後に少なくとも 1 回通知されます。ほとんどの場合、イベントの数分以内に通知が配信されます。

エラー

スマートウォッチの通知が配信され続けると、スマートウォッチの状態が SUSPENDED になり、スマートウォッチの errorType フィールドが設定されます。一時停止したスマートウォッチの状態を ACTIVE にリセットして通知を再開するには、スマートウォッチを更新するをご覧ください。

推奨される用途

1 つの Cloud Pub/Sub トピックを複数のモニタリングのターゲットとして使用する。
トピックに関する通知を受信すると、フォーム ID が通知ペイロードに含まれます。イベントタイプとともに使用して、取得するデータと取得元のフォームを把握します。
EventType.RESPONSES を含む通知の後に更新されたデータを取得するには、forms.responses.list() を呼び出します。
- リクエストのフィルタを timestamp > timestamp_of_the_last_response_you_fetched に設定します。
EventType.SCHEMA を含む通知の後に更新されたデータを取得するには、forms.get() を呼び出します。

プッシュ通知の設定と受信 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

使用可能なイベントタイプ

通知の応答

Cloud Pub/Sub トピックを設定する

ウォッチを作成する

Python

Node.js

モニタリングを削除する

Python

Node.js

承認

フォームのウォッチを一覧表示する

Python

Node.js

スマートウォッチを更新する

Python

Node.js

スロットル処理

上限

信頼性

エラー

推奨される用途

プッシュ通知の設定と受信