Cảnh báo: Trang này giới thiệu về các API cũ của Google, API dữ liệu của Google; trang này chỉ liên quan đến các API được liệt kê trong thư mục API dữ liệu của Google, nhiều API trong số này đã được thay thế bằng các API mới hơn. Để biết thông tin về một API mới cụ thể, hãy xem tài liệu của API mới. Để biết thông tin về việc uỷ quyền cho các yêu cầu bằng một API mới hơn, hãy xem phần Xác thực và ủy quyền tài khoản Google.
Tài liệu này mô tả Giao thức dữ liệu của Google được nhiều API của Google sử dụng, bao gồm thông tin về truy vấn trông như thế nào, kết quả trông như thế nào, v.v.
Để biết thêm thông tin về Giao thức dữ liệu Google, hãy xem trang tổng quan Hướng dẫn dành cho nhà phát triển và tài liệu Cơ bản về giao thức.
Đối tượng người xem
Tài liệu này dành cho những ai muốn tìm hiểu chi tiết về định dạng XML và giao thức được sử dụng bởi các API triển khai Giao thức dữ liệu Google.
Nếu chỉ muốn viết mã sử dụng một trong những API này, thì bạn không cần biết những thông tin chi tiết này; thay vào đó, bạn có thể sử dụng thư viện ứng dụng dành riêng cho ngôn ngữ.
Nhưng nếu bạn muốn hiểu giao thức, hãy đọc tài liệu này. Ví dụ: bạn có thể muốn đọc tài liệu này để giúp bạn thực hiện bất kỳ tác vụ nào sau đây:
- đánh giá kiến trúc của Giao thức dữ liệu của Google
- lập trình bằng giao thức mà không cần sử dụng các thư viện ứng dụng được cung cấp
- viết thư viện ứng dụng bằng ngôn ngữ mới
Tài liệu này giả định rằng bạn hiểu được các khái niệm cơ bản về XML, vùng chứa tên, nguồn cấp dữ liệu được phân phối và các yêu cầu GET, POST, PUT và DELETE trong HTTP, cũng như khái niệm "tài nguyên" của HTTP. Để biết thêm thông tin về những vấn đề đó, hãy xem phần Tài nguyên bổ sung của tài liệu này.
Tài liệu này không dựa vào bất kỳ ngôn ngữ lập trình cụ thể nào. Bạn có thể gửi và nhận thông báo Giao thức dữ liệu của Google bằng bất kỳ ngôn ngữ lập trình nào cho phép bạn đưa ra yêu cầu HTTP và phân tích cú pháp phản hồi dựa trên XML.
Chi tiết về giao thức
Phần này mô tả định dạng tài liệu và cú pháp truy vấn trong Giao thức dữ liệu của Google.
Định dạng tài liệu
Giao thức dữ liệu của Google và Atom có cùng mô hình dữ liệu cơ bản: vùng chứa lưu giữ một số dữ liệu toàn cầu và số lượng mục nhập bất kỳ. Đối với mỗi giao thức, định dạng được xác định bởi một giản đồ cơ sở, nhưng có thể mở rộng định dạng này bằng cách sử dụng không gian tên nước ngoài.
Atom là định dạng mặc định cho Giao thức dữ liệu Google. Để yêu cầu phản hồi ở định dạng khác, hãy sử dụng tham số truy vấn alt; để biết thêm thông tin, hãy xem bài viết Yêu cầu truy vấn.
Lưu ý: Hầu hết các nguồn cấp dữ liệu Giao thức dữ liệu của Google ở định dạng Atom đều sử dụng vùng chứa tên Atom làm không gian tên mặc định bằng cách chỉ định thuộc tính xmlns trên phần tử nguồn cấp dữ liệu, như trong các ví dụ đã cho trong Cơ bản về giao thức. Do đó, những ví dụ trong tài liệu này không chỉ định rõ ràng atom: cho các phần tử trong nguồn cấp dữ liệu định dạng Atom.
Các bảng sau đây trình bày cách thể hiện Atom của các thành phần trong giản đồ. Tất cả dữ liệu không được đề cập trong các bảng này đều được coi là XML thuần tuý. Trừ khi được chỉ định khác, các phần tử XML trong một cột nhất định nằm trong không gian tên Atom.
Lưu ý: Bản tóm tắt này sử dụng ký hiệu CUE chuẩn: dấu gạch chéo thể hiện hệ phân cấp phần tử và dấu @ cho biết thuộc tính của phần tử.
Trong mỗi bảng sau, bạn cần điền các mục được làm nổi bật.
Bảng sau đây trình bày các thành phần của một nguồn cấp dữ liệu Giao thức dữ liệu của Google:
| Mục giản đồ nguồn cấp dữ liệu | Đại diện nguyên tử |
|---|---|
| Tiêu đề của nguồn cấp dữ liệu | /feed/title |
| ID nguồn cấp dữ liệu | /feed/id |
| Đường liên kết HTML của nguồn cấp dữ liệu | /feed/link[@rel="alternate"] [@type="text/html"]/@href |
| Mô tả nguồn cấp dữ liệu | /feed/subtitle |
| Ngôn ngữ của nguồn cấp dữ liệu | /feed/@xml:lang |
| Bản quyền trên nguồn cấp dữ liệu | /feed/rights |
| Tác giả của nguồn cấp dữ liệu |
(Bắt buộc trong một số trường hợp; xem thông số kỹ thuật Atom.) |
| Ngày cập nhật nguồn cấp dữ liệu gần đây nhất | /feed/updated(Định dạng RFC 3339) |
| Danh mục nguồn cấp dữ liệu | /feed/category/@term |
| Lược đồ danh mục nguồn cấp dữ liệu | /feed/category/@scheme |
| Trình tạo nguồn cấp dữ liệu | /feed/generator/feed/generator/@uri |
| Biểu tượng nguồn cấp dữ liệu | /feed/icon |
| Biểu tượng của nguồn cấp dữ liệu | /feed/logo |
Bảng sau trình bày các thành phần của nguồn cấp dữ liệu kết quả tìm kiếm Giao thức dữ liệu của Google. Lưu ý: Giao thức này hiển thị một số phần tử Phản hồi của OpenSearch 1.1 trong nguồn cấp dữ liệu về kết quả tìm kiếm.
| Mục lược đồ nguồn cấp dữ liệu kết quả tìm kiếm | Đại diện nguyên tử |
|---|---|
| Số lượng kết quả tìm kiếm | /feed/openSearch:totalResults |
| Chỉ mục bắt đầu kết quả tìm kiếm | /feed/openSearch:startIndex |
| Số kết quả tìm kiếm trên mỗi trang | /feed/openSearch:itemsPerPage |
Bảng sau đây cho thấy các thành phần của một mục nhập Giao thức dữ liệu của Google:
| Mục giản đồ mục nhập | Đại diện nguyên tử |
|---|---|
| Mã mục nhập | /feed/entry/id |
| Tiêu đề mục nhập | /feed/entry/title |
| Đường liên kết đến mục nhập | /feed/entry/link |
| Tóm tắt thông tin đăng ký |
(Bắt buộc trong một số trường hợp; xem thông số kỹ thuật Atom.) |
| Nội dung nhập |
(Nếu không có phần tử nội dung nào thì mục nhập phải chứa ít nhất một phần tử |
| Tác giả nhập môn |
(Bắt buộc trong một số trường hợp; xem thông số kỹ thuật Atom.) |
| Danh mục nhập | /feed/entry/category/@term |
| Lược đồ danh mục mục nhập | /feed/entry/category/@scheme |
| Ngày phát hành mục | /feed/entry/published(RFC 3339) |
| Ngày cập nhật mục nhập | /feed/entry/updated(RFC 3339) |
Cụm từ tìm kiếm
Phần này mô tả cách sử dụng hệ thống truy vấn.
Nguyên lý thiết kế mô hình truy vấn
Mô hình truy vấn có chủ đích rất đơn giản. Nguyên tắc cơ bản là:
- Các truy vấn được biểu thị dưới dạng URI HTTP, chứ không phải là tiêu đề HTTP hoặc như một phần của trọng tải. Một lợi ích của phương pháp này là bạn có thể liên kết với truy vấn.
- Các thuộc tính nằm trong phạm vi một mục. Vì vậy, không có cách nào để gửi một cụm từ tìm kiếm tương quan như "tìm tất cả email từ những người đã gửi cho tôi ít nhất 10 email trong hôm nay".
- Tập hợp các thuộc tính mà truy vấn có thể dự đoán rất hạn chế; hầu hết các truy vấn chỉ đơn giản là truy vấn tìm kiếm văn bản đầy đủ.
- Thứ tự kết quả phụ thuộc vào việc triển khai.
- Giao thức này có thể mở rộng tự nhiên. Nếu muốn hiển thị các thuộc tính hoặc sắp xếp bổ sung trong dịch vụ, bạn có thể dễ dàng thực hiện thông qua việc giới thiệu các tham số mới.
Yêu cầu truy vấn
Một ứng dụng truy vấn dịch vụ của Google bằng cách gửi một yêu cầu HTTP GET. URI truy vấn bao gồm URI của tài nguyên (được gọi là FeedURI trong Atom) sau đó là tham số truy vấn. Hầu hết các tham số truy vấn được biểu thị dưới dạng tham số URL ?name=value[&...] truyền thống. Thông số danh mục được xử lý khác nhau; hãy xem bên dưới.
Ví dụ: nếu URI URI là http://www.example.com/feeds/jo, thì bạn có thể gửi truy vấn với URI sau:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Giao thức dữ liệu của Google hỗ trợ GET có điều kiện HTTP. Các API triển khai giao thức sẽ đặt tiêu đề phản hồi Sửa đổi lần cuối dựa trên giá trị của phần tử <atom:updated> trong nguồn cấp dữ liệu hoặc mục được trả về. Một ứng dụng có thể gửi lại giá trị này dưới dạng giá trị của tiêu đề yêu cầu If-Sửa đổi-Từ để tránh truy xuất lại nội dung nếu nội dung đó chưa thay đổi. Nếu nội dung không thay đổi kể từ thời gian If-Sửa đổi từ thì dịch vụ sẽ trả về phản hồi HTTP 304 (Không sửa đổi).
API triển khai Giao thức dữ liệu Google phải hỗ trợ các truy vấn alt; việc hỗ trợ các thông số khác là không bắt buộc. Việc chuyển một thông số chuẩn không được dịch vụ nhất định hiểu được sẽ dẫn đến một phản hồi 403 Forbidden. Truyền một tham số không chuẩn không được hỗ trợ sẽ dẫn đến một phản hồi 400 Bad Request. Để biết thông tin về các mã trạng thái khác, hãy xem phần Mã trạng thái HTTP của tài liệu này.
Các tham số truy vấn chuẩn được tóm tắt trong bảng sau. Tất cả giá trị thông số cần phải được mã hóa URL.
| Thông số | Ý nghĩa | Ghi chú |
|---|---|---|
alt |
Loại hình đại diện thay thế |
|
author |
Tác giả nhập môn |
|
category |
Bộ lọc truy vấn danh mục |
|
/-/category |
Bộ lọc truy vấn danh mục |
|
| entryID | Mã của một mục cụ thể sẽ được truy xuất |
|
fields |
Bộ lọc phản hồi |
|
max-results |
Số lượng kết quả truy xuất tối đa | Đối với dịch vụ có giá trị max-results mặc định (để giới hạn kích thước nguồn cấp dữ liệu mặc định), bạn có thể chỉ định một số rất lớn nếu muốn nhận toàn bộ nguồn cấp dữ liệu. |
prettyprint |
Trả về phản hồi XML có các ký tự nhận dạng và ngắt dòng |
|
published-min, published-max |
Ranh giới vào ngày xuất bản mục |
|
q |
Chuỗi truy vấn văn bản đầy đủ |
|
start-index |
1 chỉ mục dựa trên kết quả đầu tiên được truy xuất |
|
strict |
Kiểm tra tham số truy vấn nghiêm ngặt |
|
updated-min, updated-max |
Ranh giới vào ngày cập nhật mục nhập |
|
Giới thiệu về truy vấn danh mục
Chúng tôi quyết định cung cấp một định dạng không bình thường cho các truy vấn danh mục. Thay vì yêu cầu một truy vấn như sau:
http://example.com/jo?category=Fritz&category=2006
chúng tôi có thể sử dụng:
http://example.com/jo/-/Fritz/2006
Phương pháp này xác định một tài nguyên không cần sử dụng tham số truy vấn và tạo ra URI sạch hơn. Chúng tôi chọn phương pháp này cho danh mục vì chúng tôi nghĩ rằng truy vấn danh mục sẽ nằm trong số những truy vấn phổ biến nhất.
Hạn chế của phương pháp này là chúng tôi yêu cầu bạn sử dụng /-/ trong loại truy vấn danh mục này để dịch vụ có thể phân biệt truy vấn danh mục với URI tài nguyên khác, chẳng hạn như http://example.com/jo/MyPost/comments.
Câu trả lời cho cụm từ tìm kiếm
Các truy vấn trả về nguồn cấp dữ liệu Atom, mục nhập Atom hoặc nguồn cấp dữ liệu RSS, tuỳ thuộc vào thông số yêu cầu.
Kết quả truy vấn chứa các phần tử OpenSearch sau đây ngay trong phần tử <feed> hoặc phần tử <channel> (tuỳ thuộc vào việc kết quả là Atom hay RSS):
openSearch:totalResults- Tổng số kết quả tìm kiếm cho cụm từ tìm kiếm (không nhất thiết phải có tất cả kết quả trong nguồn cấp dữ liệu về kết quả).
openSearch:startIndex- Chỉ mục dựa trên 1 của kết quả đầu tiên.
openSearch:itemsPerPage- Số lượng mục tối đa xuất hiện trên một trang. Điều này cho phép khách hàng tạo các đường liên kết trực tiếp đến mọi nhóm trang tiếp theo. Tuy nhiên, nếu sử dụng số điện thoại này có sai lầm có thể xảy ra, hãy xem lưu ý về
start-indextrong bảng trong phần Yêu cầu truy vấn.
Nguồn cấp dữ liệu phản hồi và mục nhập Atom cũng có thể bao gồm mọi phần tử Atom và Data API sau (cũng như các phần tử khác liệt kê trong quy cách Atom):
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- Chỉ định URI nơi có thể truy xuất nguồn cấp dữ liệu Atom hoàn chỉnh.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- Chỉ định URI URI của nguồn cấp dữ liệu Atom (nơi có thể đăng các mục nhập mới).
<link rel="self" type="..." href="..."/>- Chứa URI của tài nguyên này. Giá trị của thuộc tính
typephụ thuộc vào định dạng đã yêu cầu. Nếu không có dữ liệu thay đổi trong thời gian chờ đợi, việc gửi một GET khác đến URI này sẽ trả về cùng một phản hồi. <link rel="previous" type="application/atom+xml" href="..."/>- Chỉ định URI của phần trước của tập hợp kết quả truy vấn này, nếu phần này được chia nhỏ.
<link rel="next" type="application/atom+xml" href="..."/>- Chỉ định URI của phân đoạn tiếp theo của nhóm kết quả truy vấn này nếu phân đoạn.
<link rel="edit" type="application/atom+xml" href="..."/>- Chỉ định URI URI của mục nhập Atom (nơi bạn gửi mục đã cập nhật).
Dưới đây là nội dung phản hồi mẫu, để phản hồi một truy vấn tìm kiếm:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
Nếu nguồn cấp dữ liệu được yêu cầu ở định dạng Atom, nếu không có tham số truy vấn nào được chỉ định và nếu kết quả không chứa tất cả các mục nhập, thì phần tử sau đây sẽ được chèn vào nguồn cấp dữ liệu cấp cao nhất: <link rel="next" type="application/atom+xml" href="..."/>. Nó trỏ đến một nguồn cấp dữ liệu chứa tập hợp các mục nhập tiếp theo. Các nhóm tiếp theo chứa một phần tử <link rel="previous" type="application/atom+xml" href="..."/> tương ứng. Bằng cách nhấp vào tất cả các đường liên kết tiếp theo, ứng dụng có thể truy xuất tất cả mục nhập từ một nguồn cấp dữ liệu.
Mã trạng thái HTTP
Bảng sau đây mô tả ý nghĩa của các mã trạng thái HTTP trong ngữ cảnh của API dữ liệu.
| Mã | Giải thích |
|---|---|
| 200 OK | Không có lỗi. |
| 201 ĐÃ TẠO | Đã tạo thành công tài nguyên. |
| 304 KHÔNG ĐƯỢC CHỈNH SỬA | Tài nguyên không thay đổi kể từ thời gian chỉ định trong tiêu đề If-Sửa đổi-Từ khi yêu cầu. |
| 400 YÊU CẦU KHÔNG TỐT | URI hoặc tiêu đề của yêu cầu không hợp lệ, hoặc tham số không chuẩn được hỗ trợ. |
| 401 KHÔNG ĐƯỢC uỷ quyền | Cần có sự cho phép. |
| 403 LẦM TIẾN | Không xác thực được thông số chuẩn, hoặc việc xác thực hay uỷ quyền không được hỗ trợ. |
| 404 KHÔNG TÌM THẤY | Không tìm thấy tài nguyên (chẳng hạn như nguồn cấp dữ liệu hoặc mục nhập). |
| 409 TRUNG BÌNH | Số phiên bản đã chỉ định không khớp với số phiên bản mới nhất của tài nguyên. |
| 410 GONE | Nhật ký thay đổi được yêu cầu không còn trên máy chủ. Hãy tham khảo tài liệu về dịch vụ cụ thể để biết thêm chi tiết. |
| 500 LỖI MÁY CHỦ NỘI BỘ | Lỗi nội bộ. Đây là mã mặc định được sử dụng cho tất cả các lỗi máy chủ không xác định. |
Tạo phiên bản tài nguyên (ETag)
Đôi khi, bạn cần tham chiếu đến một phiên bản cụ thể của một mục cụ thể.
Điều này đặc biệt quan trọng trong hai trường hợp cụ thể:
- Thực hiện "truy xuất có điều kiện", trong đó ứng dụng của bạn yêu cầu một mục nhập và máy chủ chỉ gửi mục nhập nếu mục đó đã thay đổi kể từ lần gần nhất máy khách yêu cầu.
- Đảm bảo rằng nhiều khách hàng không vô tình ghi đè các thay đổi của nhau. API dữ liệu thực hiện việc này bằng cách thực hiện các thao tác cập nhật và xoá nếu ứng dụng chỉ định giá trị nhận dạng phiên bản cũ cho mục nhập.
API Dữ liệu của Google xử lý cả hai trường hợp này bằng cách sử dụng ETag, một phần tiêu chuẩn của HTTP.
ETag là một giá trị nhận dạng chỉ định một phiên bản cụ thể của một mục cụ thể. Máy chủ sẽ đính kèm một thẻ ETag vào các mục nhập và nguồn cấp dữ liệu mà nó gửi tới máy khách. Khi một mục nhập hoặc nguồn cấp dữ liệu thay đổi, ETag cũng sẽ thay đổi.
API Dữ liệu của Google cung cấp ETag ở hai nơi: trong tiêu đề HTTP ETag và trong một thuộc tính gd:etag của các phần tử <feed> và <entry>.
Trong API dữ liệu của Google, ETag thường là một chuỗi chữ cái và số, đôi khi cũng bao gồm dấu gạch nối và dấu chấm; chuỗi thường được đặt trong dấu ngoặc kép. (Dấu ngoặc kép là một phần của ETag.) Ví dụ: đây là ETag từ một mục Data API: "S0wCTlpIIip7ImA0X0QI".
Có hai loại ETag: mạnh và yếu. Thẻ Estrong mạnh xác định một phiên bản cụ thể của một mục cụ thể và có thể được sử dụng để tránh ghi đè thay đổi của khách hàng khác. Trong bối cảnh của các API Dữ liệu của Google, điểm E yếu, chỉ được dùng để truy xuất có điều kiện. Một ETag yếu luôn bắt đầu bằng W/. Ví dụ: W/"D08FQn8-eil7ImA9WxZbFEw."
Không phải tất cả API dữ liệu của Google đều hỗ trợ thẻ ETag mạnh. Đối với những trường hợp như vậy, ETag mạnh chỉ được sử dụng cho các mục nhập; ETag trên nguồn cấp dữ liệu luôn yếu.
Dưới đây là ví dụ về nguồn cấp dữ liệu (bao gồm cả một số tiêu đề HTTP) được truy xuất từ một dịch vụ hỗ trợ ETag mạnh:
GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
...
<entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
...
</entry>
</feed>
Các thư viện ứng dụng hỗ trợ phiên bản 2 của API dữ liệu sẽ xử lý ETag một cách minh bạch. Thông tin sau dành cho các ứng dụng khách không sử dụng thư viện ứng dụng và cho các độc giả quan tâm đến cách xử lý phiên bản ở cấp giao thức.
Lưu ý: Để biết thông tin về hệ thống phiên bản tài nguyên được sử dụng trong phiên bản 1.0 của API dữ liệu, hãy xem hướng dẫn tham khảo 1.0.
Truy xuất có điều kiện
Nếu muốn truy xuất một mục mà bạn đã truy xuất trước đó, bạn có thể cải thiện hiệu quả bằng cách yêu cầu máy chủ chỉ gửi mục nhập nếu mục đó đã thay đổi kể từ lần truy xuất gần đây nhất.
Để thực hiện loại truy xuất có điều kiện này, hãy gửi một yêu cầu HTTP GET bao gồm tiêu đề HTTP If-None-Match. Trong tiêu đề, hãy chỉ định ETag của mục nhập.
Dưới đây là ví dụ về tiêu đề If-None-Match:
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
Khi nhận được yêu cầu này, máy chủ sẽ kiểm tra xem liệu mục nhập mà bạn yêu cầu có giống ETag với ETag mà bạn đã chỉ định hay không. Nếu ETag khớp, thì mục nhập sẽ không thay đổi và máy chủ trả về mã trạng thái HTTP 304 Not Modified.
Nếu ETag không khớp, thì mục nhập đã được sửa đổi kể từ lần bạn yêu cầu gần đây nhất và máy chủ sẽ trả về mục nhập.
Đang cập nhật mục nhập
Cách dễ nhất để tránh ghi đè thay đổi của một ứng dụng khách khác là đảm bảo rằng khi máy khách của bạn gửi mục nhập đã cập nhật, phiên bản của mục nhập mà ứng dụng bắt đầu giống với phiên bản hiện tại được máy chủ lưu trữ. Nếu ứng dụng thứ hai cập nhật trước khi ứng dụng thực hiện, thì bản cập nhật của ứng dụng bị từ chối vì ứng dụng không còn dựa trên các nội dung sửa đổi trên phiên bản mới nhất nữa.
Khi ứng dụng của bạn truy xuất dữ liệu từ một dịch vụ hỗ trợ ETag mạnh, mỗi mục nhập có một ETag hoạt động như một giá trị nhận dạng phiên bản duy nhất cho phiên bản của mục đó.
Lưu ý: Việc cập nhật bằng ETag chỉ hoạt động với những ETag mạnh. Đối với các dịch vụ cung cấp ETag yếu, tất cả các bản cập nhật đều thành công, bất kể có người nào khác đã cập nhật mục nhập kể từ khi bạn truy xuất; bản cập nhật mới nhất luôn ghi đè mọi bản cập nhật trước đó khác. Vì vậy, đừng gửi ETag yếu khi cập nhật hoặc xóa; bạn sẽ nhận được thông báo lỗi nếu bạn làm như vậy.
Vì vậy, khi ứng dụng khách của bạn gửi bản cập nhật đến một dịch vụ ETag mạnh, ứng dụng cần chỉ định phiên bản của mục mà ứng dụng đang cập nhật. Có hai cách để thực hiện việc này:
- Dùng tiêu đề HTTP
If-Match. - Dùng thuộc tính
gd:etagtrong phần tử<atom:entry>.
Bạn nên sử dụng phương pháp If-Match nếu có thể.
Để cập nhật một mục nhập bằng If-Match, hãy bắt đầu bằng cách thu nạp mục nhập bạn đang cập nhật. Thực hiện mọi thay đổi mong muốn đối với mục nhập, sau đó tạo một yêu cầu PUT mới chứa mục nhập đã sửa đổi. (Để biết thông tin chi tiết về URL cần sử dụng, hãy xem tài liệu dành riêng cho dịch vụ.)
Trước khi gửi PUT, hãy thêm tiêu đề HTTP If-Match chứa ETag từ mục nhập ban đầu:
If-Match: "S0wCTlpIIip7ImA0X0QI"
Sau đó, hãy gửi yêu cầu PUT.
Nếu cập nhật thành công, máy chủ sẽ trả về mã trạng thái HTTP 200 OK và bản sao của mục nhập đã cập nhật.
Nếu cập nhật không thành công vì ETag mà bạn đã chỉ định không khớp với ETag hiện tại trên mục nhập (ám chỉ rằng mục nhập đã thay đổi trên máy chủ kể từ lần cuối bạn truy xuất nó), máy chủ sẽ trả về mã trạng thái HTTP 412 Precondition Failed.
Nếu không thể dễ dàng viết tiêu đề HTTP hoặc có lý do nào đó để tránh sử dụng tiêu đề If-Match, bạn có thể sử dụng thuộc tính gd:etag.
Nếu bạn không gửi tiêu đề If-Match thì máy chủ sẽ sử dụng giá trị thuộc tính gd:etag của mục nhập đã cập nhật làm giá trị If-Match ngụ ý.
Để ghi đè hệ thống tạo phiên bản và cập nhật mục nhập bất kể người khác có cập nhật mục đó kể từ khi bạn truy xuất hay không, hãy sử dụng If-Match: * thay vì chỉ định ETag trong tiêu đề.
Để biết thông tin về những dịch vụ hỗ trợ thẻ E yếu, hãy xem Hướng dẫn di chuyển.
Đang xoá các mục
Xóa các mục nhập sử dụng ETag mạnh hoạt động giống như cập nhật các mục nhập đó.
Để xóa một mục có ETag mạnh, trước tiên bạn truy xuất mục mình muốn xóa, sau đó bạn gửi yêu cầu DELETE đến URL chỉnh sửa của mục đó.
Nếu muốn đảm bảo rằng bạn không xoá một mục đã được một khách hàng khác thay đổi kể từ khi bạn truy xuất mục đó, hãy đưa vào tiêu đề HTTP If-Match chứa giá trị ETag của mục nhập ban đầu.
Nếu bạn muốn ghi đè hệ thống tạo phiên bản và xoá mục nhập, bất kể người khác có cập nhật mục đó kể từ khi bạn truy xuất hay không, hãy sử dụng If-Match: * thay vì chỉ định ETag trong tiêu đề.
Nếu một mục không có ETag mạnh, thì yêu cầu DELETE sẽ luôn thành công.
Phản hồi một phần (Thử nghiệm)
Theo mặc định, máy chủ sẽ gửi lại bản trình bày đầy đủ về tài nguyên đích sau khi xử lý các yêu cầu. Phản hồi một phần chỉ cho phép bạn yêu cầu các yếu tố hoặc thuộc tính quan tâm, thay vì yêu cầu thể hiện đầy đủ tài nguyên. Điều này cho phép ứng dụng của bạn tránh chuyển, phân tích cú pháp và lưu trữ các trường không cần thiết, để ứng dụng có thể sử dụng tài nguyên mạng, CPU và bộ nhớ hiệu quả hơn.
Để tìm hiểu xem sản phẩm mà bạn đang sử dụng có phản hồi một phần hay không, hãy xem tài liệu về API này.
Để yêu cầu phản hồi một phần, hãy sử dụng tham số truy vấn fields để chỉ định các phần tử hoặc thuộc tính bạn muốn trả về. Dưới đây là ví dụ:
http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))
Phản hồi của máy chủ chỉ chứa các yếu tố liên kết và yếu tố nhập cho nguồn cấp dữ liệu; các yếu tố mục nhập chỉ chứa ETag, ID, thông tin cập nhật và chỉnh sửa thông tin liên kết. Cú pháp tham số truy vấn fields được đề cập trong các phần sau. Để biết thêm thông tin về câu trả lời, hãy xem phần Xử lý một phần câu trả lời.
Lưu ý: Bạn có thể sử dụng tham số truy vấn fields với bất kỳ yêu cầu nào trả về dữ liệu. Ngoài GET, các kênh này bao gồm POST và PUT (cũng như PATCH, được dùng để cập nhật một phần). Tuy nhiên, tham số truy vấn fields chỉ ảnh hưởng đến dữ liệu phản hồi. Tham số này không ảnh hưởng đến dữ liệu mà bạn phải cung cấp hoặc những trường nào được cập nhật hoặc tạo.
Tóm tắt cú pháp thông số trường
Định dạng của giá trị tham số truy vấn fields dựa trên cú pháp đích; tuy nhiên, định dạng này chỉ hỗ trợ một tập hợp con các biểu thức CUE hợp lệ. Cú pháp được hỗ trợ được tóm tắt bên dưới và ví dụ bổ sung được cung cấp trong phần sau.
- Sử dụng danh sách được phân tách bằng dấu phẩy để chọn một số trường.
- Dùng
a/bđể chọn một phần tửblồng trong phần tửa; dùnga/b/cđể chọn một phần tửclồng trongb. - Dùng tiền tố
'@'để xác định một thuộc tính có tên nhất định; bỏ qua tiền tố'@'để tham chiếu đến một phần tử. - Áp dụng các điều kiện của trường để chọn các phần tử phù hợp với tiêu chí nhất định, bằng cách đặt biểu thức trong dấu ngoặc "
[ ]" sau phần tử mà bạn muốn hạn chế.Ví dụ:
fields=entry[author/name='Elizabeth']chỉ trả về các mục nguồn cấp dữ liệu mà Elizabeth là tác giả. - Bạn có thể chỉ định các lựa chọn phụ trong trường để chỉ yêu cầu các thuộc tính hoặc phần tử phụ cụ thể, bằng cách đặt biểu thức trong dấu ngoặc đơn "
( )" sau phần tử đã chọn bất kỳ.Ví dụ:
fields=entry(id,author/email)chỉ trả về mã nhận dạng và email của tác giả cho mỗi mục nguồn cấp dữ liệu. - Bạn có thể phân tách các chuỗi bằng cách sử dụng dấu ngoặc kép hoặc một dấu ngoặc kép
.
Để thoát khỏi dấu nháy kép hoặc dấu nháy đơn, hãy lặp lại dấu ngoặc kép. Ví dụ:"""Hello,"" he said"tạo chuỗi"Hello," he saidvà'''Hello,'' he said'tạo chuỗi'Hello,' he said. - Bạn có thể sử dụng ký tự đại diện trong các lựa chọn trường.
Ví dụ:
entry/gd:*chọn tất cả các phần tử con của mục nhập trong không gian têngd, cònentry/@gd:*chọn các thuộc tính phần tử con trong cùng một không gian tên.
Tham số truy vấn fields đóng vai trò là bộ lọc đầu ra. Tức là nội dung phản hồi một phần chỉ được tính sau khi xử lý phần còn lại của truy vấn. Ví dụ: nếu bạn cũng chỉ định tham số truy vấn max-results để cho biết rằng bạn muốn 20 kết quả trên mỗi trang, thì 20 kết quả đầu tiên được tạo và phản hồi một phần sẽ được tính từ đó. Nếu quy cách fields không khớp với bất kỳ mục nào trong số 20 mục đầu tiên do truy vấn chọn, thì bạn sẽ nhận lại nguồn cấp dữ liệu trống. Bạn không nhận lại được 20 mục đầu tiên phù hợp.
Lưu ý: Không cố sử dụng các điều kiện của trường làm bộ chọn truy vấn. Điều này nghĩa là không cố gắng truy xuất nguồn cấp dữ liệu đầy đủ và áp dụng điều kiện của trường để lọc ra các mục quan tâm từ tập dữ liệu rất lớn. Bất cứ khi nào có thể, hãy sử dụng các tham số truy vấn khác, chẳng hạn như start-index và max-results, để giảm kết quả của mỗi truy vấn xuống kích thước có thể quản lý được. Nếu không, mức tăng hiệu suất có thể đạt được khi phản hồi một phần có thể lớn hơn sự suy giảm nghiêm trọng về hiệu suất do sử dụng không đúng cách.
Định dạng giá trị thông số trường
Các nguyên tắc sau giải thích cách tạo giá trị tham số truy vấn fields. Mỗi nguyên tắc bao gồm các ví dụ và cung cấp mô tả về mức độ ảnh hưởng của giá trị thông số đối với phản hồi.
Lưu ý: Giống như với tất cả các giá trị tham số truy vấn, giá trị tham số fields phải được mã hóa URL. Để dễ đọc hơn, các ví dụ bên dưới sẽ bỏ qua phần mã hoá.
- Xác định các trường bạn muốn trả về hoặc chọn trường.
- Giá trị tham số truy vấn
fieldslà danh sách các phần tử hoặc thuộc tính được phân tách bằng dấu phẩy (gọi chung là các trường) và mỗi trường được chỉ định tương ứng với phần tử gốc của bản trình bày tài nguyên. Do đó, nếu bạn đang truy xuất nguồn cấp dữ liệu, thì các trường sẽ được chỉ định tương ứng với phần tử<feed>, còn nếu bạn đang truy xuất một mục, thì các trường sẽ được chỉ định tương ứng với phần tử<entry>. Nếu phần tử bạn chọn là (hoặc là một phần) của một phần tử lặp lại trong nguồn cấp dữ liệu, thì dịch vụ sẽ trả về tất cả các phần tử của phần tử đó.
Sau đây là một số ví dụ ở cấp nguồn cấp dữ liệu:
Ví dụ Hiệu quả entryTrả về tất cả các phần tử <entry>và tất cả các phần tử phụ của các mục đó, nhưng không trả về bất kỳ phần tử con nào khác của<feed>.id,entryTrả về cả nguồn cấp dữ liệu <id>và tất cả phần tử<entry>.entry/titleTrả về phần tử <title>cho tất cả các mục trong nguồn cấp dữ liệu.
Bất cứ khi nào một phần tử lồng nhau được trả về, phản hồi sẽ bao gồm các thẻ đính kèm cho bất kỳ phần tử mẹnào. Thẻ mẹ không chứa các phần tử hoặc thuộc tính con khác, trừ phi các thẻ này cũng được chọn rõ ràng.entry/author/uriChỉ trả về phần tử phụ <uri>của phần tử<author>cho tất cả các mục trong nguồn cấp dữ liệu.entry/*:ratingChỉ trả về các phần tử phụ có tên cục bộ ratingtrong mọi không gian tên cho tất cả các mục nhập nguồn cấp dữ liệu.
Sau đây là một số ví dụ về cấp truy cập:
Ví dụ Hiệu quả authorTrả về phần tử con <author>của mục nhập mục tiêu.@gd:etagTrả về thuộc tính etagcủa mục đích.author/uriTrả về phần tử phụ <uri>của phần tử<author>cho mục nhập mục tiêu.media:group/media:*Trả về tất cả các trường phụ của <media:group>trong không gian tênmediacho mục tiêu mục tiêu. - Hạn chế phản hồi cho các trường đã chọn phù hợp với tiêu chí nhất định hoặc sử dụng điều kiện của trường.
- Theo mặc định, nếu yêu cầu của bạn chỉ định một phần tử xuất hiện nhiều lần, thì phản hồi một phần sẽ bao gồm tất cả các phiên bản của phần tử đó. Tuy nhiên, bạn cũng có thể chỉ định rằng phản hồi chỉ nên bao gồm các phần tử có một giá trị thuộc tính cụ thể hoặc các phần tử đáp ứng một số điều kiện khác bằng cú pháp "
[ ]", như trong các ví dụ bên dưới. Xem mục cú pháp điều kiện của trường để biết thêm thông tin chi tiết.Ví dụ Hiệu quả entry[link/@rel='edit']Trả về bất kỳ mục nhập nguồn cấp dữ liệu nào chứa phần tử <link>có giá trị thuộc tínhrellà'edit'.entry/title[text()='Today']Trả về bất kỳ phần tử <title>nào xuất hiện trong mục nhập nguồn cấp dữ liệu nếu nội dung của các phần tử đó là'Today'.entry/author[name='Jo']Trả về bất kỳ phần tử <author>nào xuất hiện trong mục nhập nguồn cấp dữ liệu nếu các phần tử đó có phần tử phụ<name>có nội dung'Jo'.author[name='Jo']Trả về phần tử <author>trong mục nhập mục tiêu nếu phần tử đó có phần tử phụ<name>có nội dung'Jo'. - Chỉ yêu cầu các phần của phần tử đã chọn hoặc sử dụng lựa chọn phụ của trường.
- Theo mặc định, nếu yêu cầu của bạn chỉ định các phần tử cụ thể, thì dịch vụ sẽ trả về toàn bộ các phần tử. Bạn có thể chỉ định nội dung phản hồi chỉ nên bao gồm một số phần tử phụ nhất định trong các phần tử đã chọn. Bạn thực hiện việc này bằng cách sử dụng cú pháp lựa chọn phụ "
( )", như trong các ví dụ bên dưới.Ví dụ Hiệu quả entry/author(uri)Chỉ trả về phần tử phụ <uri>cho tác giả trong các mục nhập nguồn cấp dữ liệu.entry/author[name='Jo'](uri)Chỉ trả về phần tử phụ <uri>của<author>cho bất kỳ mục nhập nào có tên tác giả là'Jo'.entry(link(@rel,@href))Chỉ trả về các giá trị của thuộc tính relvàhrefcho từng phần tử<link>trong các mục nhập của nguồn cấp dữ liệu.entry(title,link[@rel='edit'])Chỉ trả về các phần tử <title>và<link>có thuộc tínhrelchỉnh sửa cho mỗi mục nhập nguồn cấp dữ liệu.entry(title,author(uri)Trả về cả hai phần tử <title>và các phần tử tác giả<uri>cho mỗi mục nhập nguồn cấp dữ liệu.
Tìm hiểu thêm về cú pháp điều kiện của trường
Bạn có thể sử dụng các điều kiện cho trường với các trường hoặc trường phụ. Điều kiện phải đánh giá là đúng để trường đã chọn được đưa vào kết quả.Nếu không có điều kiện về trường thì sẽ bao gồm tất cả các trường thuộc loại đã chọn.
Giá trị văn bản của trường đã chọn được dùng để so sánh. Trong trường hợp này, nếu trường là một phần tử, thì giá trị văn bản là nội dung của nó; nếu trường là một thuộc tính, thì giá trị văn bản là giá trị của thuộc tính. Nếu trường không có giá trị văn bản thì so sánh không thành công và trường đó không được bao gồm trong kết quả.
Bảng sau đây trình bày các toán tử JavaScript được hỗ trợ cho các điều kiện của trường và cung cấp một số ví dụ.
| Nhà vận hành | Cú pháp | Ví dụ |
|---|---|---|
| So sánh chuỗi |
|
|
| So sánh logic | and |
|
| So sánh số | = hoặc eq!= hoặc ne> hoặc gt>= hoặc ge< hoặc lt<= hoặc le
|
|
| So sánh ngày | Sử dụng toán tử so sánh số, như trong ví dụ. | Để so sánh ngày hoặc ngày/giờ, bạn có thể truyền các phần tử, thuộc tính hoặc giá trị cố định kiểu chuỗi vào
|
| Sự tồn tại | Sử dụng tên của phần tử hoặc thuộc tính như trong các ví dụ. |
|
| Boolean | true()false()
|
Boolean có thể hữu ích trong quá trình thử nghiệm để buộc các điều kiện của trường chuyển sang trạng thái đúng hoặc sai.
|
Xử lý các phản hồi một phần
Sau khi máy chủ hỗ trợ phản hồi một phần xử lý một yêu cầu hợp lệ chứa tham số truy vấn fields, thì máy chủ sẽ gửi lại mã trạng thái HTTP 200 OK cùng với các thuộc tính hoặc phần tử được yêu cầu. Nếu tham số truy vấn fields có lỗi hoặc không hợp lệ, máy chủ sẽ trả về mã trạng thái HTTP 400 Bad Request.
Phần tử gốc của phản hồi là <feed> hoặc <entry>, tuỳ thuộc vào URI mục tiêu. Nội dung của phần tử gốc chỉ bao gồm các trường đã chọn cho nguồn cấp dữ liệu hoặc mục nhập đó, cùng với các thẻ đính kèm cho bất kỳ phần tử mẹ nào.
Bạn có thể lặp lại giá trị của tham số truy vấn fields của yêu cầu theo hai cách:
- Phần tử gốc có một thuộc tính
gd:fieldscho biết giá trị của tham số truy vấnfieldsđược chỉ định trong yêu cầu. - Nếu URI mục tiêu là nguồn cấp dữ liệu, mỗi mục có thể chỉnh sửa có thuộc tính
gd:fieldshiển thị phần lựa chọnfieldssẽ áp dụng cho thuộc tính đó.
Lưu ý: Để xem các giá trị thuộc tính gd:fields này trong phản hồi một phần của mình, bạn phải đưa các giá trị đó vào thông số kỹ thuật của tham số truy vấn fields. Bạn có thể thực hiện rõ ràng bằng cách sử dụng @gd:fields hoặc sử dụng @gd:* chung hơn, bao gồm cả thông tin ETag.
Truy vấn mẫu sau đây yêu cầu máy chủ trả về một tài liệu chỉ chứa các thuộc tính trong vùng chứa tên gd (ở cả nguồn cấp dữ liệu và mục nhập), cũng như mã nhận dạng nguồn cấp dữ liệu, tiêu đề và đường liên kết chỉnh sửa cho từng mục nhập của nguồn cấp dữ liệu:
http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])
Máy chủ trả về phản hồi một phần sau đây cùng với mã trạng thái HTTP 200 Successful:
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
<id>http://example.com/myFeed</id>
<entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/1/'/>
<title>This year</title>
</entry>
<entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/2/'/>
<title>Last year</title>
</entry>
<entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/3/'/>
<title>Today</title>
</entry>
</feed>
Nếu các trường được chọn không khớp với bất kỳ thông tin nào, thì dịch vụ vẫn sẽ trả về mã trạng thái HTTP 200 Successful, nhưng phản hồi một phần là nguồn cấp dữ liệu trống:
<?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."' gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])> </feed>
Cập nhật một phần (Thử nghiệm)
Các sản phẩm của Google hỗ trợ phản hồi một phần và tài nguyên có thể chỉnh sửa cũng cho phép bạn sử dụng cập nhật một phần. Với cập nhật một phần, bạn chỉ gửi các trường mà bạn muốn cập nhật, thay vì gửi phiên bản sửa đổi của biểu thị tài nguyên đầy đủ. Điều này cho phép ứng dụng của bạn hiệu quả hơn khi cập nhật, cũng như khi sử dụng phản hồi một phần để truy xuất dữ liệu.
Tuy nhiên, thay vì dùng PUT, bạn phải sử dụng yêu cầu PATCH khi cập nhật một phần. Ngữ nghĩa cho PATCH đủ mạnh để cho phép bạn thêm, thay thế và xóa các trường cụ thể cho một mục cụ thể, tất cả chỉ bằng một yêu cầu.
Để tìm hiểu xem sản phẩm mà bạn đang dùng có cập nhật một phần hay không, hãy tham khảo tài liệu dành riêng cho từng sản phẩm.
Gửi yêu cầu cập nhật một phần
Để gửi yêu cầu cập nhật một phần, bạn gửi yêu cầu HTTP PATCH đến chính URL mà bạn thường dùng với PUT để cập nhật tài nguyên. Phần nội dung của yêu cầu PATCH là một phần tử <entry> chỉ định một số trường mà bạn muốn thêm hoặc sửa đổi. Thuộc tính gd:fields của mục nhập cho biết các trường mà bạn muốn xoá.
Máy chủ xử lý các yêu cầu PATCH theo thứ tự cụ thể:
- Trước tiên, thuộc tính này sẽ xoá khỏi đại diện tài nguyên các trường do thuộc tính
gd:fieldschỉ định.Cú pháp cho thuộc tính
gd:fieldsgiống với cú pháp của tham số truy vấnfieldsdùng khi yêu cầu phản hồi một phần. Xem Cú pháp được hỗ trợ để biết thêm chi tiết. - Sau đó, mã này sẽ hợp nhất thành bản trình bày tài nguyên hiện có, cung cấp dữ liệu trong phần nội dung của yêu cầu.
Bạn có thể xem thêm thông tin chi tiết về cách hợp nhất dữ liệu trong mục Thêm hoặc cập nhật các trường bên dưới.
Lưu ý: Vì phần nội dung của yêu cầu PATCH thường không tuân thủ Định dạng phân phối Atom, nên Content-Type mà bạn sử dụng với yêu cầu PATCH sẽ là application/xml.
Sau đây là ví dụ về yêu cầu cập nhật một phần:
PATCH /myFeed/1/1/
Content-Type: application/xml
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:fields='description'>
<title>New title</title>
</entry>
Yêu cầu PATCH này thực hiện những thay đổi sau đối với cách biểu diễn tài nguyên được lưu trữ trên máy chủ cho mục nhập của URI mục tiêu:
- Xoá phần tử
<description>. - Cập nhật phần tử
<title>.
Ngữ nghĩa của một yêu cầu cập nhật một phần
Hướng dẫn dưới đây giải thích cách thiết lập yêu cầu xoá PATCH, thêm hoặc cập nhật các trường cụ thể trong một mục nhập. Một yêu cầu PATCH có thể thực hiện bất kỳ kết hợp nào của các thao tác này.
Xoá trường. Dùng thuộc tính
gd:fieldscủa phần tử<entry>để xác định các trường bạn muốn xoá khỏi tài nguyên. Yêu cầu mẫu sau đây sẽ xoá tiêu đề và nội dung tóm tắt liên kết với một mục. Tuy nhiên, yêu cầu này không thêm hoặc cập nhật dữ liệu nào khác cho mục đó.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='title,summary'/>Thêm hoặc cập nhật các trường. Sử dụng phần nội dung của phần tử
<entry>để chỉ định dữ liệu mà bạn muốn thêm hoặc cập nhật cho một tài nguyên. Các trường này được hợp nhất thành dữ liệu hiện có cho tài nguyên sau khi bạn xóa bất kỳ ai, theo các quy tắc sau:Các trường chưa xuất hiện sẽ được thêm vào. Nếu dữ liệu tài nguyên chưa chỉ định giá trị cho một trường thì trường đó sẽ được thêm vào dữ liệu hiện có. Ví dụ: nếu một mục không có tiêu đề và yêu cầu
PATCHchứa phần tử<title>, thì tiêu đề mới sẽ được thêm vào mục đó.Các trường đã có sẽ được thay thế hoặc thêm vào. Hành vi cụ thể của việc hợp nhất các trường đã được chỉ định trong dữ liệu tài nguyên phụ thuộc vào các đặc điểm của trường:
Các trường không lặp lại sẽ được thay thế. Nếu dữ liệu tài nguyên đã chỉ định một giá trị cho phần tử không lặp lại, thì giá trị bạn chỉ định trong yêu cầu
PATCHsẽ thay thế giá trị hiện có cho phần tử đó. Ví dụ: trong ví dụ bên dưới, tiêu đề mới thay thế cho tiêu đề hiện có.PATCH /myFeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <title>New Title</title> </entry>Hãy xem một ví dụ phức tạp hơn bên dưới. Trong ví dụ này, giả sử mục nhập chỉ có thể có một tác giả và tài nguyên đích đã có giá trị cho tên và địa chỉ email của tác giả. Mặc dù phần tử
<author>có hai trường con, nhưng chỉ có phần tử<name>xuất hiện trong dữ liệu đã cung cấp. Do đó, chỉ có giá trị của trường đó bị ghi đè. Giá trị của phần tử<email>bị thiếu trong dữ liệu được cung cấp vẫn không thay đổi.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <author> <name>New Name</name> </author> </entry>Các trường lặp lại được nối vào. Nếu dữ liệu tài nguyên đã chỉ định một giá trị cho phần tử lặp lại, thì phần tử mới mà bạn cung cấp sẽ được thêm vào tập hợp giá trị hiện có.
Xin lưu ý rằng đôi khi, bạn có thể muốn thực hiện thao tác khác ngoài việc thêm bản sao mới của phần tử lặp lại. Ví dụ: bạn có thể muốn thực hiện một trong các thao tác sau:
Thay thế toàn bộ danh sách các phần tử lặp lại. Bạn có thể xoá tất cả các trường lặp lại bằng cách sử dụng thuộc tính
gd:fields(ví dụ:gd:fields='ns:accessControl') và cung cấp một tập hợp đầy đủ các trường thay thế. Vì tất cả các phần tử hiện có đều bị xóa trước nên tập hợp các trường bạn cung cấp không xung đột với bất kỳ giá trị hiện có nào khi được thêm vào.Thay thế một giá trị trong tập hợp các giá trị hiện có cho một phần tử lặp lại. Trong trường hợp này, bạn chỉ cần xoá một phần tử bằng cách xác định giá trị
gd:fieldsđủ hẹp để tránh xoá các giá trị khác mà bạn muốn giữ lại. Ví dụ: để chỉ xoá quyền kiểm soát truy cập vớiactionlàembed, bạn có thể sử dụnggd:fields='ns:accessControl[@action="embed"]'. Sau đó, bạn cung cấp trường duy nhất mà bạn muốn thay thế bằng trường nội dung của phần tử<entry>:PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='ns:accessControl[@action="embed"]> <ns:accessControl action="embed" permission="allowed" /> </entry>
Xử lý phản hồi cho nội dung cập nhật một phần
Sau khi xử lý yêu cầu cập nhật một phần hợp lệ, API sẽ trả về một mã phản hồi HTTP 200 OK. Theo mặc định, nội dung của phản hồi là mục hoàn chỉnh mà bạn đã cập nhật. Máy chủ cập nhật các giá trị ETag khi xử lý thành công yêu cầu PATCH, giống như với PUT.
Nếu yêu cầu PATCH dẫn đến một trạng thái tài nguyên mới không hợp lệ về mặt cú pháp hoặc ngữ nghĩa, thì máy chủ sẽ trả về một mã trạng thái HTTP HTTP 400 Bad Request hoặc 422 Unprocessable Entity và trạng thái tài nguyên đó sẽ không thay đổi. Ví dụ: Nếu bạn cố gắng xóa một trường bắt buộc và không cung cấp thuộc tính thay thế, máy chủ sẽ trả về lỗi.
Lưu ý: Bạn cần phải hiểu các trường khác nhau có liên quan với nhau như thế nào. Bạn có thể đặt một tài nguyên ở trạng thái không nhất quán bằng cách chỉ cập nhật một phần của các giá trị phụ thuộc lẫn nhau. Ví dụ: bạn có thể cập nhật thời gian bắt đầu thành một giá trị muộn hơn thời gian kết thúc. Mặc dù API sẽ trả về mã lỗi, nhưng bạn nên kiểm thử đầy đủ các loại điều kiện này để đảm bảo tính nhất quán.
Ký hiệu thay thế khi patCH không được hỗ trợ
Nếu tường lửa của bạn không cho phép PATCH, hãy thực hiện yêu cầu HTTP POST và thiết lập tiêu đề ghi đè thành PATCH, như minh hoạ dưới đây:
POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...
Sử dụng phản hồi một phần với cập nhật một phần
Bạn có thể sử dụng phản hồi một phần làm cơ sở cho yêu cầu cập nhật một phần tiếp theo. Nếu bạn thực hiện việc này, hãy chỉ định tham số truy vấn fields bao gồm đường liên kết chỉnh sửa, cũng như @gd:*. Điều này đảm bảo rằng phản hồi một phần bao gồm các thông tin như giá trị thuộc tính ETag và gd:fields, điều này rất quan trọng đối với các yêu cầu tiếp theo.
Sau đây là ví dụ trả về một phần phản hồi mà bạn có thể dùng làm cơ sở để cập nhật một phần trong tương lai:
http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who
Máy chủ phản hồi:
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"E0UKRAREeCp7IWA6WhJT"'
gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
<link href='http://example.com/myFeed/1/1/'/>
<gd:who email='liz@gmail.com'/>
<gd:who email='jo@gmail.com'/>
<gd:who email='jane@gmail.com'/>
</entry>
Giả sử bạn muốn xóa người dùng có email 'jane@gmail.com', thêm người dùng có email 'will@gmail.com' và thay đổi email của người dùng hiện đang được liệt kê là 'jo@gmail.com' thành 'josy@gmail.com'.
Bạn có thể thực hiện những thay đổi này chỉ bằng cách bắt đầu với kết quả của phản hồi trước đó, chỉ sửa đổi các trường khác nhau và gửi mục nhập đã sửa đổi một phần làm nội dung của yêu cầu PATCH. Trong ví dụ này, bạn có thể sửa đổi các yêu cầu sau:
- Xoá
<gd:who email='jane'/>khỏi danh sách các thành phần được cung cấp. - Thêm
<gd:who email='will@gmail.com'/>vào danh sách các phần tử được cung cấp. - Thay thế
<gd:who email='jo@gmail.com'/>với<gd:who email='josy@gmail.com'/>.
Yêu cầu PATCH dựa trên phản hồi một phần rõ ràng được hiển thị bên dưới:
PATCH /myFeed/1/1/
Content-Type: application/xml
<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
gd:etag="FE8LQQJJeSp7IWA6WhVa">
<link href='http://example.com/myFeed/1/1'/>
<gd:who email='liz@gmail.com'/>
<gd:who email='josy@gmail.com'/>
<gd:who email='will@gmail.com'/>
</entry>
Lưu ý: Phương pháp này dựa trên các thuộc tính gd:fields và gd:etag (nếu được hỗ trợ) trong nội dung phản hồi một phần cho mục nhập. Nội dung của mục nhập một phần phải giữ lại tất cả các trường và thuộc tính có trong phản hồi một phần — ngoại trừ những trường mà bạn muốn xóa một cách rõ ràng. Bạn có thể cập nhật bất kỳ trường hiện có nào trong phần nội dung bằng các giá trị mới và bạn có thể thêm bất kỳ trường mới nào bạn muốn thêm.
Xác thực
Khi một khách hàng cố gắng truy cập vào một dịch vụ, dịch vụ đó có thể cần cung cấp thông tin đăng nhập của người dùng cho dịch vụ đó, để chứng minh rằng người dùng có quyền thực hiện hành động được đề cập.
Phương pháp mà một ứng dụng nên sử dụng để xác thực phụ thuộc vào loại ứng dụng:
- Một ứng dụng dành cho máy tính phải sử dụng một hệ thống xác thực dành riêng cho Google có tên là Xác thực tài khoản cho các ứng dụng đã cài đặt (còn gọi là "ClientLogin"). (Ứng dụng khách dựa trên web không được sử dụng hệ thống này.)
- Ứng dụng dựa trên nền tảng web, chẳng hạn như giao diện người dùng của bên thứ ba cho một dịch vụ của Google, phải sử dụng hệ thống xác thực dành riêng cho Google có tên là Proxy xác thực tài khoản cho ứng dụng dựa trên web (còn gọi là "AuthSub").
Trong hệ thống ClientLogin, ứng dụng khách dành cho máy tính sẽ yêu cầu người dùng cung cấp thông tin đăng nhập rồi gửi những thông tin đăng nhập đó đến hệ thống xác thực của Google.
Nếu xác thực thành công, thì hệ thống xác thực sẽ trả về một mã thông báo mà ứng dụng sau đó sử dụng (trong một tiêu đề Uỷ quyền HTTP) khi gửi yêu cầu API dữ liệu.
Nếu xác thực không thành công, máy chủ sẽ trả về mã trạng thái 403 Forbidden, cùng với tiêu đề WWW-Authentication chứa thử thách áp dụng cho quá trình xác thực.
Hệ thống AuthSub hoạt động tương tự như vậy, ngoại trừ việc thay vì yêu cầu người dùng cung cấp thông tin đăng nhập, hệ thống sẽ kết nối người dùng với một dịch vụ của Google yêu cầu thông tin đăng nhập. Sau đó, dịch vụ này sẽ trả về một mã thông báo mà ứng dụng web có thể sử dụng. Ưu điểm của phương pháp này là Google (thay vì giao diện người dùng web) xử lý và lưu trữ an toàn thông tin xác thực của người dùng.
Để biết thông tin chi tiết về các hệ thống xác thực này, hãy xem tài liệu Tổng quan về quy trình xác thực API dữ liệu của Google hoặc Tài khoản Google xác thực.
Trạng thái phiên
Nhiều hoạt động triển khai logic kinh doanh đòi hỏi mức độ gắn bó với phiên — theo dõi trạng thái phiên của người dùng.
Google theo dõi trạng thái phiên theo 2 cách: sử dụng cookie và sử dụng mã thông báo có thể được gửi dưới dạng tham số truy vấn. Cả hai phương pháp đều đạt được hiệu quả như nhau. Khách hàng nên hỗ trợ một trong những phương pháp theo dõi trạng thái phiên này (chỉ một trong hai phương pháp này là đủ). Nếu ứng dụng không hỗ trợ một trong những phương thức này, thì ứng dụng đó vẫn hoạt động với API dữ liệu, nhưng hiệu suất có thể bị ảnh hưởng so với ứng dụng hỗ trợ các phương thức này. Cụ thể là nếu một ứng dụng không hỗ trợ các phương thức này, thì mọi yêu cầu sẽ dẫn đến một lệnh chuyển hướng, do đó mọi yêu cầu (và mọi dữ liệu liên quan) sẽ được gửi đến máy chủ hai lần, ảnh hưởng đến hiệu suất của cả ứng dụng và máy chủ.
Thư viện ứng dụng Google xử lý trạng thái phiên cho bạn, vì vậy nếu sử dụng thư viện của chúng tôi, bạn không cần làm gì để được hỗ trợ trạng thái phiên.
Tài nguyên khác
Bạn có thể thấy các tài liệu bên thứ ba sau đây hữu ích:
- So sánh giữa Atom và RSS từ dễ dàng
- Tổng quan về Atom của IBM
- Tiện ích Dublin Core sang RSS
- Định nghĩa phương thức HTTP 1.1; quy cách cho
GET,POST,PUTvàDELETE - Định nghĩa mã trạng thái HTTP 1.1
- Cách tạo giao thức REST
- Xây dựng dịch vụ web theo cách REST
- Giới thiệu về kỹ thuật XML
- Ví dụ về vùng chứa tên XML
- Phần ETag trong quy cách HTTP