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

Cải thiện hiệu suất

Tài liệu này đề cập đến 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, ví dụ từ các API khác hoặc API chung được sử dụng để minh hoạ các ý tưởng đã trình bày. Tuy nhiên, các khái niệm tương tự có thể á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 chức năng nén gzip. Mặc dù phương pháp này yêu cầu thêm thời gian của 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 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ề các tiêu đề HTTP được định dạng đúng để bật chức 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. Việc này giúp ứng dụng tránh được việc 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ể dùng tài nguyên bao gồm mạng, CPU và bộ nhớ một cách hiệu quả hơn.

Có hai loại yêu cầu từng phần:

Phản hồi một phần: Một 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 (Bản vá): Yêu cầu cập nhật trong đó 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 thực hiện 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ủ gửi lại bản trình bày đầy đủ của tài nguyên sau khi xử lý yêu cầu. Để đạt được hiệu suất tốt hơn, bạn có thể yêu cầu máy chủ chỉ gửi các trường 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 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 chứ 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ụ:

Ví dụ sau đây cho thấy việc sử dụng tham số fields với API "Bản minh hoạ" chung chung (hư cấu).

Yêu cầu đơn giản: Yêu cầu HTTP GET này bỏ qua tham số fields và trả về toàn bộ tài nguyên.

https://www.googleapis.com/demo/v1

Phản hồi đầy đủ cho tài nguyên: Dữ liệu tài nguyên đầy đủ bao gồm các trường sau đây, cùng với nhiều trường khác đã bị bỏ qua cho ngắn gọn.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Yêu cầu phản hồi một phần: Yêu cầu sau đây cho chính tài nguyên này sử dụng tham số fields để giảm đáng kể lượng dữ liệu được trả về.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Phản hồi một phần: Để phản hồi yêu cầu trên, máy chủ sẽ gửi lại một phản hồi chỉ chứa thông tin về loại cùng với một mảng các mục được rút gọn chỉ bao gồm thông tin về tiêu đề HTML và độ dài trong mỗi mục.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Lưu ý rằng phản hồi là một đối tượng JSON chỉ bao gồm các trường đã chọn và đối tượng mẹ chứa các trường đó.

Tiếp theo, bạn sẽ thấy thông tin chi tiết về cách định dạng tham số fields, tiếp đó là thông tin chi tiết về nội dung được trả về chính xác trong phản hồi.

Tóm tắt cú pháp tham số trường

Định dạng của giá trị tham số yêu cầu fields dựa trên cú pháp XPath. Cú pháp được hỗ trợ được tóm tắt bên dưới và các ví dụ khác được cung cấp trong phần sau.

Sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường.
Sử dụng a/b để chọn một trường b được lồng trong trường a; sử dụng a/b/c để chọn một trường c lồng trong b.

Ngoại lệ: Đối với phản hồi API sử dụng trình bao bọc "data", trong đó phản hồi được lồng trong đối tượng data giống như data: { ... }, đừng thêm "data" vào thông số kỹ thuật fields. Việc thêm đối tượng dữ liệu có thông số kỹ thuật của trường như data/a/b sẽ gây ra lỗi. Thay vào đó, chỉ sử dụng thông số kỹ thuật fields như a/b.
Sử dụng trình chọn phụ để yêu cầu một tập hợp các trường phụ cụ thể của các mảng hoặc đối tượng bằng cách đặt biểu thức trong dấu ngoặc đơn "( )".
Ví dụ: fields=items(id,author/email) chỉ trả về mã mặt hàng và email của tác giả cho từng phần tử trong mảng items. Bạn cũng có thể chỉ định một trường phụ, trong đó fields=items(id) tương đương với fields=items/id.
Sử dụng ký tự đại diện trong các lựa chọn trường, nếu cần.
Ví dụ: fields=items/pagemap/* chọn tất cả đối tượng trong sơ đồ trang.

Ví dụ khác về cách sử dụng thông số trường

Các ví dụ bên dưới bao gồm nội dung mô tả về cách giá trị tham số fields ảnh hưởng đến phản hồi.

Lưu ý: Giống như tất cả các giá trị tham số truy vấn, giá trị tham số fields phải là URL được mã hoá. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ qua phương thức mã hoá.

Xác định các trường bạn muốn được trả về hoặc chọn trường.

Giá trị tham số yêu cầu fields là một danh sách các trường được phân tách bằng dấu phẩy và mỗi trường được chỉ định tương ứng với gốc của phản hồi. Do đó, nếu bạn đang thực hiện thao tác danh sách, phản hồi là một tập hợp và thường bao gồm một mảng tài nguyên. Nếu bạn đang thực hiện thao tác trả về một tài nguyên, thì các trường sẽ được chỉ định tương ứng với tài nguyên đó. Nếu trường bạn chọn là (hoặc là một phần của) một mảng, thì máy chủ sẽ trả về phần đã chọn trong số tất cả các phần tử trong mảng đó.

Dưới đây là một số ví dụ ở cấp bộ sưu tập:

Ví dụ	Hiệu quả
`items`	Trả về tất cả phần tử trong mảng items, bao gồm tất cả các trường trong mỗi phần tử, ngoại trừ các trường khác.
`etag,items`	Trả về cả trường `etag` và tất cả các phần tử trong mảng items.
`items/title`	Chỉ trả về trường `title` cho tất cả phần tử trong mảng items. Mỗi khi một trường lồng nhau được trả về, phản hồi sẽ bao gồm các đối tượng mẹ chứa các đối tượng mẹ. Các trường mẹ không bao gồm bất kỳ trường con nào khác trừ phi chúng được chọn rõ ràng.
`context/facets/label`	Chỉ trả về trường `label` cho mọi thành phần của mảng `facets`. Mảng này được lồng trong đối tượng `context`.
`items/pagemap/*/title`	Đối với mỗi phần tử trong mảng items, chỉ trả về trường `title` (nếu có) của mọi đối tượng là phần tử con của `pagemap`.

Dưới đây là một số ví dụ ở cấp tài nguyên:

Ví dụ	Hiệu quả
`title`	Trả về trường `title` của tài nguyên được yêu cầu.
`author/uri`	Trả về trường phụ `uri` của đối tượng `author` trong tài nguyên được yêu cầu.
`links/*/href`	Trả về trường `href` của mọi đối tượng là phần tử con của `links`.

Chỉ yêu cầu các phần của các trường cụ thể bằng cách sử dụng lựa chọn phụ.

Theo mặc định, nếu yêu cầu của bạn chỉ định các trường cụ thể, thì máy chủ sẽ trả về toàn bộ các đối tượng hoặc phần tử mảng. Bạn có thể chỉ định một phản hồi chỉ bao gồm các trường phụ nhất định. Bạn thực hiện việc này bằng cách sử dụng cú pháp lựa chọn phụ "( )", như trong ví dụ bên dưới.

Ví dụ:	Hiệu quả
`items(title,author/uri)`	Chỉ trả về các giá trị của `title` và `uri` của tác giả cho từng phần tử trong mảng items.

Xử lý phản hồi một phần

Sau khi xử lý một yêu cầu hợp lệ chứa tham số truy vấn fields, máy chủ sẽ gửi lại một mã trạng thái HTTP 200 OK, cùng với dữ liệu được yêu cầu. Nếu tham số truy vấn fields có lỗi hoặc không hợp lệ, máy chủ sẽ trả về một mã trạng thái HTTP 400 Bad Request, kèm theo thông báo lỗi cho người dùng biết đã xảy ra sự cố gì với lựa chọn của họ trong các trường (ví dụ: "Invalid field selection a/b").

Dưới đây là ví dụ về câu trả lời một phần được hiển thị trong phần giới thiệu ở trên. Yêu cầu này dùng tham số fields để chỉ định những trường cần trả về.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Phản hồi một phần sẽ có dạng như sau:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Lưu ý: Đối với các API hỗ trợ tham số truy vấn để phân trang dữ liệu (ví dụ: maxResults và nextPageToken), hãy sử dụng các tham số đó để giảm kết quả của mỗi truy vấn xuống kích thước có thể quản lý được. Nếu không, mức tăng hiệu suất có thể có với phản hồi một phần có thể không được thực hiện.

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 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 trong quá trình triển khai bản cập nhật một phần GData cũ.

Ví dụ ngắn dưới đây cho thấy cách sử dụng bản vá để giảm thiểu dữ liệu bạn cần gửi nhằm thực hiện một bản cập nhật nhỏ.

Ví dụ:

Ví dụ này cho thấy một yêu cầu bản vá đơn giản chỉ cập nhật tiêu đề của tài nguyên API "Bản minh hoạ" chung chung (hư cấu). Tài nguyên này cũng có một nhận xét, một tập hợp đặc điểm, trạng thái và nhiều trường khác, nhưng yêu cầu này chỉ gửi trường title vì đó là trường duy nhất đang được sửa đổi:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Phản hồi:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Máy chủ sẽ trả về mã trạng thái 200 OK cùng với bản trình bày đầy đủ của tài nguyên đã cập nhật. Vì chỉ có trường title được đưa vào yêu cầu bản vá, nên đó là giá trị duy nhất khác với trước đây.

Lưu ý: Nếu sử dụng tham số fields phản hồi một phần kết hợp với bản vá, thì bạn có thể tăng hiệu quả của các yêu cầu cập nhật hơn nữa. Yêu cầu bản vá chỉ làm giảm kích thước của yêu cầu. Phản hồi một phần sẽ làm giảm kích thước của phản hồi. Vì vậy, để giảm lượng dữ liệu được gửi theo cả hai hướng, hãy sử dụng yêu cầu bản vá có tham số fields.

Ngữ nghĩa của yêu cầu bản vá

Phần nội dung của yêu cầu về bản vá chỉ bao gồm các trường tài nguyên bạn muốn sửa đổi. Khi chỉ định một trường, bạn phải bao gồm mọi đối tượng mẹ chứa mọi đối tượng mẹ, giống như khi các đối tượng mẹ đính kèm được trả về với phản hồi một phần. Dữ liệu đã sửa đổi mà bạn gửi sẽ được hợp nhất vào dữ liệu cho đối tượng mẹ, nếu có.

Thêm: Để thêm một trường chưa tồn tại, hãy chỉ định trường mới và giá trị của trường đó.
Sửa đổi: Để thay đổi giá trị của một trường hiện có, hãy chỉ định trường đó và đặt thành giá trị mới.
Xoá: Để xoá một trường, hãy chỉ định trường đó rồi đặt thành null. Ví dụ: "comment": null. Bạn cũng có thể xoá toàn bộ đối tượng (nếu đối tượng đó có thể thay đổi) bằng cách đặt đối tượng đó thành null. Nếu bạn đang dùng Thư viện ứng dụng API Java, hãy dùng Data.NULL_STRING; để biết thông tin chi tiết, hãy xem phần JSON rỗng.

Lưu ý về mảng: Các yêu cầu bản vá chứa mảng sẽ thay thế mảng hiện có bằng mảng bạn cung cấp. Bạn không thể sửa đổi, thêm hoặc xoá các mục trong một mảng theo cách từng phần.

Sử dụng bản vá trong chu kỳ đọc-sửa đổi-ghi

Đây có thể là một phương pháp hữu ích để bắt đầu bằng cách truy xuất một phần phản hồi chứa dữ liệu bạn muốn sửa đổi. Điều này đặc biệt quan trọng đối với những tài nguyên sử dụng ETag, vì bạn phải cung cấp giá trị ETag hiện tại trong tiêu đề HTTP If-Match để cập nhật tài nguyên thành công. Sau khi nhận được dữ liệu, bạn có thể sửa đổi các giá trị mình muốn thay đổi rồi gửi lại bản trình bày một phần đã sửa đổi bằng yêu cầu vá. Dưới đây là ví dụ giả định rằng tài nguyên Minh hoạ sử dụng ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Đây là câu trả lời một phần:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Yêu cầu bản vá sau đây là dựa trên phản hồi đó. Như hiển thị bên dưới, mã này cũng sử dụng tham số fields để giới hạn dữ liệu được trả về trong phản hồi của bản vá:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Máy chủ phản hồi bằng mã trạng thái HTTP 200 OK và đại diện một phần tài nguyên đã cập nhật:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Trực tiếp tạo yêu cầu về bản vá

Đối với một số yêu cầu vá, bạn cần dựa vào dữ liệu mà bạn đã truy xuất trước đó. Ví dụ: nếu bạn muốn thêm một mục vào một mảng và không muốn mất bất kỳ phần tử hiện có nào của mảng, trước tiên bạn phải lấy dữ liệu hiện có. Tương tự, nếu một API sử dụng ETag, bạn cần gửi giá trị ETag trước đó cùng với yêu cầu của mình để cập nhật tài nguyên thành công.

Lưu ý: Bạn có thể sử dụng tiêu đề HTTP "If-Match: *" để buộc thực hiện bản vá khi đang sử dụng ETag. Nếu làm như vậy, thì bạn không cần đọc trước khi ghi.

Tuy nhiên đối với các trường hợp khác, bạn có thể tạo yêu cầu bản vá trực tiếp mà không cần truy xuất trước dữ liệu hiện có. Ví dụ: bạn có thể dễ dàng thiết lập yêu cầu bản vá để cập nhật một trường thành một giá trị mới hoặc thêm một trường mới. Dưới đây là ví dụ:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Với yêu cầu này, nếu trường nhận xét đã có một giá trị, thì giá trị mới sẽ ghi đè giá trị đó; nếu không, giá trị sẽ được đặt thành giá trị mới. Tương tự, nếu có một đặc điểm khối lượng, giá trị của nó sẽ bị ghi đè; nếu không, đặc điểm đó sẽ được tạo. Trường chính xác (nếu được đặt) sẽ bị xoá.

Xử lý phản hồi cho bản vá

Sau khi xử lý yêu cầu bản vá hợp lệ, API sẽ trả về một mã phản hồi HTTP 200 OK cùng với thông tin biểu thị đầy đủ về tài nguyên đã sửa đổi. Nếu API được sử dụng ETag, 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ư với PUT.

Yêu cầu bản vá sẽ trả về toàn bộ biểu diễn tài nguyên trừ phi bạn sử dụng tham số fields để giảm lượng dữ liệu trả về.

Nếu 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ị cho trường bắt buộc, máy chủ sẽ trả về lỗi.

Ký hiệu thay thế khi động từ PATCH HTTP không được hỗ trợ

Nếu tường lửa của bạn không cho phép 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ư thể hiện 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

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ừ 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 trường đó sẽ bị bỏ qua. Mặc dù đây có vẻ 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 những 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, đồng thời 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, nên sẽ an toàn hơn nhiều nếu bạn sử dụng bản vá. Bạn chỉ cung cấp dữ liệu cho những trường bạn muốn thay đổi; những trường bạn bỏ qua sẽ không bị xoá. Ngoại lệ duy nhất của 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 đó, 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ố đó, 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ô

Tài liệu này cho biết cách gộ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 trình bày cụ thể về việc tạo yêu cầu hàng loạt bằng cách gửi yêu cầu HTTP. Thay vào đó, nếu bạn đang sử dụng thư viện ứng dụng của Google để gửi 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 thực hiện sẽ dẫn đến một mức hao tổn nhất định. API Google Drive hỗ trợ xử lý hàng loạt để cho phép ứng dụng khách của bạn đưa nhiều lệnh gọi API vào một yêu cầu HTTP.

Ví dụ về các trường hợp mà bạn có thể cần sử dụng tính năng phân 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 tài sản hàng loạt.
Thay đổi quyền đối với một số lượng lớn tệp, chẳng hạn như thêm một 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 không có kết nối mạng trong một thời gian dài.

Trong từng trường hợp, thay vì gửi riêng từng lệnh gọi, bạn có thể nhóm các lệnh gọi lại 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 đi tới cùng một API Google.

Bạn chỉ có thể sử dụng 100 lệnh gọi trong một yêu cầu theo lô. Nếu bạn cần thực hiện nhiều lệnh gọi hơn con số đó, 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 API Google Drive sử dụng cú pháp giống như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa khác nhau.

Lưu ý: Các yêu cầu theo lô có hơn 100 lệnh gọi có thể dẫn đến lỗi.

Lưu ý: Mỗi yêu cầu bên trong có giới hạn độ dài URL là 8.000 ký tự.

Lưu ý: Hiện tại, Google Drive không hỗ trợ các thao tác hàng loạt đối với nội dung nghe nhìn, dù là tải lên hoặc tải xuống.

Chi tiết gói

Yêu cầu hàng loạt bao gồm nhiều lệnh gọi API 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 về cú pháp lô; ở phần sau sẽ có ví dụ.

Lưu ý: Một nhóm các yêu cầu n được gộp với nhau 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 là một yêu cầu. Yêu cầu hàng loạt đượ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 hàng loạt

Yêu cầu hàng loạt là một yêu cầu HTTP chuẩn 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, các tiêu đề của phần chỉ xuất hiện để đánh dấu phần đầu của phần đó; chúng tách biệt với yêu cầu được lồng. Sau khi máy chủ khám phá yêu cầu hàng loạt thành các yêu cầu riêng biệt, tiêu đề của 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; URL đầy đủ không được phép trong yêu cầu hàng loạt.

Tiêu đề HTTP cho yêu cầu theo lô 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à lệnh gọi riêng lẻ, thì giá trị của tiêu đề cuộc gọi riêng lẻ sẽ ghi đè giá trị của tiêu đề yêu cầu lô ngoài. Tiêu đề của 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 tiêu đề Uỷ quyền cho một cuộc gọi cụ thể, thì tiêu đề đó sẽ chỉ áp dụng cho cuộc gọi đó. Nếu bạn cung cấp tiêu đề Uỷ quyền cho yêu cầu 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 chính chúng.

Khi nhận được yêu cầu theo lô, máy chủ sẽ áp dụng tham số truy vấn và tiêu đề của yêu cầu bên ngoài (nếu phù 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.

Phản hồi một yêu cầu hàng loạt

Phản hồi của máy chủ là một phản hồi HTTP 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 đú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 đứng sau một tiêu đề Content-Type đánh dấu phần đầu của phần đó.

Nếu một phần cụ thể 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 trùng khớp, có giá trị ban đầu đứng sau chuỗi response-, như trong ví dụ sau.

Lưu ý: Máy chủ có thể thực hiện lệnh gọi của bạn theo thứ tự bất kỳ. Không tính vào việc các lệnh đó đượ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 các lệnh gọi đó trong một yêu cầu; thay vào đó, hãy tự 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 thứ hai.

Ví dụ:

Ví dụ sau đây cho thấy việc sử dụng tính năng tạo lô bằng API Google Drive.

Ví dụ về yêu cầu hàng loạt

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ể của yêu cầu

Theo mặc định, máy chủ gửi lại một nhóm trường tài nguyên mặc định dành riêng cho phương thức được sử dụng. Ví dụ: phương thức files.list có thể chỉ trả về id, name và mimeType. Các trường này có thể không phải là những trường chính xác mà bạn cần. Nếu bạn cần trả về các trường khác, hãy tham khảo phần Trả về các trường cụ thể cho tệp.