Tài liệu này trình bày một số kỹ thuật mà bạn có thể dùng để cải thiện hiệu suất của ứng dụng. Trong một số trường hợp, các ví dụ từ những API khác hoặc API chung sẽ được dùng để minh hoạ các ý tưởng được trình bày. Tuy nhiên, các khái niệm tương tự cũng áp dụng cho API Google Drive.
Nén bằng gzip
Một cách dễ dàng và thuận tiện để giảm băng thông cần thiết đối với mỗi yêu cầu là bật tính năng nén gzip. Mặc dù việc này đòi hỏi CPU mất thêm thời gian để giải nén kết quả, nhưng thường thì mức tiêu hao này cũng bù trừ với chi phí mạng.
Để nhận được phản hồi được mã hoá sau khi nén gzip, bạn phải thực hiện 2 thao tác: Thiết lập tiêu đề Accept-Encoding và sửa đổi tác nhân người dùng để chứa chuỗi gzip. Sau đây là ví dụ về các tiêu đề HTTP được định dạng đúng cách để bật tính năng nén gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Thao tác với các tài nguyên một phần
Một cách khác để cải thiện hiệu suất của Lệnh gọi API là chỉ gửi và nhận phần dữ liệu mà bạn quan tâm. Điều này giúp ứng dụng của bạn tránh chuyển, phân tích cú pháp và lưu trữ các trường không cần thiết, nhờ đó ứng dụng có thể sử dụng các tài nguyên (bao gồm cả mạng, CPU và bộ nhớ) một cách hiệu quả hơn.
Có 2 loại yêu cầu một phần:
- Phản hồi một phần: Yêu cầu mà bạn chỉ định các trường cần đưa vào phản hồi (sử dụng tham số yêu cầu
fields). - Bản vá: Yêu cầu cập nhật mà bạn chỉ gửi các trường muốn thay đổi (sử dụng động từ HTTP
PATCH).
Thông tin chi tiết hơn về cách đưa ra yêu cầu một phần được cung cấp trong các phần sau.
Phản hồi một phần
Theo mặc định, máy chủ sẽ gửi lại toàn bộ thông tin về một tài nguyên sau khi xử lý các yêu cầu. Để đạt hiệu suất tốt hơn, bạn có thể yêu cầu máy chủ chỉ gửi những trường mà bạn thực sự cần và nhận phản hồi một phần thay vì toàn bộ.
Để yêu cầu phản hồi một phần, hãy sử dụng tham số yêu cầu fields để chỉ định các trường mà bạn muốn trả về. Bạn có thể dùng tham số này với mọi yêu cầu trả về dữ liệu phản hồi.
Xin lưu ý rằng tham số fields chỉ ảnh hưởng đến dữ liệu phản hồi; tham số này không ảnh hưởng đến dữ liệu mà bạn cần gửi (nếu có). Để giảm lượng dữ liệu bạn gửi khi sửa đổi tài nguyên, hãy sử dụng yêu cầu bản vá.
Bản vá (cập nhật một phần)
Bạn cũng có thể tránh gửi dữ liệu không cần thiết khi sửa đổi tài nguyên. Để chỉ gửi dữ liệu đã cập nhật cho các trường cụ thể mà bạn đang thay đổi, hãy sử dụng động từ HTTP PATCH. Ngữ nghĩa bản vá được mô tả trong tài liệu này khác (và đơn giản hơn) so với ngữ nghĩa bản vá của quá trình triển khai GData cũ về tính năng cập nhật một phần.
Ví dụ ngắn gọn dưới đây cho thấy cách sử dụng bản vá giúp giảm thiểu dữ liệu bạn cần gửi để thực hiện một bản cập nhật nhỏ.
Ví dụ:
Xử lý phản hồi cho bản vá
Sau khi xử lý một yêu cầu bản vá hợp lệ, API sẽ trả về mã phản hồi HTTP 200 OK cùng với thông tin đầy đủ về tài nguyên đã sửa đổi. Nếu API sử dụng ETags, thì máy chủ sẽ cập nhật các giá trị ETag khi xử lý thành công một yêu cầu bản vá, giống như khi xử lý PUT.
Yêu cầu bản vá trả về toàn bộ thông tin về tài nguyên, trừ phi bạn sử dụng tham số fields để giảm lượng dữ liệu mà yêu cầu này trả về.
Nếu một yêu cầu bản vá dẫn đến trạng thái tài nguyên mới không hợp lệ về mặt cú pháp hoặc ngữ nghĩa, thì máy chủ sẽ trả về mã trạng thái HTTP 400 Bad Request hoặc 422 Unprocessable Entity và trạng thái tài nguyên vẫn không thay đổi. Ví dụ: nếu bạn cố gắng xoá giá trị của một trường bắt buộc, thì máy chủ sẽ trả về lỗi.
Ký hiệu thay thế khi động từ HTTP PATCH không được hỗ trợ
Nếu tường lửa không cho phép các yêu cầu HTTP PATCH, hãy thực hiện yêu cầu HTTP POST và đặt tiêu đề ghi đè thành PATCH, như minh hoạ bên dưới:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Sự khác biệt giữa bản vá và bản cập nhật
Trên thực tế, khi gửi dữ liệu cho một yêu cầu cập nhật sử dụng động từ HTTP PUT, bạn chỉ cần gửi những trường bắt buộc hoặc không bắt buộc; nếu bạn gửi giá trị cho các trường do máy chủ đặt, thì các giá trị đó sẽ bị bỏ qua. Mặc dù có vẻ như đây là một cách khác để thực hiện bản cập nhật một phần, nhưng phương pháp này có một số điểm hạn chế. Đối với các bản cập nhật sử dụng động từ HTTP PUT, yêu cầu sẽ không thành công nếu bạn không cung cấp các tham số bắt buộc và yêu cầu sẽ xoá dữ liệu đã đặt trước đó nếu bạn không cung cấp các tham số không bắt buộc.
Vì lý do này, bạn nên sử dụng bản vá để đảm bảo an toàn hơn nhiều. Bạn chỉ cung cấp dữ liệu cho các trường mà bạn muốn thay đổi; các trường mà bạn bỏ qua sẽ không bị xoá. Quy tắc này chỉ có một trường hợp ngoại lệ là các phần tử hoặc mảng lặp lại: Nếu bạn bỏ qua tất cả các phần tử hoặc mảng này, chúng sẽ vẫn giữ nguyên; nếu bạn cung cấp bất kỳ phần tử hoặc mảng nào trong số đó, thì toàn bộ tập hợp sẽ được thay thế bằng tập hợp mà bạn cung cấp.
Yêu cầu theo lô (Batch)
Tài liệu này trình bày cách nhóm các lệnh gọi API lại với nhau để giảm số lượng kết nối HTTP mà ứng dụng của bạn phải thực hiện.
Tài liệu này đặc biệt nói về cách đưa ra yêu cầu theo lô bằng cách gửi yêu cầu HTTP. Nếu bạn đang sử dụng thư viện ứng dụng của Google để đưa ra yêu cầu theo lô, hãy xem tài liệu của thư viện ứng dụng.
Tổng quan
Mỗi kết nối HTTP mà ứng dụng của bạn thực hiện đều dẫn đến một lượng chi phí nhất định. API Google Drive hỗ trợ tính năng nhóm theo lô để cho phép ứng dụng của bạn đưa nhiều lệnh gọi API vào một yêu cầu HTTP duy nhất.
Ví dụ về các trường hợp bạn có thể muốn sử dụng tính năng nhóm theo lô:
- Truy xuất siêu dữ liệu cho một số lượng lớn tệp.
- Cập nhật siêu dữ liệu hoặc thuộc tính hàng loạt.
- Thay đổi quyền cho một số lượng lớn tệp, chẳng hạn như thêm người dùng hoặc nhóm mới.
- Đồng bộ hoá dữ liệu ứng dụng cục bộ lần đầu tiên hoặc sau khi ngoại tuyến trong một thời gian dài.
Trong mỗi trường hợp, thay vì gửi từng lệnh gọi riêng biệt, bạn có thể nhóm các lệnh gọi lại với nhau thành một yêu cầu HTTP duy nhất. Tất cả các yêu cầu bên trong phải được gửi đến cùng một API của Google.
Bạn chỉ được thực hiện tối đa 100 lệnh gọi trong một yêu cầu theo lô. Nếu phải thực hiện nhiều lệnh gọi hơn, hãy sử dụng nhiều yêu cầu theo lô.
Lưu ý: Hệ thống xử lý hàng loạt cho API Google Drive sử dụng cùng một cú pháp như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa thì khác.
Các ràng buộc khác bao gồm:
- Yêu cầu theo lô có hơn 100 lệnh gọi có thể gây ra lỗi.
- Có giới hạn 8.000 ký tự về độ dài của URL cho mỗi yêu cầu bên trong.
- Google Drive không hỗ trợ các thao tác theo lô đối với nội dung nghe nhìn, cho dù là tải lên hay tải xuống, hoặc xuất tệp.
Chi tiết gói
Yêu cầu theo lô bao gồm nhiều lệnh gọi API được kết hợp thành một yêu cầu HTTP, có thể được gửi đến batchPath được chỉ định trong tài liệu khám phá API. Đường dẫn mặc định là /batch/api_name/api_version. Phần này mô tả chi tiết cú pháp theo lô; sau đó, có một ví dụ.
Lưu ý: Một tập hợp gồm n yêu cầu được nhóm lại theo lô sẽ được tính vào hạn mức sử dụng của bạn là n yêu cầu, chứ không phải là một yêu cầu. Yêu cầu theo lô được tách thành một tập hợp các yêu cầu trước khi xử lý.
Định dạng của yêu cầu theo lô
Yêu cầu theo lô là một yêu cầu HTTP tiêu chuẩn duy nhất chứa nhiều lệnh gọi API Google Drive, sử dụng loại nội dung multipart/mixed. Trong yêu cầu HTTP chính đó, mỗi phần chứa một yêu cầu HTTP lồng nhau.
Mỗi phần bắt đầu bằng tiêu đề HTTP Content-Type: application/http riêng. Tiêu đề này cũng có thể có tiêu đề Content-ID không bắt buộc. Tuy nhiên, các tiêu đề phần chỉ dùng để đánh dấu phần bắt đầu của phần; chúng tách biệt với yêu cầu lồng nhau. Sau khi máy chủ giải nén yêu cầu theo lô thành các yêu cầu riêng biệt, các tiêu đề phần sẽ bị bỏ qua.
Nội dung của mỗi phần là một yêu cầu HTTP hoàn chỉnh, với động từ, URL, tiêu đề và nội dung riêng. Yêu cầu HTTP chỉ được chứa phần đường dẫn của URL; không được phép sử dụng URL đầy đủ trong yêu cầu theo lô.
Các tiêu đề HTTP cho yêu cầu theo lô bên ngoài, ngoại trừ các tiêu đề Content- như Content-Type, áp dụng cho mọi yêu cầu trong lô. Nếu bạn chỉ định một tiêu đề HTTP nhất định trong cả yêu cầu bên ngoài và một lệnh gọi riêng lẻ, thì giá trị của tiêu đề lệnh gọi riêng lẻ sẽ ghi đè giá trị của tiêu đề yêu cầu theo lô bên ngoài. Các tiêu đề cho một lệnh gọi riêng lẻ chỉ áp dụng cho lệnh gọi đó.
Ví dụ: nếu bạn cung cấp tiêu đề Uỷ quyền cho một lệnh gọi cụ thể, thì tiêu đề đó chỉ áp dụng cho lệnh gọi đó. Nếu bạn cung cấp tiêu đề Uỷ quyền cho yêu cầu bên ngoài, thì tiêu đề đó sẽ áp dụng cho tất cả các lệnh gọi riêng lẻ, trừ phi các lệnh gọi này ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền riêng.
Khi nhận được yêu cầu theo lô, máy chủ sẽ áp dụng các tham số truy vấn và tiêu đề của yêu cầu bên ngoài (nếu thích hợp) cho từng phần, sau đó xử lý từng phần như thể đó là một yêu cầu HTTP riêng biệt.
Phản hồi cho yêu cầu theo lô
Phản hồi của máy chủ là một phản hồi HTTP tiêu chuẩn duy nhất có loại nội dung multipart/mixed; mỗi phần là phản hồi cho một trong các yêu cầu trong yêu cầu theo lô, theo cùng thứ tự như các yêu cầu.
Giống như các phần trong yêu cầu, mỗi phần phản hồi chứa một phản hồi HTTP hoàn chỉnh, bao gồm mã trạng thái, tiêu đề và nội dung. Và giống như các phần trong yêu cầu, mỗi phần phản hồi đều có tiêu đề Content-Type đánh dấu phần bắt đầu của phần.
Nếu một phần nhất định của yêu cầu có tiêu đề Content-ID, thì phần phản hồi tương ứng sẽ có tiêu đề Content-ID khớp, với giá trị ban đầu được đặt trước bằng chuỗi response-, như minh hoạ trong ví dụ sau.
Lưu ý: Máy chủ có thể thực hiện các lệnh gọi của bạn theo bất kỳ thứ tự nào. Đừng tin rằng các lệnh gọi này sẽ được thực thi theo thứ tự mà bạn đã chỉ định. Nếu muốn đảm bảo rằng 2 lệnh gọi xảy ra theo một thứ tự nhất định, bạn không thể gửi các lệnh gọi này trong một yêu cầu duy nhất; thay vào đó, hãy gửi lệnh gọi đầu tiên riêng biệt, sau đó đợi phản hồi cho lệnh gọi đầu tiên trước khi gửi lệnh gọi thứ hai.
Ví dụ:
Ví dụ sau đây minh hoạ cách sử dụng tính năng nhóm theo lô với API Google Drive.
Yêu cầu theo lô mẫu
POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8
{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8
{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--
Phản hồi theo lô mẫu
Đây là phản hồi cho yêu cầu mẫu trong phần trước.
HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "12218244892818058021i" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "04109509152946699072k" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk--
Trả về các trường cụ thể từ yêu cầu
Nếu bạn không chỉ định tham số fields, thì máy chủ sẽ trả về một tập hợp các trường mặc định dành riêng cho phương thức. Ví dụ: phương thức files.list chỉ trả về các trường kind, id, name, và
mimeType.
Các trường mặc định được trả về có thể không phải là những trường bạn cần. Nếu bạn muốn chỉ định
các trường cần trả về trong phản hồi, hãy sử dụng fields tham số
hệ thống.
Để biết thêm thông tin, hãy xem phần Trả về các trường cụ thể.
Đối với tất cả các phương thức của tài nguyên about, comments (ngoại trừ delete) và replies (ngoại trừ delete), bạn phải đặt tham số
fields. Các phương thức này không trả về một tập hợp các trường mặc định.