Thông báo tự động

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 cho phép bạn theo dõi các thay đổi trong 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. Tính năng này giúp bạn loại bỏ chi phí mạng và tính toán bổ sung liên quan đến việc thăm dò ý kiến các tài nguyên để xác định xem các tài nguyên đó 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 "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 từng điểm cuối tài nguyên mà bạn muốn giám sát.

    Kênh chỉ định thông tin định tuyến cho 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 một kênh thay đổi, API Thư mục gửi nội dung thông báo dưới dạng POST cho 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 kênh thông báo cho mỗi tài nguyên 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 API Thư mục có thể xem đều có một phương thức watch 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 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 được liên kết với cả một người dùng cụ thể và một tài nguyên cụ thể (hoặc một nhóm tài nguyên). 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ả yêu cầu xem đối với tài nguyên User của một miền đề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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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ả 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 như sau:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Sử dụng các thông số customer và event để chỉ định mã nhận dạng duy nhất cho 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 đã xoá người dùng
  • 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 đã hủy xóa
  • update: sự kiện do người dùng cập nhật

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

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:

  • Chuỗi thuộc tính id xá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 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.

  • 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 Directory API chỉ có thể gửi thông báo đến địa chỉ HTTPS này nếu có chứng chỉ SSL hợp lệ được cài đặt trên máy chủ web của bạn. 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 token chỉ đị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 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 trong ứng dụng dựa trên mục đích của kênh này. Chiều 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-Token trong 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ư tham số truy vấn URL. Ví dụ: forwardTo=hr&createdBy=mobile

    • Đừng đưa dữ liệu nhạy cảm như mã thông báo OAuth vào.

  • 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 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 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 Người dùng 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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ể 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 ngừ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 Người dùng 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, Directory API sẽ gửi một thông báo sync để cho biết rằng thông báo sẽ bắt đầu. Giá trị tiêu đề HTTP X-Goog-Resource-State cho các thư 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ể yên tâm bỏ qua thông báo sync, nhưng 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, 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 để dừng nhận thông báo. Bạn cũng có thể sử dụng thông báo sync để khởi chạy một số hoạt động chuẩn bị cho các sự kiện sau.

Định dạng của thông báo sync mà Directory API gửi đến URL nhận của bạn được hiển thị bên dưới.

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 Thư mục hoặc mặc định (giá trị càng hạn chế sẽ được sử 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) được đưa vào 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 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ị duy nhất cho thuộc tính id của kênh mới. Xin lưu ý rằng có thể 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 thông báo mô tả thay đổi đó. Directory API 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 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 Thư mục gửi lên thiết bị nhận của bạn URL bao gồm các tiêu đề HTTP sau đây:

Tiêu đề Mô tả
Luôn có sẵ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 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ự.
X-Goog-Resource-ID 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.
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ể có: 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 cho tài nguyên được theo dõi.
Thỉnh thoảng xuất hiện
X-Goog-Channel-Expiration 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.
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à mà bạn có thể dùng để 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 duy nhất của tài nguyên người dùng.
etag ETag của nội dung 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:

POST https://mydomain.com/notifications // Your receiving URL.
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 do người dùng xoá:

POST https://mydomain.com/notifications // Your receiving URL.
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 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.

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

Khi sử dụng phương thức này, bạn ít nhất phải cung cấp 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 Directory API có nhiều 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 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 đã tạo kênh đó từ cùng một ứng dụng (như được xác định bằng mã ứng dụng OAuth 2.0 trong mã xác thực) mới có thể dừng kênh.
  • Nếu kênh được tạo bằng tài khoản dịch vụ, thì mọi người dùng trong cùng một ứ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/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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