Trang này được dịch bởi Cloud Translation API.

Thiết lập và nhận thông báo đẩy

Bạn có thể sử dụng các phương thức trong bộ sưu tập Watches (Đồng hồ) để nhận thông báo khi dữ liệu thay đổi trong các biểu mẫu. Trang này cung cấp thông tin tổng quan về khái niệm và hướng dẫn thiết lập cũng như nhận thông báo đẩy.

Tổng quan

Tính năng thông báo đẩy của API Google Biểu mẫu cho phép các ứng dụng đăng ký nhận thông báo khi dữ liệu thay đổi trong biểu mẫu. Thông báo được phân phối đến một chủ đề Cloud Pub/Sub, thường là trong vòng vài phút sau khi thay đổi.

Để nhận thông báo đẩy, bạn cần thiết lập một chủ đề Cloud Pub/Sub và cung cấp tên của chủ đề đó khi tạo một đồng hồ cho loại sự kiện thích hợp.

Dưới đây là định nghĩa về các khái niệm chính được sử dụng trong tài liệu này:

Mục tiêu là nơi thông báo được gửi đến. Mục tiêu duy nhất được hỗ trợ là chủ đề Cloud Pub/Sub.
Loại sự kiện là một danh mục thông báo mà ứng dụng bên thứ ba có thể đăng ký.
Watch (theo dõi) là một hướng dẫn cho API Biểu mẫu để phân phối thông báo cho một loại sự kiện cụ thể trên một biểu mẫu cụ thể đến một mục tiêu.

Sau khi bạn tạo một đồng hồ cho một loại sự kiện trên một biểu mẫu cụ thể, mục tiêu của đồng hồ đó (là một chủ đề Cloud Pub/Sub) sẽ nhận được thông báo từ các sự kiện đó trên biểu mẫu đó cho đến khi đồng hồ hết hạn. Đồng hồ của bạn có thời hạn một tuần, nhưng bạn có thể gia hạn đồng hồ bất cứ lúc nào trước khi đồng hồ hết hạn bằng cách gửi yêu cầu đến watches.renew().

Chủ đề Cloud Pub/Sub của bạn chỉ nhận thông báo về những biểu mẫu mà bạn có thể xem bằng thông tin xác thực mà bạn cung cấp. Ví dụ: nếu người dùng thu hồi quyền của ứng dụng hoặc mất quyền chỉnh sửa đối với một biểu mẫu được theo dõi, thì thông báo sẽ không được gửi nữa.

Các loại sự kiện hiện có

API Google Biểu mẫu hiện cung cấp hai danh mục sự kiện:

EventType.SCHEMA, thông báo về nội dung và chế độ cài đặt của biểu mẫu.
EventType.RESPONSES, thông báo khi câu trả lời trên biểu mẫu (cả mới và đã cập nhật) được gửi.

Phản hồi thông báo

Thông báo được mã hoá bằng JSON và chứa:

Mã của biểu mẫu kích hoạt
Mã của đồng hồ kích hoạt
Loại sự kiện đã kích hoạt thông báo
Các trường khác do Cloud Pub/Sub đặt, chẳng hạn như messageId và publishTime

Thông báo không chứa dữ liệu chi tiết về biểu mẫu hoặc phản hồi. Sau khi nhận được mỗi thông báo, bạn cần có một lệnh gọi API riêng để tìm nạp dữ liệu mới. Hãy xem phần Cách sử dụng đề xuất để biết cách thực hiện việc này.

Đoạn mã sau đây minh hoạ một thông báo mẫu cho một thay đổi về giản đồ:

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

Đoạn mã sau đây minh hoạ một thông báo mẫu cho một phản hồi mới:

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

Thiết lập chủ đề Cloud Pub/Sub

Thông báo được gửi đến các chủ đề Cloud Pub/Sub. Từ Cloud Pub/Sub, bạn có thể nhận thông báo trên một trình kích hoạt web hoặc bằng cách thăm dò ý kiến điểm cuối của gói thuê bao.

Để thiết lập chủ đề Cloud Pub/Sub, hãy làm như sau:

Hoàn tất Các điều kiện tiên quyết của Cloud Pub/Sub.
Thiết lập ứng dụng Cloud Pub/Sub.
Xem bảng giá của Cloud Pub/Sub và bật tính năng thanh toán cho dự án trên Developer Console.
Bạn có thể tạo chủ đề Cloud Pub/Sub theo một trong ba cách sau:
- sử dụng Bảng điều khiển dành cho nhà phát triển (dễ nhất)
- sử dụng công cụ dòng lệnh (dùng cho mục đích sử dụng có lập trình đơn giản) hoặc
- bằng cách sử dụng API Cloud Pub/Sub.
Lưu ý: Cloud Pub/Sub chỉ cho phép một số chủ đề có hạn, vì vậy, việc sử dụng một chủ đề để nhận tất cả thông báo sẽ đảm bảo rằng bạn không gặp phải vấn đề về việc mở rộng quy mô nếu ứng dụng của bạn trở nên phổ biến.
Tạo gói thuê bao trong Cloud Pub/Sub để cho Cloud Pub/Sub biết cách phân phối thông báo.
Cuối cùng, trước khi tạo đồng hồ nhắm đến chủ đề của mình, bạn cần cấp quyền cho tài khoản dịch vụ thông báo của Biểu mẫu (forms-notifications@system.gserviceaccount.com) để đăng lên chủ đề của bạn.

Tạo đồng hồ

Sau khi có một chủ đề mà tài khoản dịch vụ thông báo đẩy API Biểu mẫu có thể phát hành, bạn có thể tạo thông báo bằng phương thức watches.create(). Phương thức này xác thực rằng tài khoản dịch vụ thông báo đẩy có thể truy cập vào chủ đề Cloud Pub/Sub được cung cấp và không thành công nếu tài khoản đó không thể truy cập vào chủ đề; ví dụ: nếu chủ đề không tồn tại hoặc bạn chưa cấp quyền phát hành cho chủ đề đó.

PythonNode.js

forms/snippets/create_watch.py

Xem trên 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)

forms/snippets/create_watch.js

Xem trên GitHub

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

Xoá đồng hồ

PythonNode.js

forms/snippets/delete_watch.py

Xem trên 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)

forms/snippets/delete_watch.js

Xem trên GitHub

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

Ủy quyền

Giống như tất cả các lệnh gọi đến API Biểu mẫu, các lệnh gọi đến watches.create() phải được uỷ quyền bằng mã uỷ quyền. Mã thông báo phải bao gồm một phạm vi cấp quyền đọc dữ liệu về thông báo đang được gửi.

Đối với các thay đổi về giản đồ, điều này có nghĩa là mọi phạm vi cấp quyền đọc vào biểu mẫu bằng cách sử dụng forms.get().
Đối với câu trả lời, phạm vi này có nghĩa là bất kỳ phạm vi nào cấp quyền đọc vào câu trả lời của biểu mẫu, ví dụ: sử dụng forms.responses.list().

Để gửi thông báo, ứng dụng phải giữ lại một khoản cấp phép OAuth từ người dùng được uỷ quyền có các phạm vi bắt buộc. Nếu người dùng ngắt kết nối ứng dụng, thông báo sẽ ngừng và đồng hồ có thể bị tạm ngưng kèm theo lỗi. Để tiếp tục nhận thông báo sau khi lấy lại quyền, hãy xem phần Kích hoạt lại đồng hồ.

Liệt kê các đồng hồ của một biểu mẫu

PythonNode.js

forms/snippets/list_watches.py

Xem trên 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)

forms/snippets/list_watches.js

Xem trên GitHub

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

Gia hạn đồng hồ

PythonNode.js

forms/snippets/renew_watch.py

Xem trên 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)

forms/snippets/renew_watch.js

Xem trên GitHub

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

Điều tiết

Thông báo được điều tiết – mỗi đồng hồ có thể nhận được tối đa một thông báo mỗi 30 giây. Ngưỡng tần suất này có thể thay đổi.

Do tính năng điều tiết, một thông báo có thể tương ứng với nhiều sự kiện. Nói cách khác, thông báo cho biết một hoặc nhiều sự kiện đã xảy ra kể từ thông báo cuối cùng.

Giới hạn

Tại bất kỳ thời điểm nào, đối với một loại sự kiện và biểu mẫu nhất định, mỗi dự án trên Cloud Console có thể có:

tổng cộng tối đa 20 đồng hồ
tối đa một đồng hồ cho mỗi người dùng cuối

Ngoài ra, tại bất kỳ thời điểm nào, mỗi biểu mẫu cũng chỉ được giới hạn ở tổng cộng 50 lượt xem cho mỗi loại sự kiện trên tất cả các dự án trên Cloud Console.

Một đồng hồ được liên kết với người dùng cuối khi được tạo hoặc gia hạn bằng thông tin xác thực của người dùng đó. Một đồng hồ sẽ bị tạm ngưng nếu người dùng cuối được liên kết mất quyền truy cập vào biểu mẫu hoặc thu hồi quyền truy cập của ứng dụng vào biểu mẫu.

Độ tin cậy

Mỗi đồng hồ sẽ được thông báo ít nhất một lần sau mỗi sự kiện, ngoại trừ các trường hợp đặc biệt. Trong hầu hết các trường hợp, thông báo sẽ được phân phối trong vòng vài phút sau khi sự kiện xảy ra.

Lỗi

Nếu thông báo cho một đồng hồ liên tục không được phân phối, thì trạng thái đồng hồ sẽ trở thành SUSPENDED và trường errorType của đồng hồ sẽ được đặt. Để đặt lại trạng thái của đồng hồ bị tạm ngưng về ACTIVE và tiếp tục nhận thông báo, hãy xem phần Kích hoạt lại đồng hồ.

Cách sử dụng đề xuất

Sử dụng một chủ đề Cloud Pub/Sub làm mục tiêu của nhiều đồng hồ.
Khi nhận được thông báo về một chủ đề, mã biểu mẫu sẽ được đưa vào gói dữ liệu thông báo. Sử dụng thuộc tính này với loại sự kiện để biết dữ liệu cần tìm nạp và biểu mẫu cần tìm nạp dữ liệu.
Để tìm nạp dữ liệu đã cập nhật sau khi có thông báo bằng EventType.RESPONSES, hãy gọi forms.responses.list().
- Đặt bộ lọc trên yêu cầu thành timestamp > timestamp_of_the_last_response_you_fetched.
Để tìm nạp dữ liệu đã cập nhật sau khi có thông báo bằng EventType.SCHEMA, hãy gọi forms.get().