Yêu cầu theo lô

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 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 qua 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 để 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 phụ vào một lệnh gọi máy chủ, truy xuất một phản hồi duy nhất.

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ương thức 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 đối tượng.
  • Bạn cần xoá nhiều đối tượng.

Giới hạn, việc 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 cả tất cả yêu cầu phụ) sẽ được tính là một yêu cầu API vào 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. 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ủ sẽ xử lý các yêu cầu phụ theo cùng thứ tự mà chúng xuất hiện trong yêu cầu hàng loạt. Các yêu cầu phụ sau này có thể phụ thuộc vào những 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 tài liệu hiện có rồi tạo kiểu cho tài liệu đó.

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 tài liệu.

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 quá trình cập nhật theo lô đều được áp dụng một cách tỉ mỉ. Nghĩa là, nếu có yêu cầu 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 cùng với 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 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 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 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 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 này được tạo thành 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 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 nội dung trả lời đầy đủ của một đối tượng phản hồi duy nhất.

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 có 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ụ:

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 văn bản "Hello World" ("Xin chào thế giới") vào phần đầu một tài liệu hiện có, với chỉ mục location là 1, bằng cách dùng InsertTextRequest.

  • Cập nhật từ "Hello" (Xin chào) bằng cách sử dụng UpdateTextStyleRequest. startIndex và endIndex xác định range của văn bản được định dạng trong phân đoạn.

  • Bằng cách sử dụng textStyle, hãy đặt kiểu phông chữ thành đậm và màu xanh dương chỉ cho từ "Hello".

  • Bằng cách sử dụng trườ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 phần Thiết lập tính nhất quán của trạng thái bằng WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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ế REQUIRED_REVISION_ID bằng mã nhận dạng bản sửa đổi của tài liệu áp dụng yêu cầu ghi.

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 áp dụng từng yêu cầu phụ trong yêu cầu hàng loạt. Cả InsertTextRequest hoặc UpdateTextStyleRequest đều không chứa phản hồi, vì vậy, các giá trị chỉ mục của mảng tại [0] và [1] không bao gồm dấu ngoặc nhọn trống. Yêu cầu hàng loạt sẽ hiện đối tượng WriteControl, cho biết cách các yêu cầu được thực thi.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}