Tài liệu này mô tả cách dùng thông báo đẩy để thông báo cho ứng dụng khi một tài nguyên thay đổi.
Tổng quan
API Lịch Google cung cấp thông báo đẩy cho phép bạn theo dõi những thay đổi trong các tài nguyên. Bạn có thể sử dụng tính năng này để cải thiện hiệu suất của ứng dụng. Tính năng này cho phép bạn loại bỏ mạng bổ sung và tính toán chi phí liên quan đến việc thăm dò ý kiến để xác định xem các tài nguyên đó có thay đổi hay không. Bất cứ khi nào tài nguyên đã xem thay đổi, API Lịch Google sẽ thông báo cho ứng dụng của bạn.
Để sử dụng thông báo đẩy, bạn phải làm 2 việc:
Thiết lập URL nhận hoặc trình nhận lệnh gọi lại "webhook".
Đây là một máy chủ HTTPS xử lý những thông báo thông báo API được kích hoạt khi tài nguyên thay đổi.
Thiết lập một kênh thông báo cho mỗi điểm cuối tài nguyên mà bạn muốn xem.
Kênh chỉ định thông tin định tuyến cho nội dung thông báo. Trong quá trình thiết lập kênh, bạn phải xác định URL cụ thể mà bạn muốn nhận thông báo. Bất cứ khi nào tài nguyên của kênh thay đổi, API Lịch Google sẽ gửi một thông báo dưới dạng yêu cầu
POSTđến URL đó.
Hiện tại, API Lịch Google hỗ trợ thông báo về những thay đổi đối với tài nguyên Acl, CalendarList, Sự kiện và Cài đặt.
Tạo kênh thông báo
Để yêu cầu gửi thông báo đẩy, bạn phải thiết lập kênh thông báo cho từng tài nguyên mà bạn muốn theo dõi. Sau khi thiết lập kênh thông báo, API Lịch Google sẽ thông báo cho ứng dụng của bạn khi có bất kỳ tài nguyên nào đã xem thay đổi.
Đưa ra yêu cầu xem
Mỗi tài nguyên API Lịch Google có thể xem đều có một phương thức watch được liên kết tại URI ở dạng sau:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Để thiết lập một kênh thông báo cho các thông báo về các thay đổi đối với một tài nguyên cụ thể, hãy gửi yêu cầu POST đến phương thức watch cho tài nguyên đó.
Mỗi kênh thông báo được liên kết với cả một người dùng và tài nguyên (hoặc nhóm tài nguyên) cụ thể. Yêu cầu watch sẽ không thành công trừ phi người dùng hiện tại
sở hữu hoặc có quyền truy cập vào tài nguyên này.
Ví dụ:
Bắt đầu xem những thay đổi đối với một nhóm sự kiện trên một lịch cụ thể:
POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json
{
"id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
"type": "web_hook",
"address": "https://mydomain.com/notifications", // Your receiving URL.
...
"token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
"expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}
Thuộc tính bắt buộc
Với mỗi yêu cầu watch, bạn phải cung cấp các trường sau:
-
Một chuỗi thuộc tính
idnhận dạng duy nhất kênh thông báo mới này trong dự án của bạn. Bạn nên dùng một giá trị nhận dạng duy nhất trên toàn cầu (UUID) hoặc bất kỳ chuỗi duy nhất nào tương tự. Độ dài tối đa: 64 ký tự.Giá trị mã nhận dạng mà bạn đặt sẽ được lặp lại trong tiêu đề HTTP
X-Goog-Channel-Idcủa mọi thông báo mà bạn nhận được đối với kênh này. -
Chuỗi thuộc tính
typeđược đặt thành giá trịweb_hook. -
Chuỗi thuộc tính
addressđược đặt thành URL nghe và phản hồi thông báo cho kênh thông báo này. Đây là URL gọi lại webhook và phải sử dụng HTTPS.Xin lưu ý rằng API Lịch Google chỉ có thể gửi thông báo đến địa chỉ HTTPS này nếu bạn cài đặt chứng chỉ SSL hợp lệ trên máy chủ web của mình. Chứng chỉ không hợp lệ bao gồm:
- Chứng chỉ tự ký.
- Chứng chỉ do một nguồn không đáng tin cậy ký.
- Chứng chỉ đã bị thu hồi.
- Chứng chỉ có tiêu đề không khớp với tên máy chủ mục tiêu.
Thuộc tính tuỳ chọn
Bạn cũng có thể chỉ định các trường không bắt buộc sau đây bằng yêu cầu watch:
-
Thuộc tính
tokenchỉ định một giá trị chuỗi tuỳ ý để dùng làm mã thông báo kênh. Bạn có thể sử dụng mã thông báo kênh cho nhiều mục đích. Ví dụ: bạn có thể sử dụng mã thông báo để xác minh rằng mỗi tin nhắn đến là dành cho một kênh mà ứng dụng của bạn đã tạo (để đảm bảo rằng thông báo không bị giả mạo) hoặc để chuyển thông báo đến đúng đích đến trong ứng dụng dựa trên mục đích của kênh này. Độ dài tối đa: 256 ký tự.Mã thông báo này được đưa vào tiêu đề HTTP
X-Goog-Channel-Tokentrong mọi thông báo mà ứng dụng nhận được cho kênh này.Nếu sử dụng mã thông báo kênh thông báo, bạn nên:
Sử dụng định dạng mã hoá có thể mở rộng, chẳng hạn như tham số truy vấn URL. Ví dụ:
forwardTo=hr&createdBy=mobileĐừng gửi dữ liệu nhạy cảm như mã thông báo OAuth.
-
Chuỗi thuộc tính
expirationđược đặt thành Dấu thời gian Unix (tính bằng mili giây) về ngày và giờ mà bạn muốn API Lịch Google ngừng gửi thông báo cho kênh thông báo này.Nếu một kênh có thời gian hết hạn, thì kênh đó sẽ được đưa vào dưới dạng giá trị của tiêu đề HTTP
X-Goog-Channel-Expiration(ở định dạng mà con người có thể đọc được) trong mọi thông báo mà ứng dụng của bạn nhận được cho kênh này.
Để biết thêm thông tin chi tiết về yêu cầu, hãy tham khảo phương thức watch cho các tài nguyên Acl, CalendarList, Sự kiện và Cài đặt trong Tài liệu tham khảo API.
Xem phản hồi
Nếu yêu cầu watch tạo thành công một kênh thông báo, thì yêu cầu đó sẽ trả về một mã trạng thái HTTP 200 OK.
Nội dung thông báo của phản hồi đồng hồ cung cấp thông tin về kênh thông báo bạn vừa tạo, như minh hoạ trong ví dụ dưới đây.
{
"kind": "api#channel",
"id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
"resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
"resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
"token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
"expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}
Ngoài các thuộc tính mà bạn đã gửi trong yêu cầu của mình, thông tin được trả về cũng bao gồm resourceId và resourceUri để xác định tài nguyên đang được xem trên kênh thông báo này.
Bạn có thể truyền thông tin được trả về đến các thao tác khác của kênh thông báo, chẳng hạn như khi bạn muốn ngừng nhận thông báo.
Để biết thêm thông tin về phản hồi, hãy tham khảo phương thức watch cho các tài nguyên Acl, CalendarList, Sự kiện và Cài đặt trong Tài liệu tham khảo API.
Đồng bộ hoá thư
Sau khi tạo kênh thông báo để xem tài nguyên, API Lịch Google sẽ gửi thông báo sync để cho biết rằng thông báo đang bắt đầu. Giá trị tiêu đề HTTP X-Goog-Resource-State cho những thông báo này là sync. Do các vấn đề về thời gian kết nối mạng, bạn có thể nhận được thông báo sync ngay cả trước khi nhận được phản hồi của phương thức watch.
Bạn có thể bỏ qua thông báo sync, nhưng bạn cũng có thể sử dụng thông báo này. Ví dụ: Nếu quyết định không muốn giữ lại kênh nữa, bạn có thể sử dụng các giá trị X-Goog-Channel-ID và X-Goog-Resource-ID trong lệnh gọi để ngừng nhận thông báo. Bạn cũng có thể sử dụng thông báo sync để thực hiện một số thao tác khởi chạy nhằm chuẩn bị cho các sự kiện sau này.
Dưới đây là định dạng của thông báo sync mà API Lịch Google gửi đến URL nhận của bạn.
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
Thông báo đồng bộ hoá luôn có giá trị tiêu đề HTTP X-Goog-Message-Number là 1. Mỗi thông báo tiếp theo của kênh này sẽ có một số thông báo lớn hơn số thông báo trước đó, mặc dù số thông báo sẽ không theo tuần tự.
Gia hạn kênh thông báo
Kênh thông báo có thể có thời gian hết hạn, với một giá trị được xác định theo yêu cầu của bạn hoặc bởi bất kỳ giới hạn nội bộ hoặc mặc định nào của API Lịch Google (hãy sử dụng giá trị có mức hạn chế cao hơn). Thời gian hết hạn của kênh (nếu có) sẽ được đưa vào dưới dạng dấu thời gian Unix (tính bằng mili giây) trong thông tin mà phương thức watch trả về. Ngoài ra, ngày và giờ hết hạn sẽ được đưa vào (ở định dạng mà con người có thể đọc được) trong mọi thông báo thông báo mà ứng dụng của bạn nhận được cho kênh này trong tiêu đề HTTP X-Goog-Channel-Expiration.
Hiện tại, không có cách tự động để gia hạn kênh thông báo. Khi một kênh sắp hết hạn, bạn phải thay thế kênh đó bằng một kênh mới bằng cách gọi phương thức watch. Như thường lệ, bạn phải sử dụng một giá trị duy nhất cho
thuộc tính id của kênh mới. Lưu ý rằng có thể có một khoảng thời gian "trùng lặp" khi 2 kênh thông báo cho cùng một tài nguyên đang hoạt động.
Nhận thông báo
Bất cứ khi nào một tài nguyên đã xem thay đổi, ứng dụng của bạn sẽ nhận được một thông báo mô tả sự thay đổi đó. API Lịch Google gửi những thông báo này dưới dạng yêu cầu HTTPS POST đến URL mà bạn đã chỉ định làm tài sản address cho kênh thông báo này.
Diễn giải định dạng thông báo thông báo
Tất cả các thông báo đều bao gồm một nhóm tiêu đề HTTP có tiền tố X-Goog-.
Một số loại thông báo cũng có thể bao gồm nội dung thông báo.
Tiêu đề
Thông báo do API Lịch Google đăng lên URL nhận của bạn có các tiêu đề HTTP sau đây:
| Đầu trang | Nội dung mô tả |
|---|---|
| Luôn trình bày | |
|
UUID hoặc chuỗi duy nhất khác mà bạn đã cung cấp để xác định kênh thông báo này. |
|
Số nguyên dùng để xác định thông báo này cho kênh
thông báo này. Giá trị luôn là 1 đối với các thông báo sync. Số thông báo tăng lên cho mỗi thông báo tiếp theo trên kênh, nhưng không theo tuần tự. |
|
Một giá trị không rõ ràng xác định tài nguyên được theo dõi. Mã nhận dạng này ổn định trên các phiên bản API. |
|
Trạng thái tài nguyên mới đã kích hoạt thông báo.
Các giá trị có thể là: sync, exists hoặc not_exists.
|
|
Giá trị nhận dạng dành riêng cho phiên bản API của tài nguyên được theo dõi. |
| Thỉnh thoảng trình bày | |
|
Ngày và giờ hết hạn kênh thông báo, được thể hiện ở định dạng mà con người có thể đọc được. Chỉ hiển thị nếu được xác định. |
|
Mã thông báo kênh thông báo do ứng dụng của bạn thiết lập mà bạn có thể dùng để xác minh nguồn thông báo. Chỉ hiển thị nếu được xác định. |
Nội dung thông báo do API Lịch Google đăng lên URL nhận của bạn không có nội dung thông báo. Những thông báo này không chứa thông tin cụ thể về các tài nguyên đã cập nhật. Bạn sẽ cần thực hiện một lệnh gọi API khác để xem toàn bộ thông tin chi tiết về thay đổi.
Ví dụ
Thay đổi nội dung thông báo cho tập hợp sự kiện được sửa đổi:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events X-Goog-Resource-State: exists X-Goog-Message-Number: 10
Trả lời các thông báo
Để cho biết trạng thái đã thành công, bạn có thể trả về bất kỳ mã trạng thái nào sau đây: 200, 201, 202, 204 hoặc 102.
Nếu dịch vụ của bạn dùng thư viện ứng dụng API của Google và trả về 500,502, 503 hoặc 504, thì API Lịch Google sẽ thử lại với thời gian đợi luỹ thừa.
Mọi mã trạng thái trả về khác đều được coi là lỗi thông báo.
Tìm hiểu về sự kiện thông báo của API Lịch Google
Phần này cung cấp thông tin chi tiết về những nội dung thông báo mà bạn có thể nhận được khi sử dụng thông báo đẩy với API Lịch Google.
| Thời điểm gửi | ||
|---|---|---|
sync |
ACL, danh sách Lịch, Sự kiện, Cài đặt. | Đã tạo thành công một kênh mới. Bạn có thể sẽ bắt đầu nhận được thông báo về vấn đề này. |
exists |
ACL, danh sách Lịch, Sự kiện, Cài đặt. | Đã có thay đổi đối với tài nguyên. Những thay đổi có thể có bao gồm việc tạo tài nguyên mới hoặc sửa đổi hoặc xóa tài nguyên hiện có. |
Dừng thông báo
Thuộc tính expiration kiểm soát thời điểm tự động dừng thông báo. Bạn có thể chọn ngừng nhận thông báo về một kênh cụ thể trước khi kênh đó hết hạn bằng cách gọi phương thức stop tại URI sau:
https://www.googleapis.com/calendar/v3/channels/stop
Phương thức này yêu cầu bạn cung cấp ít nhất id và các thuộc tính resourceId của kênh, như trong ví dụ dưới đây. Xin lưu ý rằng nếu API Lịch Google có nhiều loại tài nguyên có phương thức watch, thì chỉ có một phương thức stop.
Chỉ những người dùng có quyền phù hợp mới có thể dừng kênh. Cụ thể:
- Nếu kênh được tạo bằng một tài khoản người dùng thông thường, thì chỉ chính người dùng đó trong cùng một ứng dụng (như được xác định bằng mã ứng dụng khách OAuth 2.0 từ mã thông báo xác thực) tạo kênh mới có thể dừng kênh.
- Nếu kênh được tạo bằng một tài khoản dịch vụ, thì mọi người dùng của cùng ứng dụng đó đều có thể dừng kênh đó.
Mã mẫu sau đây cho biết cách ngừng nhận thông báo:
POST https://www.googleapis.com/calendar/v3/channels/stop
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json
{
"id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
"resourceId": "ret08u3rv24htgh289g"
}