Yêu cầu và phản hồi

Hướng dẫn này giới thiệu các phương thức phản hồi và yêu cầu chính tạo nên API Google Tài liệu và 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 gọi phương thức trong thư viện ứng dụng dành riêng cho một ngôn ngữ. Các chỉ số này nhìn chung là tương đương.

API Google Tài liệu trả về 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 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

API Tài liệu hỗ trợ các phương thức sau:

  • documents.create: Tạo tài liệu trống trong Google Tài liệu.
  • documents.get: Trả về một bản sao 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 tài liệu, định dạng và các tính năng khác.
  • documents.batchUpdate: Gửi danh sách yêu cầu chỉnh sửa để áp dụng riêng cho tài liệu và trả về danh sách kết quả.

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 trả về một bản sao 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ã tài liệu.

Cập nhật theo lô

Phương thức documents.batchUpdate sẽ lấy một danh sách đối tượng request, mỗi đối tượng chỉ định một yêu cầu để thực hiện. Ví dụ: định dạng một đoạn văn rồi thêm hình ảnh cùng dòng. Mỗi yêu cầu sẽ được xác thực trước khi áp dụng và các yêu cầu sẽ đượ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 quá trình cập nhật theo lô đều được áp dụng tỉ mỉ. Điều này nghĩa là nếu có bất kỳ 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à sẽ không có thay đổi nào (có thể là phụ thuộc) được áp dụng.

Một số phương thức documents.batchUpdate cung cấp phản hồi chứa thông tin về các yêu cầu được á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 đố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 với yêu cầu tương ứng.

Một mẫu phổ biến để thực hiện yêu cầu hàng loạt giống như sau:

requests = []
requests.append(first request)
requests.append(second request)
...

body = ... & requests & ...

...batchUpdate(body)

Xem các phương pháp hay nhất về yêu cầu hàng loạt để biết toàn bộ thông tin chi tiết về cách phân 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 theo lô

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 các danh mục khác nhau.

Đối tượng THÊM / CHÈN CẬP NHẬT / THAY THẾ DELETE
Văn bản InsertTextRequest ReplaceAllTextRequest
Kiểu CreateParagraphBulletsRequest UpdateTextStyleRequest
UpdateParagraphStyleRequest
UpdateTableCellStyleRequest
UpdateTableRowStyleRequest
UpdateDocumentStyleRequest
UpdateSectionStyleRequest 		DeleteParagraphBulletsRequest
Dải ô được đặt tên CreateNamedRangeRequest ReplaceNamedRangeContentRequest DeleteNamedRangeRequest
DeleteContentRangeRequest
Hình ảnh InsertInlineImageRequest ReplaceImageRequest
Bảng InsertTableRequest
InsertTableRowRequest
InsertTableColumnRequest
 UpdateTableColumnPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
PinTableHeaderRowsRequest		 DeleteTableRowRequest
DeleteTableColumnRequest
Đối tượng trang (bao gồm cả headers và chân trang) InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest		 DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest