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 API Google Tài liệu, 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 API Google Tài liệu 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ữ. Các kiểu khớp này tương đương với nhau.
API Google Tài liệu 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 sử dụng thư viện ứng dụng để đưa ra yêu cầu, phản hồi sẽ được trả về theo cách dành riêng cho ngôn ngữ.
Phương thức yêu cầu
API Tài liệu hỗ trợ các phương thức sau:
documents.create: Tạo một tài liệu Google Tài liệu trống.documents.get: Trả về một thực thể đầy đủ của tài liệu đã chỉ định. Bạn có thể phân tích cú pháp JSON được trả về để trích xuất nội dung tài liệu, định dạng và các tính năng khác.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 mục tiêu. Phương thức documents.create sẽ trả về một thực thể 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 phần Mã tài liệu.
Cập nhật hàng loạt
Phương thức documents.batchUpdate sẽ nhận danh sách các đối tượng request, mỗi đối tượng sẽ chỉ định một yêu cầu để thực hiện. Ví dụ: định dạng một đoạn văn bản rồi thêm hình ảnh nội tuyến. Mỗi yêu cầu được xác thực trước khi á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ả 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 nào 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 phản hồi cùng với 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 phần 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 phản hồi trống. Các đối tượng trong danh sách phản hồi có thứ tự chỉ mục giống với 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 về yêu cầu theo lô để biết thông tin chi tiết đầy đủ về cách tạo lô lệnh gọi API Tài liệu và tài liệu tham khảo documents.batchUpdate về các loại yêu cầu và phản hồi.
Thao tác cập nhật hàng loạt
Có nhiều loại yêu cầu cập nhật hàng loạt. Dưới đâ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.