設定及接收推播通知

您可以使用 Watches 集合中的函式，在表單中的資料變更時收到通知。本頁面提供概念總覽和設定及接收推播通知的操作說明。

總覽

Google Forms API 推播通知功能可讓應用程式在表單中的資料變更時訂閱通知。通知會傳送至 Cloud Pub/Sub 主題，通常會在變更後的幾分鐘內傳送。

如要接收推播通知，您需要設定 Cloud Pub/Sub 主題，並在建立適當事件類型的監控時提供該主題名稱。

以下是本文件中所用重要概念的定義：

  • 目標是指通知傳送的目的。唯一支援的目標是 Cloud Pub/Sub 主題。
  • 事件類型是第三方應用程式可訂閱的通知類別。
  • watch 是給 Forms API 的指令，可將特定表單上的特定事件類型通知傳送至目標。

在特定表單上建立事件類型的監控後，該監控的目標 (即 Cloud Pub/Sub 主題) 會收到該表單上這些事件的通知，直到監控到期為止。手錶的電池續航力為一週，但您可以在到期前隨時發出 watches.renew() 要求，延長電池續航力。

您的 Cloud Pub/Sub 主題只會接收您可透過所提供的憑證查看的表單通知。舉例來說，如果使用者撤銷應用程式權限，或失去已監控表單的編輯權限，系統就不會再傳送通知。

可用的事件類型

Google 表單 API 目前提供兩類事件：

  • 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 接收網頁鉤子通知，也可以輪詢訂閱端點。

如要設定 Cloud Pub/Sub 主題，請按照下列步驟操作：

  1. 完成 Cloud Pub/Sub 先決條件。
  2. 設定 Cloud Pub/Sub 用戶端。
  3. 查看 Cloud Pub/Sub 價格，並為您的雲端控制台專案啟用帳單功能。

  4. 您可以透過下列三種方式建立 Cloud Pub/Sub 主題：

  5. 在 Cloud Pub/Sub 中建立訂閱，告訴 Cloud Pub/Sub 如何傳送通知。

  6. 最後，在建立指定主題的監控器之前，您需要授予權限，讓表單通知服務帳戶 (forms-notifications@system.gserviceaccount.com) 發布至主題。

建立智慧手錶

有了可供 Google 表單 API 推播通知服務帳戶發布的專題後，您就可以使用 watches.create() 方法建立通知。這個方法會驗證推播通知服務帳戶是否可以存取提供的 Cloud Pub/Sub 主題，如果無法存取，就會失敗，例如主題不存在，或是您未授予該主題的發布權限。

Python

forms/snippets/create_watch.py
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
'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;

刪除手錶

Python

forms/snippets/delete_watch.py
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
'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;

授權

與所有對 Forms API 的呼叫一樣，對 watches.create() 的呼叫必須使用授權憑證進行授權。權杖必須包含範圍，授予對應通知的資料讀取權限。

如要傳送通知，應用程式必須保留已授權使用者提供的 OAuth 授權，並具備必要的範圍。如果使用者中斷應用程式連線，系統就會停止傳送通知，手錶可能會因錯誤而暫停運作。如要在重新取得授權後恢復通知，請參閱續訂手錶。

列出表單的錶面

Python

forms/snippets/list_watches.py
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
'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;

續約手錶

Python

forms/snippets/renew_watch.py
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
'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;

調節

通知會受到節流限制，每部手錶每 30 秒最多只能收到一則通知。這個頻率門檻可能會變動。

由於受到節流限制，單一通知可能會對應多個事件。換句話說，通知會指出自上次通知後發生一或多個事件。

限制

在任何時間點，每個 Cloud Console 專案可針對特定表單和事件類型擁有：

  • 最多 20 次
  • 每位使用者最多可擁有一支手錶

此外，在所有 Cloud 控制台專案中，每個表單的每個事件類型，在任何時間點都只能有 50 個監控。

使用者建立或續訂手錶時，系統會使用該使用者的憑證建立或續訂手錶，並與使用者建立關聯。如果相關聯的使用者失去表單存取權，或撤銷應用程式對表單的存取權，手錶就會暫停。

可靠性

除非發生特殊情況，否則每個手錶在每個事件發生後都會收到至少一次通知。在大多數情況下，系統會在事件發生後幾分鐘內發送通知。

錯誤

如果手錶的通知持續無法傳送，手錶狀態會變成 SUSPENDED，且手錶的 errorType 欄位會設為 如要將已暫停的錶款狀態重設為 ACTIVE，並恢復通知，請參閱續約錶款。

建議用途

  • 使用單一 Cloud Pub/Sub 主題做為多個監控的目標。
  • 收到主題通知時，表單 ID 會包含在通知酬載中。搭配事件類型使用，即可瞭解要擷取哪些資料，以及從哪個表單擷取資料。
  • 如要在使用 EventType.RESPONSES 的通知後擷取更新資料，請呼叫 forms.responses.list()。
    • 將要求的篩選器設為 timestamp > timestamp_of_the_last_response_you_fetched。
  • 如要在收到 EventType.SCHEMA 通知後擷取更新的資料，請呼叫 forms.get()。