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 Google Docs API. 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 về 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 lượt 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 một lệnh gọi phương thức và một lệnh gọi phương thức khác, những cộng tác viên khác có thể cập nhật tài liệu, như minh hoạ 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à một ứng dụng API, ứng dụng của bạn phải quản lý việc này. Ngay cả khi không dự đoán được việc cộng tác trên tài liệu, bạn vẫn cần lập trình một cách phòng thủ và đảm bảo trạng thái của tài liệu luôn nhất quán. Để đảm bảo tính nhất quán, hãy xem phần WriteControl.

Thiết lập tính nhất quán về 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 hiện 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 lựa 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 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à 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 trong 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 của yêu cầu ghi và các thay đổi của cộng tác viên thành một phiên bản 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ẻ, bạn cần 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(các) thẻ để áp dụng từng Request trong phương thức documents.batchUpdate. Mỗi Request đều có 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ì Request sẽ được áp dụng cho thẻ đầu tiên trong tài liệu trong hầu hết các trường hợp. Tham khảo tài liệu về Request để biết thông tin cụ thể.