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 trường WriteControl

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ả

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 của bạn theo 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 các thay đổi đối với chỉ mục do lượt 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 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.

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. Trong bối cảnh 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 sẽ xử lý vấn đề này một cách minh bạch. Tuy nhiên, 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 quá trình cộng tác trong tài liệu này, bạn vẫn cần phải bảo vệ chương trình và đảm bảo trạng thái 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 phần WriteControl.

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

Khi đọc và cập nhật một tài liệu, bạn có thể kiểm soát hành vi về cách 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.

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

  1. Tải 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. Đưa đối tượng WriteControl không bắt buộc vào bằng một trong 2 lựa 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 mà yêu cầu ghi sẽ được áp dụng. Nếu tài liệu đã được sửa đổi kể từ khi có yêu cầu đọc API, thì các thay đổi đối với yêu cầu ghi sẽ được áp dụng đối với những thay đổi của cộng tác viên. Kết quả của yêu cầu ghi sẽ kết hợp cả thay đổi đối với 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.