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 mà ứng dụng của bạn phải thực hiện. Tính năng xử lý hàng loạt có thể cải thiện hiệu quả của ứng dụng bằng cách giảm số lượt truy cập 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 thực hiện sẽ dẫn đến một mức hao tổn nhất định. API Google Trang tính hỗ trợ tính năng tạo 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 cần thực hiện, vào 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 duy nhất đến máy chủ, truy xuất một phản hồi duy nhất.
Người dùng nên luôn tạo nhiều yêu cầu cùng một lúc. Dưới đây là một số ví dụ về trường hợp bạn có thể sử dụng tính năng xử lý hàng loạt:
- Bạn mới bắt đầu sử dụng API và có nhiều dữ liệu cần 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 đối tượng.
- Bạn cần xoá nhiều đối tượng.
Những điều cần cân nhắc về giới hạn, quyền uỷ quyền và phần phụ thuộc
Dưới đây là danh sách các mục khác cần cân nhắc 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 cả tất cả các yêu cầu phụ, được tính là một yêu cầu API đối với giới hạn sử dụng của bạn.
- Yêu cầu hàng loạt được xác thực một lần. Lượt xác thực này áp dụng cho tất cả đối tượng cập nhật hàng loạt trong yêu cầu.
- Máy chủ xử lý các yêu cầu con theo thứ tự xuất hiện trong yêu cầu theo lô. Các yêu cầu phụ sau này có thể phụ thuộc vào các hành động được thực hiện trong 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 một tài liệu hiện có rồi định kiểu cho văn bản đó.
Chi tiết gói
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ụ, chẳng hạn như thêm rồi định dạng một bảng tính.
Mỗi yêu cầu đều được xác thực trước khi được áp dụng. Tất cả các yêu cầu con trong bản cập nhật hàng loạt đều được áp dụng một cách nguyên tử. Tức 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 sẽ không thành công và không có thay đổi nào (có thể phụ thuộc) được áp dụng.
Một số yêu cầu cung cấp phản hồi kèm theo thông tin về các yêu cầu đã áp dụng. Ví dụ: tất cả yêu cầu cập nhật hàng loạt để thêm đối tượng đều trả về phản hồi để bạn có thể truy cập vào siêu dữ liệu của đối tượng mới thêm, 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ể tạo toàn bộ tài liệu trên Google bằng một yêu cầu cập nhật hàng loạt API với nhiều yêu cầu phụ.
Định dạng của yêu cầu theo lô
Yêu cầu là một yêu cầu JSON duy nhất chứa nhiều yêu cầu phụ lồng nhau với một thuộc tính bắt buộc: requests. Các yêu cầu được tạo trong một mảng gồm 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 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 một phản hồi đầy đủ của một đối tượng phản hồi.
Thuộc tính của đối tượng JSON chính có tên là replies. Các 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ự chỉ mục với yêu cầu tương ứng. Một số yêu cầu không có phản hồi và phản hồi tại chỉ mục mảng đó trống.
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 Trang tính.
Yêu cầu
Yêu cầu theo lô mẫu này minh hoạ cách:
- Thêm một trang tính vào bảng tính hiện có, với
sheetIdlà 12345, bằng cách sử dụngAddSheetRequest. - Thêm dữ liệu vào trang tính mới, bắt đầu từ ô A1, bằng cách sử dụng
UpdateCellsRequest. - Thêm
namedRangehoặc chế độ xem bộ lọc vào trang tính mới.
Bằng cách thêm mã trang tính vào yêu cầu, người dùng có thể sử dụng mã trang tính cho các yêu cầu phụ khác trong cùng một lệnh gọi API. Điều này giúp cải thiện hiệu suất bằng cách tránh chu kỳ ghi-đọc-ghi.
Để biết danh sách các loại yêu cầu cập nhật hàng loạt, được nhóm thành nhiều danh mục, hãy xem bảng trong phần Thao tác cập nhật hàng loạt.
{
"requests":[
{
"addSheet":{
"properties":{
"sheetId":123456
}
}
},
{
"updateCells":{
"start":{
"sheetId":123456
},
"rows":[
{
"values":[
{
"userEnteredValue":{
"stringValue":"hello"
}
}
]
},
{
"values":[
{
"userEnteredValue":{
"stringValue":"world"
}
}
]
}
],
"fields":"userEnteredValue"
}
},
{
"addNamedRange":{
"namedRange":{
"name":"newRange",
"range":{
"sheetId":123456,
"endRowIndex":2
}
}
}
}
]
}
Phản hồi
Phản hồi hàng loạt mẫu này cho thấy thông tin về cách áp dụng từng yêu cầu phụ trong yêu cầu hàng loạt. Lưu ý UpdateCellsRequest không chứa phản hồi, vì vậy giá trị chỉ mục của mảng tại [1] bao gồm các dấu ngoặc nhọn trống.
"replies":[
{
"addSheet":{
"properties":{
"sheetId":123456,
"title":"Sheet3",
"index":2,
"sheetType":"GRID",
"gridProperties":{
"rowCount":1000,
"columnCount":26
}
}
}
},
{
},
{
"addNamedRange":{
"namedRange":{
"namedRangeId":"2104325079",
"name":"newRange",
"range":{
"sheetId":123456,
"startRowIndex":0,
"endRowIndex":2,
"startColumnIndex":0,
"endColumnIndex":26
}
}
}
}
]