Tài liệu này mô tả cách sử dụng thông báo đẩy để cung cấp thông tin khi 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 giám sát những thay đổi về 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 của bạn. Loại bỏ mạng thừa và điện toán chi phí liên quan đến việc thăm dò tài nguyên để xác định xem chúng có thay đổi hay không. Bất cứ khi nào tài nguyên được xem thay đổi, API Lịch Google sẽ thông báo cho 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 "webhook" trình nhận lệnh gọi lại.
Chiến dịch này là một máy chủ HTTPS xử lý các nội dung thông báo API được kích hoạt khi tài nguyên thay đổi.
Thiết lập (kênh thông báo) cho mỗi điểm cuối tài nguyên mà bạn muốn đồng hồ.
Một kênh chỉ định thông tin định tuyến cho thông báo tin nhắn. Trong quá trình thiết lập kênh, bạn phải xác định URL cụ thể mà tại đó mà bạn muốn nhận thông báo. Bất cứ khi nào tài nguyên của một kênh thay đổi, API Lịch Google gửi một nội dung thông báo dưới dạng
POSTcho URL đó.
Hiện tại, API Lịch Google hỗ trợ thông báo về những thay đổi đối với các 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 thông báo đẩy, bạn phải thiết lập kênh thông báo cho mỗi tài nguyên bạn muốn theo dõi. Sau khi thiết lập xong các kênh thông báo lên, API Lịch Google sẽ thông báo cho ứng dụng của bạn khi tài nguyên được 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 tại URI có dạng sau:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Để thiết lập kênh thông báo cho thông báo về các thay đổi đối với
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à người dùng cụ thể
một 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 theo dõi những thay đổi đối với bộ sưu tập 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:
-
Chuỗi thuộc tính
idxác định duy nhất thuộc tính này kênh thông báo mới trong dự án của mình. 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ỳ sản phẩm nào tương tự chuỗi duy nhất. Độ dài tối đa: 64 ký tự.Giá trị mã nhận dạng mà bạn đã đặt đượ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. -
Một 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 các thông báo cho kênh thông báo này. Đây là URL gọi lại webhook của bạn và phải sử dụng HTTPS.Xin lưu ý rằng API Lịch Google có thể gửi thông báo tới địa chỉ HTTPS này chỉ khi có cài đặt chứng chỉ SSL hợp lệ trên máy chủ web của bạn. Các 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 phù hợp với mục tiêu tên máy chủ.
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 này bằng
Yêu cầu watch:
-
Thuộc tính
tokenchỉ định một chuỗi tuỳ ý để sử dụng làm mã thông báo kênh. Bạn có thể dùng kênh thông báo mã 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 kênh mà bạn ứng dụng của bạn đã được tạo—để đảm bảo rằng thông báo hiện không được giả mạo—hoặc định tuyến thư đến đúng đích trong đơn đăng ký của bạn 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 của bạn nhận được đối với kênh này.Nếu sử dụng mã thông báo kênh thông báo thì bạn nên:
Sử dụng định dạng mã hoá có thể mở rộng, chẳng hạn như truy vấn URL tham số. 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) của ngày và giờ mà bạn muốn API Lịch Google ngừng gửi tin nhắn cho kênh thông báo này.Nếu một kênh có thời gian hết hạn thì thời gian đó sẽ được thêm vào dưới dạng giá trị của tiêu đề HTTP
X-Goog-Channel-Expiration(ở dạng mà con người có thể đọc được định dạng) trong mỗi nội dung thông báo mà lượt đăng ký nhận được cho kênh này.
Để biết thêm thông tin 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 câu trả lời
Nếu yêu cầu watch tạo thành công một thông báo
thì sẽ trả về mã trạng thái HTTP 200 OK.
Nội dung tin nhắn của phản hồi trên đồng hồ cung cấp thông tin về kênh thông báo bạn vừa tạo, như được 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 những tài sản bạn đã gửi trong yêu cầu,
thông tin trả về cũng bao gồm resourceId và
resourceUri để xác định tài nguyên đang được xem
kênh thông báo.
Bạn có thể chuyển thông tin trả về sang kênh thông báo khác 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ề câu trả lời này, hãy tham khảo 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 gửi một thông báo sync để cho biết rằng
thông báo sẽ bắt đầu. HTTP X-Goog-Resource-State
giá trị tiêu đề cho các thư này là sync. Do mạng
vấn đề về thời gian, có thể nhận được thông báo sync
ngay cả trước khi bạn nhận được phản hồi phương thức watch.
Bạn có thể bỏ qua thông báo sync, nhưng có thể
cũng sử dụng nó. Ví dụ: nếu bạn quyết định không muốn giữ lại
kênh, bạn có thể sử dụng X-Goog-Channel-ID và
X-Goog-Resource-ID giá trị trong lệnh gọi đến
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ố hoạt động khởi chạy nhằm chuẩn bị
các sự kiện sau đó.
Định dạng của sync thông báo mà API Lịch Google gửi đến
URL nhận của bạn được hiển thị dưới đây.
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
Các thông báo đồng bộ hoá luôn có một HTTP X-Goog-Message-Number
giá trị tiêu đề của 1. Mỗi thông báo tiếp theo cho kênh này có
số tin nhắn lớn hơn số trước đó, mặc dù tin nhắn
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 kèm theo một giá trị
được xác định theo yêu cầu của bạn hoặc theo giới hạn nội bộ bất kỳ của API Lịch Google
hoặc mặc định (giá trị càng hạn chế sẽ được sử dụng). Thời hạn của kênh
thời gian, 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 do phương thức watch trả về. Ngoài ra,
ngày và giờ hết hạn (ở định dạng 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 trong
Tiêu đề HTTP X-Goog-Channel-Expiration.
Hiện tại, không có cách tự động nào để gia hạn kênh thông báo. Thời gian
một kênh sắp hết hạn, bạn phải thay thế 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. Xin lưu ý rằng có thể
trở thành sự "trùng lặp" đó là khoảng thời gian mà hai 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 tài nguyên được theo dõi thay đổi, ứng dụng của bạn sẽ nhận được một
nội dung thông báo mô tả thay đổi. API Lịch Google sẽ gửi những thông tin này
thông báo dưới dạng HTTPS POST sẽ yêu cầu URL mà bạn đã chỉ định là
Tài sản address cho thông báo này
của bạn.
Diễn giải định dạng nội dung thông báo
Tất cả thông báo đều bao gồm một tập hợp các 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ư.
Tiêu đề
Nội dung thông báo do API Lịch Google đăng lên địa chỉ email nhận URL bao gồm các tiêu đề HTTP sau đây:
| Tiêu đề | Mô tả |
|---|---|
| Luôn có mặt | |
|
UUID hoặc chuỗi duy nhất khác mà bạn đã cung cấp để xác định điều này kênh thông báo. |
|
Số nguyên xác định thông báo này cho thông báo này
của bạn. Giá trị luôn là 1 cho thông báo sync. Nội dung
cho mỗi tin nhắn tiếp theo trên kênh, nhưng số lượng sẽ tă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ã này là ổ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ể có:
sync, exists hoặc
not_exists.
|
|
Giá trị nhận dạng dành riêng cho phiên bản API cho tài nguyên được theo dõi. |
| Thỉnh thoảng xuất hiện | |
|
Ngày và giờ hết hạn kênh thông báo, được thể hiện bằng ở định dạng mà con người có thể đọc được. Chỉ xuất hiện 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 đặt và mà bạn có thể dùng để xác minh nguồn thông báo. Chỉ hiển thị nếu xác định. |
Các thông báo do API Lịch Google đăng tới URL nhận của bạn không bao gồm 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 đã 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 sử dụng thư viện ứng dụng API của Google
và trả về 500,502, 503 hoặc 504 (API Lịch Google)
thử lại có thời gian đợi luỹ thừa.
Mọi mã trạng thái trả về khác được coi là lỗi thông báo.
Tìm hiểu về các 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ề các 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 gian giao hàng | ||
|---|---|---|
sync |
Danh sách kiểm soát quyền truy cập (ACL), danh sách lịch, sự kiện, chế độ cài đặt. | Đã tạo thành công một kênh mới. Bạn có thể bắt đầu nhận được thông báo về thiết bị đó. |
exists |
Danh sách kiểm soát quyền truy cập (ACL), danh sách lịch, sự kiện, chế độ cài đặt. | Đã có thay đổi đối với một tài nguyên. Những thay đổi có thể xảy ra bao gồm việc tạo tài nguyên mới, sửa đổi hoặc xoá 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 thông báo tự động dừng. Bạn có thể
chọn ngừng nhận thông báo cho một kênh cụ thể trước kênh đó
hết hạn bằng cách gọi phương thức stop lúc
URI sau:
https://www.googleapis.com/calendar/v3/channels/stop
Để sử dụng phương thức này, bạn cần cung cấp ít nhất thông tin
id và các thuộc tính resourceId, như minh hoạ trong
ví dụ bên dưới. Xin lưu ý rằng nếu API Lịch Google có một số loại
các tài nguyên có watch phương thức, 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ởi một tài khoản người dùng thông thường thì chỉ có cùng một tài khoản người dùng từ cùng một ứng dụng khách (như được xác định bằng ID ứng dụng khách OAuth 2.0 từ mã auth) đã tạo kênh có thể khiến kênh đó ngừng hoạt động.
- Nếu kênh được tạo bằng một tài khoản dịch vụ, thì bất kỳ người dùng nào trên kênh đó khách hàng 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"
}