Hướng dẫn này giới thiệu các phương thức yêu cầu và phản hồi chính tạo nên Google Docs API, cũng như cách bạn có thể cập nhật tài liệu theo lô.
Bạn có thể gọi Google Docs API bằng yêu cầu HTTP hoặc bằng cách sử dụng lệnh gọi phương thức trong thư viện ứng dụng dành riêng cho ngôn ngữ. Những giá trị này tương đương với nhau.
Google Docs API trả về một phản hồi HTTP, thường bao gồm kết quả của lệnh gọi yêu cầu. Khi bạn sử dụng một thư viện ứng dụng để đưa ra yêu cầu, các phản hồi sẽ được trả về theo cách dành riêng cho từng ngôn ngữ.
Phương thức yêu cầu
Docs API hỗ trợ các phương thức sau:
documents.create: Tạo một tài liệu trống trên Google Tài liệu.documents.get: Trả về một phiên bản hoàn chỉnh của tài liệu được chỉ định. Bạn có thể phân tích cú pháp JSON được trả về để trích xuất nội dung, định dạng và các tính năng khác của tài liệu.documents.batchUpdate: Gửi danh sách các yêu cầu chỉnh sửa để áp dụng một cách nguyên tử cho tài liệu và trả về danh sách kết quả.
Các phương thức documents.get và documents.batchUpdate yêu cầu documentId làm tham số để chỉ định tài liệu đích. Phương thức documents.create trả về một phiên bản của tài liệu đã tạo, từ đó bạn có thể đọc documentId. Để biết thêm thông tin về documentId, hãy xem Mã nhận dạng tài liệu.
Xin lưu ý rằng bạn không thể dùng phương thức documents.get để truy xuất các tài liệu đã xuất bản. Sau khi được xuất bản, các tài liệu công khai sẽ sử dụng một định dạng URL khác. Các lần thử sử dụng documentId mới của URL bằng phương thức documents.get sẽ trả về phản hồi mã trạng thái HTTP 404. Không có phương thức nào để truy xuất documentId ban đầu từ URL đã xuất bản. Để giải quyết vấn đề này, bạn có thể dùng Drive API để sao chép tài liệu đã xuất bản sang tài liệu dùng chung rồi truy cập vào tệp này. Để biết thêm thông tin, hãy xem bài viết Đặt tệp Google Tài liệu, Trang tính, Trang trình bày và Biểu mẫu ở chế độ công khai.
Cập nhật theo lô
Phương thức documents.batchUpdate sẽ nhận một danh sách các đối tượng request, mỗi đối tượng chỉ định một yêu cầu duy nhất cần thực hiện. Ví dụ: định dạng một đoạn văn bản rồi thêm một hình ảnh cùng dòng. Mỗi yêu cầu đều được xác thực trước khi được áp dụng và các yêu cầu được xử lý theo thứ tự xuất hiện trong yêu cầu hàng loạt.
Tất cả các yêu cầu trong bản cập nhật hàng loạt đều được áp dụng một cách nguyên tử. Tức là nếu có yêu cầu không hợp lệ, thì toàn bộ quá trình cập nhật sẽ không thành công và không có thay đổi nào (có thể phụ thuộc) được áp dụng.
Một số phương thức documents.batchUpdate cung cấp các phản hồi có thông tin về các yêu cầu đã áp dụng. Các phương thức này trả về một nội dung phản hồi chứa danh sách các đối tượng response.
Các yêu cầu khác không cần trả về thông tin và hiển thị một câu trả lời trống. Các đối tượng trong danh sách phản hồi chiếm cùng một thứ tự chỉ mục như yêu cầu tương ứng.
Một mẫu phổ biến để tạo yêu cầu hàng loạt có dạng như sau:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Hãy xem các phương pháp hay nhất đối với yêu cầu theo lô để biết đầy đủ thông tin chi tiết về cách xử lý hàng loạt các lệnh gọi Docs API và tài liệu tham khảo documents.batchUpdate cho các loại yêu cầu và phản hồi.
Thao tác cập nhật theo lô
Có nhiều loại yêu cầu cập nhật hàng loạt. Sau đây là thông tin chi tiết về các loại yêu cầu, được nhóm thành nhiều danh mục.
Chủ đề có liên quan
- Cấu trúc của một tài liệu trên Google Tài liệu
- Quy tắc và hành vi chỉnh sửa cấu trúc
- Yêu cầu theo lô