Thông báo về các thay đổi đối với tài nguyên

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

API Google Drive cung cấp thông báo đẩy để bạn có thể 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. Tính năng này giúp bạn loại bỏ các chi phí bổ sung về mạng và tính toán liên quan đến việc thăm dò tài nguyên để xác định xem 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, API Google Drive 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 thực hiện hai việc:

  • Thiết lập URL nhận hoặc trình nhận 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 từng điểm cuối tài nguyên mà bạn muốn theo dõi.

    Một kênh chỉ định thông tin định tuyến cho thông báo 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 Google Drive 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 Google Drive hỗ trợ thông báo về các thay đổi đối với phương thức files và changes.

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, API Google Drive sẽ thông báo cho ứng dụng của bạn khi có bất kỳ tài nguyên được theo dõi nào thay đổi.

Thực hiện yêu cầu theo dõi

Mỗi tài nguyên API Google Drive 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ề những 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 (hoặc tập hợp 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ụ

Mã mẫu sau đây cho biết cách sử dụng tài nguyên channels để bắt đầu theo dõi các thay đổi đối với một tài nguyên files bằng phương thức files.watch:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

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

  • token để sử dụng làm mã thông báo kênh.
  • Thời gian expiration tính bằng mili giây cho thời gian hết hạn kênh mà bạn yêu cầu.

Mẫu mã sau đây cho biết cách sử dụng tài nguyên channels để bắt đầu theo dõi tất cả changes bằng phương thức changes.watch:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

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

  • token để sử dụng làm mã thông báo kênh.
  • Thời gian expiration tính bằng mili giây cho thời gian hết hạn kênh mà bạn yêu cầu.

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 giá trị nhận dạng duy nhất toàn cầu (UUID) hoặc bất kỳ chuỗi duy nhấ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 lại trong tiêu đề X-Goog-Channel-Id HTTP 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 các 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 Google Drive 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ó chủ đề 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 token chỉ định một giá trị chuỗi tuỳ ý để sử 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ể 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 để đị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. Độ dài tối đa: 256 ký tự.

    Mã thông báo đượ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 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

    • Không đưa dữ liệu nhạy cảm vào, chẳng hạn như mã thông báo OAuth.

  • 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 API Google Drive 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 dưới dạng giá trị của tiêu đề HTTP X-Goog-Channel-Expiration (ở định dạng dễ đọc format) 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 phương thức files và changes trong Tài liệu tham khảo về API.

Phản hồi theo dõ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 theo dõi 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": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

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

  • kind: Xác định đây là tài nguyên kênh API.
  • 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 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 theo dõi 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 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 chi tiết về phản hồi, hãy tham khảo phương thức watch cho các phương thức files và changes trong Tài liệu tham khảo về API.

Thông báo đồng bộ hoá

Sau khi tạo một kênh thông báo để theo dõi một tài nguyên, API Google Drive sẽ gửi một 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 các 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 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ữ kênh, bạn có thể sử dụng các giá trị X-Goog-Channel-ID và X-Goog-Resource-ID trong một 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 động 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à API Google Drive gửi đến URL nhận của bạn được trình bày 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

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

Gia hạn 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ị được xác định bằng yêu cầu của bạn hoặc bằng bất kỳ giới hạn nội bộ nào của API Google Drive hoặc giá trị mặc định (giá trị hạn chế hơn 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 được đưa vào (ở định dạng dễ đọ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 để 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ư mọi khi, 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 "chồng chéo" 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 đó. API Google Drive gửi các thông báo này dưới dạng yêu cầu POST HTTPS đến URL mà bạn đã chỉ định làm thuộc tính address cho kênh thông báo này.

Giải thích định dạng thông báo

Tất cả thông báo đều bao gồm một tập hợp tiêu đề HTTP có X-Goog- tiền tố. Một số loại thông báo cũng có thể bao gồm a nội dung thông báo.

Tiêu đề

Thông báo do API Google Drive đă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 có
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 cho thông báo sync. Số thông báo tăng cho mỗi thông báo tiếp theo trên kênh, nhưng không theo trình 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, add, remove, update, trash, untrash, hoặc change .
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 có
X-Goog-Changed Thông tin bổ sung về các thay đổi. Các giá trị có thể có: content, parents, children, hoặc permissions . Không được cung cấp cùng với thông báo sync.
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 dễ đọc. Chỉ có khi đượ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ể sử dụng để xác minh nguồn thông báo. Chỉ có khi được xác định.

Thông báo cho files và changes trống.

Ví dụ

Thông báo thay đổi cho tài nguyên files, không bao gồm nội dung yêu cầu:

POST https://mydomain.com/notifications
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/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

Thông báo thay đổi cho tài nguyên changes, bao gồm nội dung yêu cầu:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

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ì API Google Drive sẽ thử lại với 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.

Tìm hiểu về các sự kiện thông báo của API Google Drive

Phần này cung cấp thông tin chi tiết về các thông báo mà bạn có thể nhận được khi sử dụng thông báo đẩy với API Google Drive.

X-Goog-Resource-State Áp dụng cho Được gửi khi
sync files, changes Đã tạo thành công một kênh. Bạn có thể bắt đầu nhận thông báo cho kênh đó.
add files Một tài nguyên đã được tạo hoặc chia sẻ.
remove files Một tài nguyên hiện có đã bị xoá hoặc không được chia sẻ.
update files Một hoặc nhiều thuộc tính (siêu dữ liệu) của một tài nguyên đã được cập nhật.
trash files Một tài nguyên đã được chuyển vào thùng rác.
untrash files Một tài nguyên đã bị xoá khỏi thùng rác.
change changes Một hoặc nhiều mục nhật ký thay đổi đã được thêm.

Đối với các sự kiện update, tiêu đề HTTP X-Goog-Changed có thể được cung cấp. Tiêu đề đó chứa một danh sách được phân tách bằng dấu phẩy mô tả các loại thay đổi đã xảy ra.

Loại thay đổi Cho biết
content Nội dung tài nguyên đã được cập nhật.
properties Một hoặc nhiều thuộc tính tài nguyên đã được cập nhật.
parents Một hoặc nhiều tài nguyên mẹ đã được thêm hoặc xoá.
children Một hoặc nhiều tài nguyên con đã được thêm hoặc xoá.
permissions Quyền tài nguyên đã được cập nhật.

Ví dụ về tiêu đề X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

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/drive/v3/channels/stop

Phương thức này yêu cầu bạn cung cấp ít nhất thuộc tính của kênh id và thuộc tính resourceId, như minh hoạ trong ví dụ bên dưới. Xin lưu ý rằng nếu API Google Drive 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 được tạo bởi một tài khoản người dùng thông thường, thì chỉ người dùng đó từ cùng một ứng dụng (được xác định bằng mã ứng dụng OAuth 2.0 từ mã thông báo uỷ quyền) đã tạo kênh mới có thể dừng kênh đó.
  • Nếu kênh được tạo bởi một tài khoản dịch vụ, thì bất kỳ người dùng nào từ 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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