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 biểu mẫu. Trang này cung cấp thông tin tổng quan và hướng dẫn về cách thiết lập và 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 sẽ được gửi đến một chủ đề trên Cloud Pub/Sub, thường 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 chủ đề Cloud Pub/Sub và cung cấp tên của chủ đề đó khi tạo đồ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 gửi thông báo. 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ý.
- Đồng hồ là hướng dẫn cho API Biểu mẫu để 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ể tới một mục tiêu.
Sau khi bạn tạo đồ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ồ đó (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ể dùng trong một tuần, nhưng bạn có thể gia hạn thời gian này bất cứ lúc nào trước khi hết hạn bằng cách gửi yêu cầu tới watches.renew().
Chủ đề Cloud Pub/Sub của bạn chỉ nhận được thông báo về các 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 trong ứng dụng hoặc mất quyền chỉnh sửa một biểu mẫu đã xem, 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ề các nội dung chỉnh sửa đối với nội dung và chế độ cài đặt của biểu mẫu.EventType.RESPONSES
– sẽ thông báo khi bạn gửi phản hồi qua biểu mẫu (cả mới và cập nhật).
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ồ đang 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ạ thông báo mẫu về việc 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ạ 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 chủ đề Cloud Pub/Sub
Thông báo được gửi đến các chủ đề trên Cloud Pub/Sub. Trên Cloud Pub/Sub, bạn có thể nhận thông báo trên một webhook hoặc bằng cách thăm dò đ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 thành Điều kiện tiên quyết về Cloud Pub/Sub.
- Thiết lập máy khách Cloud Pub/Sub.
- Xem lại giá của Cloud Pub/Sub và bật tính năng thanh toán cho dự án Developer Console của bạn.
Tạo chủ đề Cloud Pub/Sub bằng một trong ba cách:
- bằng cách sử dụng Bảng điều khiển dành cho nhà phát triển (cách dễ nhất)
- sử dụng công cụ dòng lệnh (để sử dụng có lập trình đơn giản) hoặc
- bằng cách sử dụng API Cloud Pub/Sub.
Tạo Gói thuê bao trong Cloud Pub/Sub để cho Cloud Pub/Sub biết cách gửi thông báo của bạn.
Cuối cùng, trước khi tạo đồng hồ nhắm mục tiêu đế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) để xuất bản chủ đề.
Tạo đồng hồ
Sau khi có chủ đề mà tài khoản dịch vụ thông báo đẩy của 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 chủ đề Cloud Pub/Sub đã cung cấp có thể truy cập được qua tài khoản dịch vụ thông báo đẩy và sẽ không truy cập được nếu không truy cập được chủ đề này; 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ủ đề đó.
Python
Node.js
Xoá đồng hồ
Python
Node.js
Ủy quyền
Giống như mọi 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ã thông báo 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ề những thông báo đang được gửi.
- Đối với các thay đổi về giản đồ, đây là mọi phạm vi cấp quyền đọc forms thông qua forms.get().
- Đối với phản hồi, đây có nghĩa là bất kỳ phạm vi nào cấp quyền đọc phản hồi biểu mẫu, chẳng hạn như thông qua forms.responses.list().
Để gửi thông báo, ứng dụng phải giữ lại thông tin đã cấp OAuth từ người dùng được uỷ quyền trong 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ì thông báo sẽ dừng lại và đồng hồ có thể bị tạm ngưng do xảy ra lỗi. Để tiếp tục nhận thông báo sau khi được cấp lại quyền, hãy xem phần Gia hạn đồng hồ.
Liệt kê đồ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
Thông báo bị điều tiết – 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 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 gần nhất.
Các giới hạn
Tại mọi thời điểm, đối với một biểu mẫu và loại sự kiện nhất định, mỗi dự á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, bất cứ lúc nào, mỗi biểu mẫu chỉ được có tối đa 50 đồng hồ cho mỗi loại sự kiện, đối với tất cả các dự á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 cho người dùng đó. Đồ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 trong mọi trường hợp đặc biệt. Trong hầu hết các trường hợp, thông báo sẽ được gửi trong vòng vài phút sau khi sự kiện diễn ra.
Lỗi
Nếu thông báo của đồng hồ liên tục không được gửi, trạng thái đồng hồ sẽ trở thành SUSPENDED
và trường errorType
của đồng hồ đượ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 Gia hạn đồng hồ.
Cách sử dụng được đề xuất
- Sử dụng một chủ đề Cloud Pub/Sub duy nhất 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 đưa vào trọng tải thông báo. Hãy sử dụng sự kiện này với loại sự kiện để biết dữ liệu nào cần tìm nạp và biểu mẫu nào cần tìm nạp.
- Để 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 theo yêu cầu thành
timestamp > timestamp_of_the_last_response_you_fetched
.
- Đặt bộ lọc theo yêu cầu thành
- Để tìm nạp dữ liệu cập nhật sau khi nhận được thông báo bằng
EventType.SCHEMA
, hãy gọi forms.get().