本文件將說明 Google Data API 所使用的通訊協定，包括查詢的外觀和結果的外觀等相關資訊。
如要進一步瞭解 Google Data API，請參閱 Google Data 開發人員指南文件和通訊協定指南。
目標對象
本文旨在協助使用者瞭解 Google Data API 使用的 XML 格式和通訊協定的詳情。
如果您只想編寫使用 Google Data Client API 的程式碼，則無需瞭解這些細節，而可以改用語言專用的用戶端程式庫。
如果您想瞭解通訊協定，請參閱本文。舉例來說，您可以參閱本文件，協助您執行下列任一工作：
- 評估 Google Data 架構
- 使用通訊協定的編碼，但不使用提供的 Google Data 用戶端程式庫
- 以新語言撰寫用戶端程式庫
本文件假設您瞭解 XML、命名空間、聯合發布的動態饋給、HTTP 中的 GET、POST、PUT 和 DELETE 要求，以及 HTTP 的「資源」概念。如要進一步瞭解相關資訊，請參閱本文的其他資源一節。
這份文件不需要任何特定的程式設計語言；您可以使用任何程式設計語言傳送和接收「Google 資料」訊息，以發出 HTTP 要求及剖析 XML 回應。
通訊協定詳細資料
本節將說明 Google Data 文件的格式和查詢語法。
文件格式
Google 資料、Atom 及 RSS 2.0 皆共用相同的基本資料模型：一個容器可用來存放部分全域資料和不限數量的項目。每個通訊協定的格式皆是由基本結構定義所定義，但可使用外命名空間來擴充。
Google Data API 可使用 Atom 聯合發布格式 (適用於讀寫) 或 RSS 格式 (唯讀)。
Atom 是 Google 資料的預設格式。如要透過 RSS 格式要求回應，請使用 /alt=rss/ 參數；詳情請參閱查詢要求。
當您要求 RSS 格式的資料時，Google 資料會以 RSS 格式提供資訊提供 (或其他資源表示法)。如果特定 Google 資料屬性沒有對等的 RSS 屬性，Google 資料就會使用 Atom 屬性，為適當的命名空間加上標籤，藉此表示是 RSS 的延伸。
注意：多數採用 Atom 格式的 Google 資料動態饋給，都會在動態饋給元素中指定 xmlns 屬性，將 Atom 命名空間做為預設命名空間；如需範例說明，請參閱範例一節。因此，本文件中的範例並未明確為 Atom 格式資訊提供中的元素指定 atom:。
下表顯示了架構元素的 Atom 和 RSS 表示法。所有未提及的資料表都會視為純文字 XML，並在這兩種呈現方式中都顯示相同的結果。除非另有註明，否則指定欄中的 XML 元素位於該欄對應的命名空間中。這個摘要使用標準 XPath 標記法：尤其，斜線代表元素階層，@ 符號則代表元素屬性。
下列每個表格都必須標明標示的項目。
下表列出 Google 資料動態饋給的各元素：
| 資訊提供架構項目 | Atom 代表 | RSS 表示法 |
|---|---|---|
| 資訊提供標題 | /feed/title |
/rss/channel/title |
| 動態饋給ID | /feed/id |
/rss/channel/atom:id |
| 資訊提供 HTML 連結 | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
/rss/channel/link |
| 資訊提供說明 | /feed/subtitle |
/rss/channel/description |
| 動態饋給語言 | /feed/@xml:lang |
/rss/channel/language |
| 資訊提供版權 | /feed/rights |
/rss/channel/copyright |
| 資訊提供作者 |
(在某些情況下需要，請參閱 Atom 規格)。 |
/rss/channel/managingEditor |
| 資訊提供上次更新日期 | /feed/updated(RFC 3339 格式) |
/rss/channel/lastBuildDate(RFC 822 格式) |
| 資訊提供類別 | /feed/category/@term |
/rss/channel/category |
| 資訊提供類別配置 | /feed/category/@scheme |
/rss/channel/category/@domain |
| 資訊提供產生器 | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| 資訊提供圖示 | /feed/icon |
/rss/channel/image/url (除非有標誌，否則動態饋給中不會顯示該圖示) |
| 資訊提供標誌 | /feed/logo |
/rss/channel/image/url |
下表說明 Google Data 搜尋結果資訊提供的元素。請注意，Google 資料會在搜尋結果資訊提供中顯示部分 OpenSearch 1.1 回應元素。
| 搜尋結果資訊提供的結構定義項目 | Atom 代表 | RSS/OpenSearch 代表 |
|---|---|---|
| 搜尋結果數量 | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| 搜尋結果開始索引 | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| 每頁搜尋結果數 | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
下表顯示 Google 資料項目的元素：
| 登入結構定義項目 | Atom 代表 | RSS 表示法 |
|---|---|---|
| 項目 ID | /feed/entry/id |
/rss/channel/item/guid |
| 項目版本 ID | 選擇性地嵌入 EditURI 中 (請參閱本文的最佳並行一節)。 | — |
| 項目標題 | /feed/entry/title |
/rss/channel/item/title |
| 項目連結 | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| 報名摘要 |
(在某些情況下需要，請參閱 Atom 規格)。 |
/rss/channel/item/atom:summary |
| 項目內容 |
(如果沒有內容元素，項目中至少須包含一個 |
/rss/channel/item/description |
| 入口作者 |
(在某些情況下需要，請參閱 Atom 規格)。 |
/rss/channel/item/author |
| 項目類別 | /feed/entry/category/@term |
/rss/channel/item/category |
| 項目類別配置 | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| 報名出版日期 | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| 項目更新日期 | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom:updated(RFC 3339) |
查詢
本節說明如何使用查詢系統。
查詢模型設計種類
查詢模型刻意採用簡單的方法。基本原則如下：
- 查詢會以 HTTP URI 表示，而非 HTTP 標頭或酬載的一部分。這個方式的一個優點是可以連結到查詢。
- 述詞的範圍限定為單一項目。因此，您無法傳送關聯性最高的查詢，例如「尋找今天至少寄給我 10 封電子郵件的使用者」。
- 查詢可以述說的語系非常有限；大部分查詢都只有全文搜尋查詢。
- 結果排序取決於實作。
- 通訊協定可自然擴充。如果您想在服務中顯示其他述詞或排序，只要導入新的參數即可。
查詢要求
用戶端會發出 HTTP GET 要求來查詢 Google Data 服務。查詢 URI 包含資源的 URI (在 Atom 中稱為 FeedURI)，後面接著查詢參數。大多數的查詢參數都以傳統的 ?name=value[&...] 網址參數表示。類別參數的處理方式不同，請見下文。
舉例來說，如果 FeedURI 為 http://www.example.com/feeds/jo，則您可以使用以下 URI 傳送查詢：
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Google 資料服務支援 HTTP 條件式 GET。系統會根據傳回的動態饋給或項目中的 <atom:updated> 元素值，設定 Last-Modified 回應標頭。用戶端可以將此值做為 If-Modified-Before 要求標頭的值傳回，避免在內容沒有變更的情況下再次擷取內容。如果內容在 If-Modified-Since 時間之後沒有變更，則 Google Data 服務會傳回 304 (未修改) HTTP 回應。
Google Data 服務必須支援類別查詢和 alt 查詢，其他參數也可以支援。傳送指定服務無法解讀的標準參數會導致 403 Forbidden 回應。傳送不支援的非標準參數會導致 400 Bad Request 回應。如要進一步瞭解其他狀態碼，請參閱本文的 HTTP 狀態碼一節。
下表匯總了標準查詢參數。所有參數值都必須經過網址編碼。
| 參數 | 意義 | Notes |
|---|---|---|
q |
全文查詢字串 |
|
/-/category |
類別篩選器 |
|
category |
類別篩選器 |
|
author |
報名作者 |
|
alt |
替代表示法類型 | |
updated-maxupdated-min |
項目更新日期的 Bounds |
|
published-maxpublished-min |
項目發布日期的 Bounds |
|
start-index |
首次擷取結果的索引 (以 1 為基準) |
|
max-results |
要擷取的結果數上限 | 任何預設 max-results 值 (以限制預設動態饋給大小) 的服務，如果您要接收整個動態饋給，請指定非常大的數字。 |
| 項目 ID | 要擷取的特定項目 ID |
|
關於類別查詢
我們決定為類別查詢指定稍微不尋常的格式。而不是像以下查詢：
http://example.com/jo?category=Fritz&category=2006
我們使用：
http://example.com/jo/-/Fritz/2006
這個方法可在不使用查詢參數的情況下識別資源，進而產生更簡潔的 URI。我們認為這是類別時最常使用的查詢類型，因此選擇這種做法。
這種做法的缺點是，您必須在類別查詢中使用 /-/，以便 Google Data 服務區分類別查詢和其他資源 URI (例如 http://example.com/jo/MyPost/comments)。
查詢回應
查詢會傳回 Atom 資訊提供、Atom 項目或 RSS 資訊提供，視要求參數而定。
查詢結果會在 <feed> 元素或 <channel> 元素下方直接列出下列 OpenSearch 元素 (視結果是 Atom 還是 RSS 而定)：
openSearch:totalResults- 該查詢的搜尋結果總數 (不一定會出現在結果動態饋給中)。
openSearch:startIndex- 第一個結果的索引型索引。
openSearch:itemsPerPage- 單一頁面顯示的項目數量上限。這樣一來，客戶就能為後續的網頁產生直接連結。不過，如果您有可能使用該數字，請參閱查詢要求一節中關於
start-index的注意事項。
Atom 回應資訊提供和項目也可能包含以下 Atom 和 Google 資料元素，以及 Atom 規格中列出的其他元素：
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- 指定可擷取完整 Atom 資訊提供的 URI。
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- 指定 Atom 資訊提供的 PostURI (可以發布新項目)。
<link rel="self" type="..." href="..."/>- 包含這項資源的 URI。
type屬性的值取決於要求的格式。如果這段期間內的資料沒有任何變動，將其他 GET 傳送至這個 URI 會傳回相同的回應。 <link rel="previous" type="application/atom+xml" href="..."/>- 指定這個查詢結果集先前區塊的 URI (如有分區塊)。
<link rel="next" type="application/atom+xml" href="..."/>- 為這個查詢結果集的下一個區塊指定 URI，前提是區塊已分塊。
<link rel="edit" type="application/atom+xml" href="..."/>- 指定 Atom 項目的 EditURI (您傳送更新項目的位置)。
以下是回應搜尋查詢的範例回應主體：
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<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>
<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>
<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>
如果要求的動態饋給採用 Atom 格式，且未指定查詢參數，且結果未包含所有項目，則系統會將下列元素插入頂層動態饋給：<link rel="next" type="application/atom+xml" href="..."/>。指向的動態饋給包含下一組項目。後續的組合則包含對應的 <link rel="previous" type="application/atom+xml" href="..."/> 元素。客戶完成所有「後續」連結之後，就能從動態饋給擷取所有項目。
HTTP 狀態碼
下表說明各種 HTTP 狀態碼在 Google Data 服務內容中的意義。
| 程式碼 | 說明 |
|---|---|
| 200 成功 | 未發生錯誤。 |
| 201 建立 | 已成功建立資源。 |
| 304 未修改 | 資源自要求的 If-Modified-Since 標頭中指定的時間後，尚未變更。 |
| 400 錯誤要求 | 要求 URI 或標頭無效，或不支援的非標準參數。 |
| 401 未獲授權 | 需要授權。 |
| 403 禁止 | 不支援的標準參數，或是驗證或授權失敗。 |
| 404 未成功 | 找不到資源 (例如資訊提供或項目)。 |
| 409 衝突 | 指定的版本號碼與資源最新的版本號碼不符。 |
| 500 內部伺服器錯誤 | 發生內部錯誤，這是所有無法辨識的錯誤所使用的預設代碼。 |
樂觀並行 (版本管理)
有時請務必確保多位客戶不會不小心覆寫彼此的變更。最簡單的方法就是確保用戶端修改的項目目前版本與用戶端根據其版本修改的版本相同。如果第二個用戶端在第一個用戶端之前進行更新，則第一個用戶端的更新不再是依據用戶端的最新版本來修改，因此會拒絕第一個用戶端的更新。
在支援版本管理功能的 Google 資料動態饋給中，我們在各項目的 EditURI 中附加一個版本 ID，可實現這些語意。請注意，只有編輯 URI 會受到影響，不會影響項目 ID。在這個架構中，每次更新都會變更該項目的 EditURI，確保根據後續版本的更新保證更新失敗。當然，刪除作業與這項功能相關更新相同，如果您傳送的舊版本號碼與舊版不同，則刪除作業會失敗。
並非所有 Google 資料動態饋給都支援樂觀並行。在支援此功能的動態饋給中，如果伺服器在 PUT 或 DELETE 中偵測到版本衝突，伺服器會傳回 409 Conflict。回應的主體會包含項目目前的狀態 (Atom 項目文件)。建議用戶端根據 409 回應中的 EditURI，解決衝突並重新提交要求。
動力與設計注意事項
這個做法可以達到最佳的並行，不需要實作新的版本 ID 標記，就能讓 Google 資料與非 Google Data Atom 端點相容。
與其指定版本 ID，我們可以選擇查看每個項目 (/atom:entry/atom:updated) 的更新時間戳記，但使用更新時間戳記有兩點問題：
- 這項功能僅適用於更新，不適用於刪除作業。
- 這麼做會強制應用程式使用日期/時間值做為版本 ID，這使得許多現有資料儲存庫以外的 Google 資料都變得越來越難。
驗證
當用戶端嘗試存取服務時，可能需要將憑證提供給服務，以證明使用者有權執行相關動作。
用戶端應採用哪種方法，取決於用戶端類型：
- 電腦版應用程式應使用名為帳戶驗證的 Google 專屬驗證系統 (又稱為「ClientLogin」)。(網頁式用戶端不應使用此系統)。
- 網路用戶端 (例如 Google Data 服務的第三方前端) 應使用名為帳戶式應用程式的帳戶驗證 Proxy (也稱為「AuthSub」) 的 Google 專用驗證系統。
在 ClientLogin 系統中，桌面用戶端會要求使用者提供憑證，然後將這些憑證傳送到 Google 驗證系統。
如果驗證成功，驗證系統會傳回用戶端在傳送「Google 資料」要求後所使用的憑證 (在 HTTP 授權標頭中)。
如果驗證失敗，伺服器會傳回 403 Forbidden 狀態碼和 WWW-Authenticate 標頭，其中包含適用於驗證的驗證問題。
AuthSub 系統的運作方式類似，不過使用者不會要求他們提供憑證，而是將使用者導向要求憑證的 Google 服務。接著，服務會傳回一個憑證，供網路應用程式使用；這種方法的優點在於 Google (而非網站前端) 可以安全地處理及儲存使用者的憑證。
如要進一步瞭解這些驗證系統，請參閱 Google 資料驗證總覽或 Google 帳戶驗證說明文件。
工作階段狀態
許多商業邏輯實作都需要工作階段黏著度，追蹤使用者工作階段的狀態。
Google 追蹤工作階段狀態的方法有兩種：使用 Cookie，以及使用可做為查詢參數傳送的憑證。這兩種方法的效果相同。我們建議客戶支援上述其中一種工作階段狀態追蹤方式 (其中一種)。如果客戶不支援上述任一方法，該用戶端仍可使用 Google Data 服務，不過與支援這些方法的用戶端相比，效能可能較不理想。具體來說，如果用戶端不支援這些方法，則每個要求都會產生重新導向，因此每個要求 (以及任何相關聯的資料) 都會傳送到伺服器兩次，進而影響用戶端和伺服器的效能。
Google 用戶端程式庫會為您處理工作階段狀態，因此如果您使用了我們的程式庫，則無須執行任何動作，即可取得工作階段狀態支援。
其他資源
以下第三方文件或許能派上用場：
- Atoms 與 RSS 的比較
- IBM 的 Atom 總覽
- Dublin Core 擴充功能 (RSS)
- HTTP 1.1 方法定義；
GET、POST、PUT和DELETE的規格 - HTTP 1.1 狀態碼定義
- 如何建立 REST 通訊協定
- 以 REST 方式打造網路服務
- XML 技術簡介
- XML 命名空間範例