Trang này được dịch bởi Cloud Translation API.

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 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. 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, 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 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ý thông báo API được kích hoạt khi một 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 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 nào được theo dõi thay đổi.

Tạo yêu cầu xem

Mỗi tài nguyên API Google Drive có thể xem được đề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ừ khi 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Mã mẫu 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and 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 id 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 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 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.
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 theo dõi 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 bạn đã cài đặt chứng chỉ SSL hợp lệ trên máy chủ web. 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 này bằng yêu cầu watch:

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ể 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. Chiều 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 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.
Lưu ý: Nếu bạn phải gửi dữ liệu cực kỳ nhạy cảm, hãy đảm bảo dữ liệu đó được mã hoá trước khi thêm vào mã thông bá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 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 này sẽ được đưa vào làm 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.

Lưu ý: Đối với API Google Drive, thời gian hết hạn tối đa là 86400 giây (1 ngày) sau thời gian hiện tại đối với tài nguyên files và 604800 giây (1 tuần) đối với changes. Nếu bạn không đặt thuộc tính expiration trong yêu cầu, thì thời gian hết hạn mặc định là 3600 giây sau thời gian hiện tại.

Để 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 API.

Phản hồi trên đồng hồ

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 xem cung cấp thông tin về kênh thông báo bạn vừa tạo, như trong ví dụ bên dưới.

{
  "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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

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 cho tài nguyên. Thuộc tính resourceUri là URI chuẩn của tài nguyên được theo dõi trong ngữ 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 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 phương thức files và changes trong Tài liệu tham khảo API.

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

Sau khi tạo kênh thông báo để theo dõi một tài nguyên, API Google Drive 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 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 để thực hiện một số hoạt động 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 các thông báo sync mà API Google Drive gửi tới URL nhậ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

Các 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ự.

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 theo yêu cầu của bạn hoặc theo mọi giới hạn nội bộ hoặc giá trị mặc định của API Google Drive (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ó) 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 (ở đị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ư 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 "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 đó. 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.

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

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ô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ó 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`. Số tin nhắn tăng lên cho mỗi tin nhắn tiếp theo trên kênh, nhưng các số này không theo thứ tự.
`X-Goog-Resource-ID`	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ó thể dùng các giá trị sau: `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 cho tài nguyên được theo dõi.
Đôi khi có
`X-Goog-Changed`	Thông tin bổ sung về những thay đổi này. Có thể dùng các giá trị: `content`, `parents`, `children` hoặc `permissions`. Không được cung cấp 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 thể hiện ở đị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 để 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 files và changes đang 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 // 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/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 cả phần nội dung yêu cầu:

POST https://mydomain.com/notifications // Your receiving URL.
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 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, thì API Google Drive 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.

Tìm hiểu về 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 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 Google Drive.

X-Goog-Resource-State	Áp dụng cho	Thời gian giao hàng
`sync`	`files`, `changes`	Đã tạo thành công kênh. Bạn có thể bắt đầu nhận được thông báo về thiết bị đó.
`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 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`	Thêm một hoặc nhiều mục nhật ký thay đổi.

Đố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`	Đã cập nhật quyền đối với tài nguyên.

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 các thuộc tính id và resourceId của kênh, như minh hoạ trong ví dụ dưới đây. Xin lưu ý rằng nếu API Google Drive có một số loại tài nguyên có phương thức watch, thì sẽ 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 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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