Tài liệu này cho biết cách nhóm các lệnh gọi API lại với nhau để giảm số lượng kết nối mà ứng dụng của bạn phải thực hiện. Việc phân lô có thể cải thiện hiệu quả của ứng dụng bằng cách giảm số lượt trọn vòng mạng và tăng thông lượng.
Tổng quan
Mỗi kết nối mà ứng dụng thực hiện sẽ dẫn đến một mức hao tổn nhất định. API Google Trang trình bày 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 để 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 phụ vào một lệnh gọi duy nhất đến máy chủ, truy xuất lại một phản hồi duy nhất.
Người dùng nên luôn gộp nhiều yêu cầu cùng nhau. Sau đâ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 để 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, việc uỷ quyền 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 theo lô (bao gồm cả tất cả các yêu cầu phụ) sẽ được tính là một yêu cầu API trong 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. Phương thức xác thực duy nhất này áp dụng cho tất cả đối tượng cập nhật theo lô trong yêu cầu.
- Máy chủ xử lý các yêu cầu phụ theo thứ tự xuất hiện trong yêu cầu hàng loạt. Các yêu cầu phụ sau 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 tạo 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ản trình bày.
Mỗi yêu cầu đều được xác thực trước khi áp dụng. Tất cả các yêu cầu phụ trong quá trình cập nhật theo lô đều được áp dụng tỉ mỉ. Nghĩa là, nếu 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).
Một số yêu cầu đưa ra 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 được 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 của Google bằng cách sử dụ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 hàng loạt
Yêu cầu là một yêu cầu JSON 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 theo một loạt các yêu cầu riêng lẻ. Mỗi yêu cầu sử dụng JSON để đại diện cho đối tượng yêu cầu và chứa các thuộc tính của đối tượng đó.
Định dạng phản hồi hàng loạt
Định dạng phản hồi cho một 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 câu trả lờ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 sẽ chiếm cùng một 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ụ:
Mã mẫu sau đây cho thấy cách sử dụng tính năng phân lô bằng API Trang trình bày.
Yêu cầu
Ví dụ về yêu cầu hàng loạt minh hoạ cách:
Thêm tài nguyên
presentations.pagesvào bản trình bày hiện có vớiinsertionIndexlà1bằng cách sử dụng phương thứcCreateSlideRequest.Thêm
shapeTypethuộc loạiTEXT_BOXvào trang trình bày mới bằng phương thứcCreateShapeRequest.Chèn văn bản "Hello World" vào trường mới bằng phương thức
InsertTextRequest.
{
"requests":[
{
"createSlide":{
"insertionIndex":1,
"objectId":"newSlide"
}
},
{
"createShape":{
"elementProperties":{
"pageObjectId":"newSlide",
"size":{
"height":{
"magnitude":50,
"unit":"PT"
},
"width":{
"magnitude":200,
"unit":"PT"
}
}
},
"shapeType":"TEXT_BOX",
"objectId":"newTextBox"
}
},
{
"insertText":{
"objectId":"newTextBox",
"text":"Hello World"
}
}
]
}
Phản hồi
Ví dụ về phản hồi hàng loạt này hiển thị thông tin về cách từng yêu cầu phụ trong yêu cầu hàng loạt được áp dụng. Lưu ý rằng phương thức InsertTextRequest không chứa phản hồi nên giá trị chỉ mục của mảng tại [2] bao gồm dấu ngoặc nhọn trống. Yêu cầu theo lô sẽ hiển thị thuộc tính WriteControl, cho biết cách thực thi các yêu cầu ghi.
{
"requiredRevisionId": ID
"presentationId": "",
"replies":[
{
"createSlide":{
"objectId":"newSlide"
}
},
{
"createShape":{
"objectId":"newTextBox"
}
},
{
}
],
"writeControl":{
"requiredRevisionId": REVISION_ID
}
}