Tài liệu này trình bày cách phân nhóm các lệnh gọi API với nhau để giảm số lượng lệnh gọi API các kết nối mà khách hàng của bạn phải tạo. Việc phân lô có thể cải thiện hiệu quả bằng cách giảm số lượt trọn vòng của mạng và tăng thông lượng.
Tổng quan
Mỗi kết nối mà ứng dụng của bạn tạo ra đều dẫn đến một mức chi phí nhất định. API Google Tài liệu hỗ trợ tính năng phân lô để cho phép ứng dụng của bạn đặt nhiều đối tượng yêu cầu, mỗi đối tượng chỉ định một loại yêu cầu duy nhất để thực hiện, thành một yêu cầu hàng loạt. Yêu cầu hàng loạt có thể tăng hiệu suất bằng cách kết hợp nhiều yêu cầu con vào một lệnh gọi máy chủ, truy xuất một phản hồi.
Người dùng nên luôn nhóm nhiều yêu cầu cùng nhau. Sau đây là một số ví dụ về các trường hợp mà bạn có thể sử dụng phân lô:
- Bạn mới bắt đầu sử dụng API và có nhiều dữ liệu để tải lên.
- Bạn cần cập nhật siêu dữ liệu hoặc thuộc tính (chẳng hạn như định dạng) trên nhiều .
- Bạn cần xoá nhiều đối tượng.
Giới hạn, uỷ quyền và những điều cần cân nhắc về phần phụ thuộc
Dưới đây là danh sách các mục khác cần xem xét khi sử dụng tính năng cập nhật hàng loạt:
- Mỗi yêu cầu hàng loạt (bao gồm tất cả yêu cầu phụ) sẽ được tính là một API yêu cầu của bạn so với hạn mức sử dụng của bạn.
- Yêu cầu hàng loạt được xác thực một lần. Áp dụng phương thức xác thực duy nhất này cho tất cả các đối tượng cập nhật theo lô trong yêu cầu.
- Máy chủ sẽ xử lý các yêu cầu phụ theo cùng thứ tự mà chúng xuất hiện trong hàng loạt. Các yêu cầu phụ phía sau có thể phụ thuộc vào các hành động được thực hiện trong khoảng thời gian các yêu cầu phụ trước đó. Ví dụ: trong cùng một yêu cầu hàng loạt, người dùng có thể chèn văn bản vào tài liệu hiện có rồi tạo kiểu cho văn bản đó.
Chi tiết gói
Một yêu cầu hàng loạt bao gồm một lệnh gọi phương thức batchUpdate
với nhiều yêu cầu phụ để thêm rồi định dạng tài liệu chẳng hạn.
Mỗi yêu cầu đều được xác thực trước khi áp dụng. Tất cả yêu cầu phụ trong lô thì bản cập nhật được áp dụng tỉ mỉ. Nghĩa là, nếu có bất kỳ yêu cầu nào không hợp lệ thì toàn bộ quá trình cập nhật không thành công và không có lựa chọn nào (có thể phụ thuộc) sẽ được áp dụng.
Một số yêu cầu cung cấp phản hồi cùng với thông tin về các yêu cầu đã áp dụng. Ví dụ: mọi yêu cầu cập nhật hàng loạt để thêm đối tượng sẽ trả về phản hồi, bạn có thể truy cập siêu dữ liệu của đối tượng mới được thêm vào, chẳng hạn như mã nhận dạng hoặc tiêu đề.
Với phương pháp này, bạn có thể xây dựng toàn bộ tài liệu trên Google bằng một API yêu cầu cập nhật hàng loạt có nhiều yêu cầu phụ.
Định dạng của một yêu cầu hàng loạt
Yêu cầu là một yêu cầu JSON duy nhất chứa nhiều
các yêu cầu phụ lồng nhau có một thuộc tính bắt buộc: requests. Chiến lược phát hành đĩa đơn
các yêu cầu được tạo trong một loạt các yêu cầu riêng lẻ. Mỗi yêu cầu sử dụng
JSON để biểu thị đối tượng yêu cầu và chứa các thuộc tính của đối tượng đó.
Định dạng của một phản hồi hàng loạt
Định dạng phản hồi cho yêu cầu hàng loạt tương tự như định dạng yêu cầu. Phản hồi của máy chủ chứa toàn bộ phản hồi của của bạn.
Thuộc tính của đối tượng JSON chính có tên là replies. Phản hồi
được trả về trong một mảng, trong đó mỗi phản hồi cho một trong các yêu cầu chiếm
cùng thứ tự lập chỉ mục với yêu cầu tương ứng. Một số yêu cầu không có
và phản hồi tại chỉ mục mảng đó bị trống.
Ví dụ:
Mã mẫu sau đây minh hoạ cách sử dụng tính năng phân lô bằng API Tài liệu.
Yêu cầu
Ví dụ về yêu cầu hàng loạt này minh hoạ cách:
Chèn "Hello World" ("Xin chào thế giới") văn bản vào đầu tài liệu hiện có, với chỉ mục
location/1, sử dụngInsertTextRequest.Cập nhật từ "Hello" sử dụng
UpdateTextStyleRequest.startIndexvàendIndexxác địnhrangecủa văn bản được định dạng trong phân đoạn.Sử dụng
textStyle, đặt kiểu phông chữ thành đậm và màu xanh dương chỉ từ "Xin chào".Sử dụng
WriteControl, bạn có thể kiểm soát cách thực thi các yêu cầu ghi. Để biết thêm thông tin, hãy xem Thiết lập tính nhất quán của trạng thái với WriteControl.
{
"requests":[
{
"insertText":{
"location":{
"index":1,
"tabId":TAB_ID
},
"text":"Hello World"
}
},
{
"updateTextStyle":{
"range":{
"startIndex":1,
"endIndex":6
},
"textStyle":{
"bold":true,
"foregroundColor":{
"color":{
"rgbColor":{
"blue":1
}
}
}
},
"fields":"bold,foreground_color"
}
}
],
"writeControl": {
"requiredRevisionId": "REQUIRED_REVISION_ID"
}
}
Thay thế TAB_ID và REQUIRED_REVISION_ID bằng mã thẻ và mã bản sửa đổi tương ứng của tài liệu yêu cầu ghi được áp dụng cho.
Phản hồi
Ví dụ về tính năng phản hồi hàng loạt hiển thị thông tin về cách mỗi yêu cầu phụ trong
yêu cầu hàng loạt đã được áp dụng. Cả hai
InsertTextRequest
hoặc
UpdateTextStyleRequest
chứa một phản hồi, vì vậy các giá trị chỉ mục của mảng tại [0] và [1] bao gồm
dấu ngoặc nhọn trống. Yêu cầu hàng loạt hiển thị đối tượng WriteControl,
cho thấy cách các yêu cầu được thực thi.
{
"replies":[
{},
{}
],
"writeControl":{
"requiredRevisionId":`REQUIRED_REVISION_ID`
},
"documentId":`DOCUMENT_ID`
}