Method: documents.batchUpdate

Áp dụng một hoặc nhiều nội dung cập nhật cho tài liệu.

Mỗi request đều được xác thực trước khi được áp dụng. Nếu có yêu cầu không hợp lệ, thì toàn bộ yêu cầu sẽ không thành công và không có gì được áp dụng.

Một số yêu cầu có biểu tượng replies để cung cấp cho bạn thông tin về cách áp dụng các yêu cầu đó. Các yêu cầu khác không cần trả về thông tin; mỗi yêu cầu này sẽ trả về một câu trả lời trống. Thứ tự của các câu trả lời khớp với thứ tự của các yêu cầu.

Ví dụ: giả sử bạn gọi batchUpdate với 4 nội dung cập nhật và chỉ nội dung thứ ba trả về thông tin. Phản hồi sẽ có 2 câu trả lời trống, câu trả lời cho yêu cầu thứ ba và một câu trả lời trống khác, theo thứ tự đó.

Vì những người dùng khác có thể đang chỉnh sửa tài liệu, nên tài liệu có thể không phản ánh chính xác các thay đổi của bạn: các thay đổi của bạn có thể bị thay đổi so với các thay đổi của cộng tác viên. Nếu không có cộng tác viên, tài liệu sẽ phản ánh các thay đổi của bạn. Trong mọi trường hợp, các nội dung cập nhật trong yêu cầu của bạn đều được đảm bảo áp dụng cùng nhau một cách nguyên tử.

Yêu cầu HTTP

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Thông số
documentId

string

Mã của tài liệu cần cập nhật.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu với cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Trường
requests[]

object (Request)

Danh sách các nội dung cập nhật cần áp dụng cho tài liệu.
writeControl

object (WriteControl)

Cho phép kiểm soát cách thực hiện các yêu cầu ghi.

Nội dung phản hồi

Thông báo phản hồi từ một yêu cầu documents.batchUpdate.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Trường
documentId

string

Mã nhận dạng của tài liệu mà các nội dung cập nhật được áp dụng.
replies[]

object (Response)

Câu trả lời cho thông tin cập nhật. Điều này tương ứng 1:1 với các bản cập nhật, mặc dù câu trả lời cho một số yêu cầu có thể trống.
writeControl

object (WriteControl)

Quyền ghi đã cập nhật sau khi áp dụng yêu cầu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.

WriteControl

Cho phép kiểm soát cách thực hiện các yêu cầu ghi.

Biểu diễn dưới dạng JSON 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
Trường
Trường nhóm control. Xác định phiên bản của tài liệu cần ghi và cách yêu cầu hoạt động nếu phiên bản đó không phải là phiên bản hiện tại của tài liệu. Nếu bạn không chỉ định trường nào, thì các nội dung cập nhật sẽ được áp dụng cho bản sửa đổi mới nhất. control chỉ có thể là một trong những trạng thái sau:
requiredRevisionId

string

revision ID không bắt buộc của tài liệu mà yêu cầu ghi được áp dụng. Nếu đây không phải là bản sửa đổi mới nhất của tài liệu, thì yêu cầu sẽ không được xử lý và trả về lỗi 400 yêu cầu không hợp lệ.

Khi một mã phiên bản bắt buộc được trả về trong phản hồi, mã này cho biết mã phiên bản của tài liệu sau khi yêu cầu được áp dụng.
targetRevisionId

string

Mục tiêu không bắt buộc revision ID của tài liệu mà yêu cầu ghi được áp dụng.

Nếu cộng tác viên đã thực hiện các thay đổi sau khi tài liệu được đọc bằng API, thì các thay đổi do yêu cầu ghi này tạo ra sẽ được áp dụng cho các thay đổi của cộng tác viên. Thao tác này sẽ tạo ra một bản sửa đổi mới của tài liệu, trong đó kết hợp cả các thay đổi của cộng tác viên và các thay đổi trong yêu cầu, đồng thời máy chủ Tài liệu sẽ giải quyết các thay đổi xung đột. Khi sử dụng mã nhận dạng phiên bản mục tiêu, bạn có thể coi ứng dụng API là một cộng tác viên khác của tài liệu.

Bạn chỉ có thể dùng mã nhận dạng phiên bản đích để ghi vào các phiên bản gần đây của một tài liệu. Nếu phiên bản mục tiêu quá cũ so với phiên bản mới nhất, thì yêu cầu sẽ không được xử lý và trả về lỗi 400 yêu cầu không hợp lệ. Bạn nên thử lại yêu cầu sau khi truy xuất phiên bản mới nhất của tài liệu. Thông thường, mã phiên bản vẫn hợp lệ để sử dụng làm phiên bản đích trong vài phút sau khi được đọc, nhưng đối với những tài liệu thường xuyên được chỉnh sửa, khoảng thời gian này có thể ngắn hơn.