Tài liệu này trình bày một số kỹ thuật mà bạn có thể sử 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ừ các API khác hoặc API chung đượ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 cho 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 thêm thời gian CPU để giải nén kết quả, nhưng việc đánh đổi với chi phí mạng thường rất đáng giá.
Để nhận được phản hồi được mã hoá gzip, bạn phải làm hai việc: Đặt tiêu đề Accept-Encoding và sửa đổi tác nhân người dùng để chứa chuỗi gzip. Dưới đây là ví dụ về tiêu đề HTTP được tạo đúng cách để bật tính năng nén gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Làm việc với một phần tài nguyê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ờ đó có thể sử dụng tài nguyên (bao gồm cả mạng, CPU và bộ nhớ) hiệu quả hơn.
Có hai 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 mà bạn muốn thay đổi (sử dụng động từ HTTP
PATCH).
Bạn có thể xem thêm thông tin chi tiết về cách gửi yêu cầu một phần 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ộ nội dung đại diện của một tài nguyên sau khi xử lý các yêu cầu. Để đạt được hiệu suất cao hơn, bạn có thể yêu cầu máy chủ chỉ gửi các trường mà bạn thực sự cần và nhận phản hồi một phần.
Để 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 được trả về. Bạn có thể sử dụng tham số này với bất kỳ yêu cầu nào 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á.
Ví dụ:
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ừ PATCH HTTP. Ngữ nghĩa củ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 cách triển khai bản cập nhật một phần cũ của GData.
Ví dụ ngắ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 một 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 nội dung trình bày đầy đủ của tài nguyên đã sửa đổi. Nếu API sử dụng ETag, thì máy chủ sẽ cập nhật các giá trị ETag khi xử lý thành công yêu cầu bản vá, giống như cách xử lý với PUT.
Yêu cầu vá trả về toàn bộ nội dung trình bày 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 yêu cầu vá dẫn đến trạng thái tài nguyên mới không hợp lệ về 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 sẽ không thay đổi. Ví dụ: nếu bạn cố gắng xoá giá trị cho một trường bắt buộc, máy chủ sẽ trả về lỗi.
Chú thích thay thế khi động từ HTTP PATCH không được hỗ trợ
Nếu tường lửa của bạn không cho phép các yêu cầu HTTP PATCH, hãy thực hiện một 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
Trong 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ừ PUT HTTP, 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 trường đó sẽ bị bỏ qua. Mặc dù có vẻ như đây là một cách khác để cập nhật một phần, nhưng phương pháp này có một số hạn chế. Với các bản cập nhật sử dụng động từ PUT HTTP, 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à 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á. Bạn chỉ cung cấp dữ liệu cho những trường mà bạn muốn thay đổi; những trường mà bạn bỏ qua sẽ không bị xoá. Trường hợp ngoại lệ duy nhất đối với quy tắc này xảy ra với 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 đó, thì các phần tử hoặc mảng đó sẽ 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 cho biết cách kết hợp các lệnh gọi API để 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 chủ yếu nói về cách tạo yêu cầu hàng loạt 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 để tạo yêu cầu hàng loạt, hãy xem tài liệu về 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 sẽ dẫn đến một mức hao tổn nhất định. API Google Drive hỗ trợ tính năng tạo yêu cầu hàng loạt để cho phép ứng dụng của bạn đưa một số 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 nên sử dụng tính năng xử lý hàng loạt:
- Truy xuất siêu dữ liệu cho một 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 ở chế độ ngoại tuyến trong 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 chuyển đến cùng một API của Google.
Bạn chỉ được gửi tối đa 100 lệnh gọi trong một yêu cầu hàng loạt. Nếu bạn 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ú pháp giống với hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa lại khác nhau.
Các quy tắ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.
- Mỗi yêu cầu bên trong có giới hạn 8.000 ký tự đối với độ dài URL.
- Google Drive không hỗ trợ thao tác hàng loạt đối với nội dung nghe nhìn, cho dù là tải lên, tải xuống hay xuất tệp.
Chi tiết gói
Yêu cầu hàng loạt bao gồm nhiều lệnh gọi API được kết hợp thành một yêu cầu HTTP. Yêu cầu này 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 xử lý hàng loạt; sau đó, sẽ có một ví dụ.
Lưu ý: Một nhóm các yêu cầu n được gộp lại với nhau sẽ được tính vào hạn mức sử dụng dưới dạng các yêu cầu n, chứ không phải một yêu cầu. Yêu cầu theo lô được tách thành một nhóm 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 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 đều 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. Tệp này cũng có thể có tiêu đề Content-ID không bắt buộc. Tuy nhiên, tiêu đề phần chỉ dùng để đánh dấu phần bắt đầu; các tiêu đề này tách biệt với yêu cầu lồng nhau. Sau khi máy chủ mở gói yêu cầu hàng loạt 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 hàng loạt.
Các tiêu đề HTTP cho yêu cầu hàng loạt 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. 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 đó ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền của riêng chú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 đó coi mỗi phần như một yêu cầu HTTP riêng biệt.
Phản hồi 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 thứ tự tương 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ó một tiêu đề Content-Type ở phía trước để đánh dấu phần bắt đầu.
Nếu một phần nhất định của yêu cầu có tiêu đề Content-ID, thì phần tương ứng của phản hồi sẽ có tiêu đề Content-ID khớp, với giá trị ban đầu đứng trước chuỗi response-, như 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 thứ tự bất kỳ. Đừng tin rằng các lệnh này sẽ được thực thi theo thứ tự mà bạn chỉ định. Nếu muốn đảm bảo rằng hai lệnh gọi xảy ra theo thứ tự nhất định, bạn không thể gửi chúng trong một yêu cầu duy nhất; thay vào đó, hãy gửi lệnh gọi đầu tiên, 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 cho thấy cách sử dụng tính năng xử lý hàng loạt bằng API Google Drive.
Ví dụ về yêu cầu theo lô
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--
Ví dụ về phản hồi hàng loạt
Đâ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, 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 thông số hệ thống fields.
Để 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ả 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.