Các phương pháp hay nhất để có kết quả tốt nhất

Bạn nên tuân thủ một số nguyên tắc khi sử dụng API Google Tài liệu. bao gồm:

  • Chỉnh sửa ngược để tăng hiệu quả
  • Lập kế hoạch cộng tác
  • Đảm bảo tính nhất quán của trạng thái bằng cách sử dụng trường WriteControl
  • Tính đến các thẻ

Các phần sau đây giải thích những nguyên tắc này.

Chỉnh sửa ngược để tăng hiệu quả

Trong một lệnh gọi duy nhất đến phương thức documents.batchUpdate, hãy sắp xếp các yêu cầu theo thứ tự giảm dần của vị trí chỉ mục. Điều này giúp bạn không cần phải tính toán các thay đổi về chỉ mục do các thao tác chèn và xoá.

Lập kế hoạch cộng tác

Dự kiến trạng thái tài liệu sẽ thay đổi. Giữa các lệnh gọi phương thức, các cộng tác viên khác có thể cập nhật tài liệu, như trong sơ đồ sau:

Cách một tài liệu có thể thay đổi giữa các lệnh gọi phương thức.

Điều này có thể dẫn đến lỗi nếu chỉ mục của bạn không chính xác. Khi nhiều người dùng chỉnh sửa một tài liệu bằng giao diện người dùng, Google Tài liệu sẽ xử lý việc này một cách minh bạch. Tuy nhiên, với tư cách là ứng dụng khách API, ứng dụng của bạn phải quản lý việc này. Ngay cả khi bạn không dự kiến sẽ cộng tác trên tài liệu, điều quan trọng là bạn phải lập trình một cách phòng thủ và đảm bảo trạng thái tài liệu luôn nhất quán. Để đảm bảo tính nhất quán, hãy xem lại phần WriteControl.

Thiết lập tính nhất quán trạng thái bằng WriteControl

Khi đọc rồi cập nhật một tài liệu, bạn có thể kiểm soát hành vi xử lý các thay đổi cạnh tranh bằng cách sử dụng trường WriteControl trong phương thức documents.batchUpdate. WriteControl cung cấp quyền kiểm soát cách thực thi các yêu cầu ghi.

Sau đây là cách sử dụng:

  1. Lấy tài liệu bằng phương thức documents.get và lưu revisionId từ tài nguyên documents được trả về.
  2. Soạn yêu cầu cập nhật.
  3. Thêm một đối tượng WriteControl không bắt buộc bằng một trong hai cách sau:
    1. Trường requiredRevisionId được đặt thành revisionId của tài liệu mà yêu cầu ghi được áp dụng. Nếu tài liệu đã được sửa đổi kể từ yêu cầu đọc API, thì yêu cầu ghi sẽ không được xử lý và sẽ trả về lỗi.
    2. Trường targetRevisionId được đặt thành revisionId của tài liệu mà yêu cầu ghi được áp dụng. Nếu tài liệu đã được sửa đổi kể từ yêu cầu đọc API, thì các thay đổi đối với yêu cầu ghi sẽ được áp dụng cho các thay đổi của cộng tác viên. Kết quả của yêu cầu ghi kết hợp cả các thay đổi đối với yêu cầu ghi và các thay đổi của cộng tác viên vào một bản sửa đổi mới của tài liệu. Máy chủ Tài liệu chịu trách nhiệm hợp nhất nội dung.

Để biết ví dụ về cách tạo yêu cầu hàng loạt bằng WriteControl, hãy xem ví dụ về yêu cầu hàng loạt này.

Tính đến các thẻ

Một tài liệu có thể chứa nhiều thẻ, yêu cầu xử lý cụ thể trong các yêu cầu API.

Sau đây là những điều cần nhớ:

  1. Đặt tham số includeTabsContent thành true trong phương thức documents.get để truy xuất nội dung từ tất cả các thẻ trong một tài liệu. Theo mặc định, không phải tất cả nội dung thẻ đều được trả về.
  2. Chỉ định (các) mã nhận dạng của thẻ để áp dụng từng Request trong phương thức documents.batchUpdate. Mỗi Request bao gồm một cách để chỉ định các thẻ cần áp dụng bản cập nhật. Theo mặc định, nếu bạn không chỉ định thẻ, thì trong hầu hết các trường hợp, Request sẽ được áp dụng cho thẻ đầu tiên trong tài liệu. Hãy tham khảo tài liệu về Request để biết thông tin chi tiết.