Thông báo đẩy

Tài liệu này mô tả cách sử dụng thông báo đẩy để thông báo cho ứng dụng của bạn khi một tài nguyên thay đổi.

Tổng quan

Directory API cung cấp thông báo đẩy để bạn có thể theo dõi các 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. API này giúp bạn loại bỏ các chi phí bổ sung về mạng và điện toán 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 một tài nguyên được theo dõi thay đổi, Directory API 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 hai 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ý các thông báo API được kích hoạt khi một 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 theo dõi.
Kênh chỉ định thông tin định tuyến cho các 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, Directory API sẽ gửi một thông báo dưới dạng yêu cầu POST đến URL đó.

Hiện tại, Directory API hỗ trợ thông báo về những thay đổi đối với tài nguyên Người dùng.

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 một kênh thông báo cho từng tài nguyên mà bạn muốn theo dõi. Sau khi bạn thiết lập các kênh thông báo, Directory API sẽ thông báo cho ứng dụng của bạn khi có bất kỳ tài nguyên nào được theo dõi thay đổi.

Đưa ra yêu cầu xem

Mỗi tài nguyên Directory API có thể theo dõi đều có một phương thức watch được liên kết tại một URI có dạng như 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ề 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 đều được liên kết với một người dùng cụ thể và một tài nguyên (hoặc một 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 hoặc tài khoản dịch vụ sở hữu hoặc có quyền truy cập vào tài nguyên này.

Ví dụ

Tất cả các yêu cầu theo dõi đối với tài nguyên User cho một miền duy nhất đều có dạng chung:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Trong nội dung yêu cầu, hãy cung cấp id kênh của bạn, type dưới dạng web_hook và URL nhận của bạn trong address. Bạn cũng có thể cung cấp (không bắt buộc):

Một token để dùng làm mã thông báo kênh.
ttl trong params để yêu cầu thời gian tồn tại cho kênh này tính bằng giây.

Sử dụng các thông số domain và event để chỉ định miền và loại sự kiện mà bạn muốn nhận thông báo.

Tất cả các yêu cầu theo dõi đối với tài nguyên Người dùng của một khách hàng đều có dạng chung:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Sử dụng các tham số customer và event để chỉ định mã nhận dạng duy nhất của Tài khoản Google của khách hàng và loại sự kiện mà bạn muốn nhận thông báo.

Các giá trị có thể có cho event là:

add: sự kiện do người dùng tạo
delete: sự kiện người dùng đã xoá
makeAdmin: sự kiện thay đổi trạng thái quản trị viên người dùng
undelete: sự kiện người dùng xoá
update: sự kiện người dùng đã cập nhật

Lưu ý: Các ví dụ sau đây bỏ qua phần nội dung yêu cầu để cho rõ ràng.

Theo dõi các sự kiện do người dùng tạo cho miền mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Theo dõi các sự kiện do người dùng tạo cho khách hàng my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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 id giúp xác định duy nhất kênh thông báo mới này trong dự án của bạn. Bạn nên sử dụng mã nhận dạng riêng biệt trên toàn cầu (UUID) hoặc bất kỳ chuỗi riêng biệt tương tự nào. Độ dài tối đa: 64 ký tự.

Giá trị mã nhận dạng mà bạn đặt sẽ được phản hồi trong tiêu đề HTTP X-Goog-Channel-Id của mọi thông báo mà bạn nhận được cho kênh này.
Một chuỗi thuộc tính type được đặt thành giá trị web_hook.
Một chuỗi thuộc tính address được đặt thành URL lắng 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 của bạn và phải sử dụng HTTPS.

Xin lưu ý rằng Directory API chỉ có thể gửi thông báo đến địa chỉ HTTPS này nếu bạn đã cài đặt mộ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ó chủ đề không khớp với tên máy chủ đí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:

Một thuộc tính token chỉ đị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 thông báo cho nhiều mục đích. Ví dụ: bạn có thể dùng mã thông báo này để xác minh rằng mỗi thông báo đến là dành cho một kênh mà ứng dụng của bạn đã tạo – để đảm bảo thông báo không bị giả mạo – hoặc để định tuyế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ó trong tiêu đề HTTP X-Goog-Channel-Token trong mọi thông báo mà ứng dụng của bạn 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 một định dạng mã hoá có thể mở rộng, chẳng hạn như các tham số truy vấn URL. Ví dụ: forwardTo=hr&createdBy=mobile
- Đừng thêm dữ liệu nhạy cảm như mã thông báo OAuth.
Lưu ý: Nếu bạn phải gửi dữ liệu có độ nhạy cao, hãy đảm bảo dữ liệu đó được mã hoá trước khi thêm vào mã thông báo.
Một 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 Directory API 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ì thời gian đó sẽ được đưa vào làm giá trị của tiêu đề X-Goog-Channel-Expiration HTTP (ở đị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 này, hãy tham khảo phương thức watch cho tài nguyên Users trong Tài liệu tham khảo về API.

Xem câu trả lờ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ã trạng thái HTTP 200 OK.

Nội dung thông báo của phản hồi watch cung cấp thông tin về kênh thông báo mà bạn vừa tạo, như minh hoạ trong ví dụ bên dưới.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

Nội dung phản hồi cung cấp thông tin chi tiết về kênh, chẳng hạn như:

id: Mã nhận dạng mà bạn chỉ định cho kênh này.
resourceId: Mã nhận dạng của tài nguyên được theo dõi.
resourceUri: Mã nhận dạng dành riêng cho phiên bản của tài nguyên được theo dõi.
token: Mã thông báo được cung cấp trong nội dung yêu cầu.
expiration: Thời gian hết hạn của kênh dưới dạng dấu thời gian Unix tính bằng mili giây.

Ngoài các thuộc tính mà bạn đã gửi trong yêu cầu, 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.

Lưu ý: Thuộc tính resourceId là một giá trị nhận dạng ổn định, độc lập với phiên bản của tài nguyên. Thuộc tính resourceUri là URI chuẩn của tài nguyên được theo dõi trong bối cảnh của phiên bản API hiện tại, vì vậy, thuộc tính này dành riêng cho phiên bản.

Bạn có thể truyền thông tin được trả về cho các thao tác khác trên kênh thông báo, chẳng hạn như khi bạn muốn dừng nhận thông báo.

Để biết thêm thông tin chi tiết về phản hồi, hãy tham khảo phương thức watch cho tài nguyên Users trong Tài liệu tham khảo API.

Đồng bộ hoá thư

Sau khi bạn tạo một kênh thông báo để theo dõi một tài nguyên, Directory API sẽ gửi một thông báo sync để cho biết 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 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 phương thức watch.

Bạn có thể bỏ qua thông báo sync mà không gặp vấn đề gì, 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ữ kênh này, 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 đến dừng nhận thông báo. Bạn cũng có thể dùng thông báo sync để thực hiện một số thao tác khởi tạo nhằm chuẩn bị cho các sự kiện sau này.

Định dạng của thông báo sync mà Directory API gửi đến URL nhận của bạn được trình bày 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

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 cho kênh này có số thông báo lớn hơn số thông báo trước đó, mặc dù các số thông báo sẽ không theo thứ tự.

Làm mới kênh thông báo

Một kênh thông báo có thể có thời gian hết hạn, với giá trị do yêu cầu của bạn hoặc bất kỳ giới hạn hoặc giá trị mặc định nội bộ nào của Directory API xác định (giá trị hạn chế hơn sẽ được dùng). Thời gian hết hạn của kênh (nếu có) đượ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 mà con người có thể đọc được) sẽ được đưa vào 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 nào 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ị riêng biệt cho thuộc tính id của kênh mới. Xin lưu ý rằng có thể sẽ có một khoảng thời gian "trùng lặp" khi 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 một tài nguyên được theo dõi thay đổi, ứng dụng của bạn sẽ nhận được một thông báo mô tả sự thay đổi đó. Directory API gửi các 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 thuộc tính address cho kênh thông báo này.

Lưu ý: Yêu cầu HTTPS gửi thông báo chỉ định tác nhân người dùng là APIs-Google và tuân theo chỉ thị robots.txt, như mô tả trong phần Tác nhân người dùng của API Google.

Diễn giải định dạng thông báo

Tất cả thông báo đều có 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ể có phần nội dung thông báo.

Tiêu đề

Thông báo do Directory API đăng lên URL nhận của bạn bao gồm các tiêu đề HTTP sau:

Tiêu đề	Mô tả
Luôn xuất hiện
`X-Goog-Channel-ID`	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.
`X-Goog-Message-Number`	Số nguyên 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ứ tự của tin nhắn tăng lên cho mỗi tin nhắn tiếp theo trên kênh, nhưng không theo thứ tự liên tiếp.
`X-Goog-Resource-ID`	Một giá trị mờ 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.
`X-Goog-Resource-State`	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` hoặc tên sự kiện.
`X-Goog-Resource-URI`	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.
Đôi khi xuất hiện
`X-Goog-Channel-Expiration`	Ngày và giờ hết hạn của kênh thông báo, được biểu thị ở định dạng mà con người có thể đọc được. Chỉ xuất hiện nếu được xác định.
`X-Goog-Channel-Token`	Mã thông báo kênh thông báo do ứng dụng của bạn đặt và bạn có thể dùng mã này để xác minh nguồn thông báo. Chỉ xuất hiện nếu được xác định.

Thông báo cho người dùng chứa những thông tin sau trong phần nội dung yêu cầu:

Thuộc tính	Mô tả
`kind`	Xác định đây là một tài nguyên Người dùng. Giá trị: chuỗi cố định "`admin#directory#user`".
`id`	Giá trị nhận dạng riêng biệt của tài nguyên người dùng.
`etag`	ETag của thông báo. Khác với ETag của tài nguyên Người dùng.
`primaryEmail`	Địa chỉ email chính của người dùng.

Ví dụ

Thông báo cho các sự kiện tài nguyên User có dạng chung như sau:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Ví dụ về sự kiện người dùng đã xoá:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

Trả lời các thông báo

Để cho biết 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, thì Directory API sẽ thử lại bằng thuật toán tăng thời gian chờ theo cấp số nhân. Mọi mã trạng thái trả về khác đều được coi là lỗi thông báo.

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 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/admin/directory_v1/channels/stop

Phương thức này yêu cầu bạn cung cấp ít nhất các thuộc tính id và resourceId của kênh, như minh hoạ trong ví dụ bên dưới. Xin lưu ý rằng nếu Directory API 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 một kênh. Cụ thể:

Nếu kênh do một tài khoản người dùng thông thường tạo, thì chỉ người dùng đó trên cùng một ứng dụng (được xác định bằng mã ứng dụng OAuth 2.0 trong 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 trong cùng một ứng dụng khách đề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/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}

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

Tạo kênh thông báo

Đưa ra yêu cầu xem

Ví dụ

Thuộc tính bắt buộc

Thuộc tính tuỳ chọn

Xem câu trả lời

Đồng bộ hoá thư

Làm mới kênh thông báo

Nhận thông báo

Diễn giải định dạng thông báo

Tiêu đề

Ví dụ

Trả lời các thông báo

Dừng thông báo

Thông báo đẩy