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 phải 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 ngược lại để tăng tính 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

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

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

Trong một lệnh gọi đế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í lập chỉ mục. Điều này giúp bạn không cần tính toán các thay đổi đối với chỉ mục do các thao tác chèn và xoá.

Lập 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 này và một lệnh gọi phương thức khác, các 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 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 các 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 tài liệu bằng giao diện người dùng, Google Tài liệu xử lý việc này một cách minh bạch. Tuy nhiên, khi 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 hoạt động cộng tác trên tài liệu này, bạn vẫn cần phải lập chương trình một cách phòng vệ và đảm bảo trạng thái của tài liệu luôn nhất quán. Để biết một cách đảm bảo tính nhất quán, hãy xem lại mục WriteControl.

Thiết lập tính nhất quán của trạng thái với ReadControl

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 thông qua 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.

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

  1. Lấy tài liệu bằng cách sử dụng phương thức documents.get và lưu revisionId từ tài nguyên documents được trả về.
  2. Soạn các 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 tuỳ chọn:
    1. Trường requiredRevisionId được đặt thành revisionId của tài liệu áp dụng yêu cầu ghi. 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 áp dụng yêu cầu ghi. Nếu tài liệu được sửa đổi kể từ yêu cầu đọc API, thì các thay đổi về 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ả thay đổi về yêu cầu ghi và 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.

Để xem 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.