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ừ những 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 Google Drive API.
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á bằng gzip, bạn phải thực hiện 2 việc: Đặt 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)
Làm việ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 các 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 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ó 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 những trường cần đưa vào phản hồi (sử dụng tham số yêu cầu
fields). - Patch: Yêu cầu cập nhật mà bạn chỉ gửi những trường 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 đưa ra 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ộ thông tin về một tài nguyên sau khi xử lý các yêu cầu. Để có 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 được 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ể sử 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 patch.
Ví dụ:
Bản vá (bản 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 mới 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 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 ngữ nghĩa của bản vá trong việc triển khai GData cũ của bản cập nhật một phần.
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 bản vá
Sau khi xử lý một yêu cầu vá hợp lệ, API sẽ trả về mã phản hồi HTTP 200 OK cùng với biểu thị đầ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 một yêu cầu vá, giống như khi xử lý PUT.
Yêu cầu vá sẽ trả về toàn bộ biểu thị 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ề 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 của bạn 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ạ dưới đây:
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 những 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ố hạn chế. 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á. 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á. Ngoại lệ duy nhất đối với quy tắc này là các mảng hoặc phần tử lặp lại: Nếu bạn bỏ qua tất cả các phần tử đó, chúng sẽ vẫn giữ nguyên; nếu bạn cung cấp bất kỳ phần tử nào trong số đó, 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 kết hợp các lệnh gọi API 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ập cụ thể đến việc tạo yêu cầu hàng loạt bằng cách gửi một yêu cầu HTTP. Nếu bạn đang sử dụng một thư viện ứng dụng Google để thực hiện yêu cầu hàng loạt, 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 sẽ dẫn đến một lượng hao tổn nhất định. API Google Drive hỗ trợ việc 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 có thể muố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 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 cục bộ của ứng dụng lần đầu tiên hoặc sau khi ở trạng thái 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 nội bộ 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 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 hàng loạt.
Lưu ý: Hệ thống xử lý hàng loạt cho Google Drive API 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:
- Các 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ự cho độ dài của URL.
- Google Drive không hỗ trợ các 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 duy nhất. 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 theo lô; 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 sẽ được tính vào hạn mức sử dụng của bạn 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 tiêu chuẩn duy nhất chứa nhiều lệnh gọi Google Drive API, 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. Ngoài ra, bạn cũng có thể thêm 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 đầ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ủ mở gói yêu cầu hàng loạt thành các yêu cầu riêng biệt, 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 các yêu cầu hàng loạt.
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 hàng loạt bên ngoài. Tiêu đề của một cuộc gọi riêng lẻ chỉ áp dụng cho cuộc gọi đó.
Ví dụ: nếu bạn cung cấp một 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 một 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 đề này 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 đó coi từng phần như thể đó là 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ó kiểu 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ự với 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. 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 phản hồi tương ứng sẽ có tiêu đề Content-ID phù hợ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 bất kỳ thứ tự nào. Đừng mong đợi các thao tác này đượ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 một 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 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ạ việc sử dụng tính năng xử lý hàng loạt với Google Drive API.
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 ví dụ 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 nhóm trường mặc định dành riêng cho phương thức này. 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 những 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 mặc định gồm các trường.