Để giúp người tạo biểu mẫu kiểm soát chặt chẽ hơn những người có thể trả lời, chúng tôi sẽ ra mắt chế độ kiểm soát chi tiết cho người trả lời. Theo mặc định, những biểu mẫu được tạo bằng API sau ngày 31 tháng 3 năm 2026 sẽ ở trạng thái chưa được xuất bản. Để tìm hiểu thêm, hãy xem bài viết Các thay đổi về API đối với Google Biểu mẫu.

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 tập hợp Watches để nhận thông báo khi dữ liệu thay đổi trong 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 Google Biểu mẫu API 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 gửi đến một chủ đề Cloud Pub/Sub, thường là trong vòng vài phút kể từ khi có 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 yêu cầu theo dõi 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 dùng trong tài liệu này:

Đích đến là nơi thông báo được gửi đến. Mục tiêu duy nhất được hỗ trợ là một 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ý nhận.
watch là một chỉ dẫn cho Forms API để gửi thông báo về 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 lệnh theo dõi cho một loại sự kiện trên một biểu mẫu cụ thể, đích đến của lệnh theo dõi đó (là một chủ đề Cloud Pub/Sub) sẽ nhận được thông báo từ những sự kiện đó trên biểu mẫu đó cho đến khi lệnh theo dõi hết hạn. Thời gian xem của bạn là một tuần, nhưng bạn có thể gia hạn bất cứ lúc nào trước khi 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 đăng nhập 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 có sẵn

Google Biểu mẫu API hiện cung cấp 2 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 được chỉnh sửa.
EventType.RESPONSES, thông báo khi có câu trả lời qua biểu mẫu (cả câu trả lời mới và câu trả lời đã 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à có chứa:

Mã nhận dạng của biểu mẫu kích hoạt
Mã nhận dạng 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 câu trả lời. Sau khi nhận được mỗi thông báo, bạn cần thực hiện một lệnh gọi API riêng biệt để tìm nạp dữ liệu mới. Hãy xem phần Cách sử dụng được đề 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 về thay đổi 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 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 một 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 web hook hoặc bằng cách thăm dò một điểm cuối đăng ký.

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

Hoàn tất Các điều kiện tiên quyết đối với Cloud Pub/Sub.
Thiết lập một ứng dụng Cloud Pub/Sub.
Xem giá của Cloud Pub/Sub và bật tính năng thanh toán cho dự án trên Developer Console.
Tạo một chủ đề Cloud Pub/Sub bằng một trong 3 cách sau:
- sử dụng Developer Console (dễ nhất)
- bằng cách sử dụng công cụ dòng lệnh (để sử dụng theo cách 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ố lượng 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 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 một gói thuê bao trong Cloud Pub/Sub để cho Cloud Pub/Sub biết cách gửi thông báo.
Cuối cùng, trước khi tạo các yêu cầu theo dõi nhắm đến chủ đề của bạn, 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 một đồng hồ

Sau khi có một chủ đề mà tài khoản dịch vụ thông báo đẩy của Forms API có thể xuất bản, 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à sẽ không thành công nếu không truy cập được vào chủ đề đó; ví dụ: nếu chủ đề không tồn tại hoặc bạn chưa cấp cho chủ đề đó quyền xuất bản.

Python

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)

Node.js

forms/snippets/create_watch.js

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

Xoá đồng hồ

Python

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)

Node.js

forms/snippets/delete_watch.js

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

Ủy quyền

Giống như tất cả các lệnh gọi đến Forms API, 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 có một phạm vi cấp quyền truy cập đọc vào dữ liệu mà 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 cho biểu mẫu bằng cách sử dụng forms.get().
Đối với câu trả lời, điều này có nghĩa là mọi phạm vi cấp quyền đọc cho câu trả lời của biểu mẫu, ví dụ: sử dụng forms.responses.list().

Để thông báo được gửi, ứng dụng phải giữ lại một quyền truy cậ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 do lỗi. Để tiếp tục nhận thông báo sau khi lấy lại quyền uỷ quyền, hãy xem phần Gia hạn quyền uỷ quyền cho đồng hồ.

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

Python

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)

Node.js

forms/snippets/list_watches.js

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

Gia hạn đồng hồ

Python

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)

Node.js

forms/snippets/renew_watch.js

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

Điều tiết

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

Do bị điều tiết, một thông báo duy nhất 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 đã có một hoặc nhiều sự kiện xảy ra kể từ thông báo gần đây nhất.

Giới hạn

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

tối đa 20 lượt xem
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 đều bị giới hạn ở 50 lượt theo dõi cho mỗi loại sự kiện trên tổng số tất cả các dự án trên Cloud Console.

Đồ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 đăng nhập của người dùng đó. Đồng hồ sẽ bị tạm ngưng nếu người dùng cuối 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ẽ nhận được thông báo ít nhất một lần sau mỗi sự kiện, trừ những trường hợp đặc biệt. Trong phần lớn các trường hợp, thông báo sẽ được gửi trong vòng vài phút kể từ khi có sự kiện.

Lỗi

Nếu thông báo cho một đồng hồ liên tục không được gửi, trạng thái của đồng hồ sẽ chuyển 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 thành ACTIVE và tiếp tục nhận thông báo, hãy xem phần Làm mới đồng hồ.

Mức sử dụng được đề xuất

Sử dụng một chủ đề Cloud Pub/Sub làm mục tiêu của nhiều lượt theo dõi.
Khi nhận được thông báo về một chủ đề, mã biểu mẫu sẽ có trong gói dữ liệu thông báo. Sử dụng tham số này với loại sự kiện để biết cần tìm nạp dữ liệu nào và tìm nạp dữ liệu đó từ biểu mẫu nào.
Để tìm nạp dữ liệu mới nhất sau khi nhận đượ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 một thông báo có EventType.SCHEMA, hãy gọi forms.get().

Thiết lập và nhận thông báo đẩy Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tổng quan

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

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

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

Tạo một đồng hồ

Python

Node.js

Xoá đồng hồ

Python

Node.js

Ủy quyền

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

Python

Node.js

Gia hạn đồng hồ

Python

Node.js

Điều tiết

Giới hạn

Độ tin cậy

Lỗi

Mức sử dụng được đề xuất

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