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:
Đ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:
- Lấy tài liệu bằng cách sử dụng phương thức
documents.get
và lưurevisionId
từ tài nguyêndocuments
được trả về. - Soạn các yêu cầu cập nhật.
- Thêm một đối tượng
WriteControl
không bắt buộc bằng một trong hai tuỳ chọn:- Trường
requiredRevisionId
được đặt thànhrevisionId
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. - Trường
targetRevisionId
được đặt thànhrevisionId
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.
- Trường
Để 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.