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

Có một số nguyên tắc bạn nên tuân theo khi sử dụng API Google Tài liệu. Những quốc gia/khu vực này bao gồm:

  • Chỉnh sửa lui để đảm bảo tính hiệu quả
  • Lên 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 WriteControl trường
  • Xem xét các thẻ

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

Chỉnh sửa lui để đảm bảo tính hiệu quả

Chỉ trong một lệnh gọi đến documents.batchUpdate Hãy sắp xếp các yêu cầu của bạn theo thứ tự thứ tự giảm dần của vị trí chỉ mục. Việc này giúp bạn không cần phải tính toán thay đổi chỉ mục do việc chèn và xoá.

Lên kế hoạch cộng tác

Trạng thái tài liệu sẽ thay đổi. Giữa một lệnh gọi phương thức và một phương thức khác, cộng tác viên có thể cập nhật tài liệu, như minh hoạ trong sơ đồ dưới đây:

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

Việc 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 có nhiều người dùng chỉnh sửa 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, là ứng dụng API mà ứng dụng của bạn phải quản lý việc này. Ngay cả khi bạn không dự đoán cộng tác trên tài liệu, điều quan trọng là phải lập chương trình theo cách phòng vệ và đảm bảo đảm bảo trạng thái tài liệu vẫn nhất quán. Đối với một cách để đảm bảo tính nhất quán, hãy xem mục WriteControl.

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

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

Dưới đây là cách sử dụng:

  1. Tải tài liệu bằng cách sử dụng documents.get và lưu thời gian 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 WriteControl (không bắt buộc) bằng một trong hai tuỳ chọn:
    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 giấy tờ đã được sửa đổi vì yêu cầu đọc API nên yêu cầu ghi sẽ không được xử lý và sẽ trả về một lỗi.
    2. Trường targetRevisionId được đặt thành revisionId của tài liệu sẽ áp dụng yêu cầu ghi. Nếu tài liệu được sửa đổi từ Yêu cầu đọc API, các thay đổi đối với yêu cầu ghi sẽ được áp dụng đối với 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ả yêu cầu ghi thay đổi và cộng tác viên thay đổi thành bản sửa đổ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 một 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.

Xem xét các thẻ

Một tài liệu có thể chứa nhiều thẻ cần được 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 tài liệu. Theo mặc định, không phải tất cả các thẻ nội dung được trả về.
  2. Chỉ định(các) mã nhận dạng của(các) thẻ để áp dụng cho từng Request vào documents.batchUpdate . Mỗi Request bao gồm cách chỉ định các thẻ để áp dụng bản cập nhật. Theo mặc định, nếu một chưa chỉ định, thì Request trong hầu hết các trường hợp sẽ được áp dụng cho thẻ đầu tiên trong tài liệu. Tham khảo Request giây tài liệu cụ thể.