警告：本頁面說明 Google 的舊版 API (即 Google Data API)；該 API 只與 Google Data API 目錄中列出的 API 相關，其中許多 API 已由新版 API 取代。如需特定新的 API 的相關資訊，請參閱新 API 的說明文件。如要瞭解如何使用新版 API 授權要求，請參閱 Google 帳戶驗證與授權。
本文件說明許多 Google API 所使用的 Google Data 通訊協定，包括查詢的樣貌和結果等。
如要進一步瞭解 Google 資料通訊協定，請參閱《開發人員指南》總覽網頁，以及通訊協定基本概念文件。
目標對象
本文件旨在協助有意瞭解採用 Google Data Protocol 的 API 使用的 XML 格式和通訊協定詳細資訊。
如果您只想編寫使用其中一種 API 的程式碼，則不必瞭解這些細節，而可以改用語言專用的用戶端程式庫。
如果您想瞭解通訊協定，請參閱本文。舉例來說，您可以參閱本文件，協助您執行下列任一工作：
- 評估 Google Data Protocol 架構
- 使用通訊協定的編碼，而無需使用提供的用戶端程式庫
- 以新語言撰寫用戶端程式庫
本文件假設您瞭解 XML、命名空間、聯合發布的動態饋給、HTTP 中的 GET、POST、PUT 和 DELETE 要求，以及 HTTP 的「資源」概念。如要進一步瞭解相關資訊，請參閱本文的其他資源一節。
本文件不需任何特定的程式設計語言，您可以使用任何程式設計語言來傳送和接收「Google Data 通訊協定」訊息，以發出 HTTP 要求及剖析 XML 回應。
通訊協定詳細資料
本節將說明 Google Data Protocol 文件的格式和查詢語法。
文件格式
Google Data 通訊協定和 Atom 共用相同的基本資料模型：一個容器同時含有部分全域資料和不限數量的項目。每個通訊協定的格式皆是由基本結構定義所定義，但可使用外命名空間來擴充。
Atom 是 Google 資料通訊協定的預設格式，如要請求其他格式的回應，請使用 alt 查詢參數；詳情請參閱查詢要求。
注意：大部分的 Google 資料通訊協定動態饋給採用 Atom 格式，會透過在動態饋給元素中指定 xmlns 屬性，將 Atom 命名空間做為預設命名空間，如通訊協定基本資訊中的範例所示。因此，本文件中的範例並未明確為 Atom 格式資訊提供中的元素指定 atom:。
下表顯示了結構定義元素的 Atom 表示法。凡是未提及的資料表，都會視為純 XML。除非另有註明，否則指定資料欄中 XML 元素位於 Atom 命名空間。
注意：這個摘要使用標準 XPath 標記法：尤其是斜線代表元素階層，@ 符號則代表元素屬性。
下列每個表格都必須標明標示的項目。
下表為「Google Data 通訊協定」資訊提供的元素：
| 資訊提供架構項目 | Atom 代表 |
|---|---|
| 資訊提供標題 | /feed/title |
| 動態饋給ID | /feed/id |
| 資訊提供 HTML 連結 | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
| 資訊提供說明 | /feed/subtitle |
| 動態饋給語言 | /feed/@xml:lang |
| 資訊提供版權 | /feed/rights |
| 資訊提供作者 |
(在某些情況下需要，請參閱 Atom 規格)。 |
| 資訊提供上次更新日期 | /feed/updated(RFC 3339 格式) |
| 資訊提供類別 | /feed/category/@term |
| 資訊提供類別配置 | /feed/category/@scheme |
| 資訊提供產生器 | /feed/generator/feed/generator/@uri |
| 資訊提供圖示 | /feed/icon |
| 資訊提供標誌 | /feed/logo |
下表為「Google Data 通訊協定」搜尋結果資訊提供的元素，請注意，通訊協定會在搜尋結果資訊提供中公開部分 OpenSearch 1.1 Response 元素。
| 搜尋結果資訊提供的結構定義項目 | Atom 代表 |
|---|---|
| 搜尋結果數量 | /feed/openSearch:totalResults |
| 搜尋結果開始索引 | /feed/openSearch:startIndex |
| 每頁搜尋結果數 | /feed/openSearch:itemsPerPage |
下表為「Google Data 通訊協定」項目的元素：
| 登入結構定義項目 | Atom 代表 |
|---|---|
| 項目 ID | /feed/entry/id |
| 項目標題 | /feed/entry/title |
| 項目連結 | /feed/entry/link |
| 報名摘要 |
(在某些情況下需要，請參閱 Atom 規格)。 |
| 項目內容 |
(如果沒有內容元素，項目中至少須包含一個 |
| 入口作者 |
(在某些情況下需要，請參閱 Atom 規格)。 |
| 項目類別 | /feed/entry/category/@term |
| 項目類別配置 | /feed/entry/category/@scheme |
| 報名出版日期 | /feed/entry/published(RFC 3339) |
| 項目更新日期 | /feed/entry/updated(RFC 3339) |
查詢
本節說明如何使用查詢系統。
查詢模型設計種類
查詢模型刻意採用簡單的方法。基本原則如下：
- 查詢會以 HTTP URI 表示，而非 HTTP 標頭或酬載的一部分。這個方式的一個優點是可以連結到查詢。
- 述詞的範圍限定為單一項目。因此，您無法傳送關聯性最高的查詢，例如「尋找今天至少寄給我 10 封電子郵件的使用者」。
- 查詢可以述說的語系非常有限；大部分查詢都只有全文搜尋查詢。
- 結果排序取決於實作。
- 通訊協定可自然擴充。如果您想在服務中顯示其他述詞或排序，只要導入新的參數即可。
查詢要求
用戶端會發出 HTTP GET 要求來查詢 Google 服務。查詢 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。實作通訊協定的 API 會根據所傳回資訊提供或項目中的 <atom:updated> 元素值，設定 Last-Modified 回應標頭。用戶端可以將此值做為 If-Modified-Before 要求標頭的值傳回，避免在內容沒有變更的情況下再次擷取內容。如果內容在 If-Modified-Since 時間之後仍未變更，則服務會傳回 304 (未修改) HTTP 回應。
導入 Google Data 通訊協定的 API 必須支援 alt 查詢；您可以選用其他參數。傳送指定服務無法解讀的標準參數會導致 403 Forbidden 回應。傳送不支援的非標準參數會導致 400 Bad Request 回應。如要進一步瞭解其他狀態碼，請參閱本文的 HTTP 狀態碼一節。
下表匯總了標準查詢參數。所有參數值都必須經過網址編碼。
| 參數 | 意義 | Notes |
|---|---|---|
alt |
替代表示法類型 |
|
author |
報名作者 |
|
category |
類別查詢篩選器 |
|
/-/category |
類別查詢篩選器 |
|
| 項目 ID | 要擷取的特定項目 ID |
|
fields |
回應篩選器 |
|
max-results |
要擷取的結果數上限 | 任何預設 max-results 值 (以限制預設動態饋給大小) 的服務，如果您要接收整個動態饋給，請指定非常大的數字。 |
prettyprint |
傳回包含地址和斷行的 XML 回應 |
|
published-maxpublished-min |
項目發布日期的 Bounds |
|
q |
全文查詢字串 |
|
start-index |
首次擷取結果的索引 (以 1 為基準) |
|
strict |
嚴格查詢參數檢查 |
|
updated-maxupdated-min |
項目更新日期的 Bounds |
|
關於類別查詢
我們決定為類別查詢提供稍微不尋常的格式。不需要使用類似以下的查詢：
http://example.com/jo?category=Fritz&category=2006
我們可以使用：
http://example.com/jo/-/Fritz/2006
這個方法可在不使用查詢參數的情況下識別資源，進而產生更簡潔的 URI。我們認為這是類別常用的查詢，因此，我們選擇以類別做為這種方式。
這種做法的缺點是，您必須在這類類別查詢中使用 /-/，讓服務能夠區分類別查詢和其他資源 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 和 Data API 元素 (以及 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="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>
如果要求的動態饋給採用 Atom 格式，且未指定查詢參數，且結果未包含所有項目，則系統會將下列元素插入頂層動態饋給：<link rel="next" type="application/atom+xml" href="..."/>。指向的動態饋給包含下一組項目。後續的組合則包含對應的 <link rel="previous" type="application/atom+xml" href="..."/> 元素。客戶完成所有「後續」連結之後，就能從動態饋給擷取所有項目。
HTTP 狀態碼
下表說明各種 HTTP 狀態碼在 Data API 的情境中的意義。
| 程式碼 | 說明 |
|---|---|
| 200 成功 | 未發生錯誤。 |
| 201 建立 | 已成功建立資源。 |
| 304 未修改 | 資源自要求的 If-Modified-Since 標頭中指定的時間後，尚未變更。 |
| 400 錯誤要求 | 要求 URI 或標頭無效，或不支援的非標準參數。 |
| 401 未獲授權 | 需要授權。 |
| 403 禁止 | 不支援的標準參數，或是驗證或授權失敗。 |
| 404 未成功 | 找不到資源 (例如資訊提供或項目)。 |
| 409 衝突 | 指定的版本號碼與資源最新的版本號碼不符。 |
| 410 消失 | 您要求的變更記錄已不在伺服器上。詳情請參閱服務專屬說明文件。 |
| 500 內部伺服器錯誤 | 發生內部錯誤，這是所有不明的伺服器錯誤所使用的預設代碼。 |
資源版本管理 (ETag)
有時，您需要能夠參照特定項目的特定版本。
在以下兩種情況中，這相當重要：
- 執行「條件式擷取」時，用戶端會要求項目，且伺服器只有在用戶端上次要求之後變更時，才會傳送該項目。
- 確保多位用戶端不會意外覆寫彼此的變更。如果用戶端已為該項目指定舊的版本識別碼，Data API 就會進行更新並刪除作業失敗。
Google Data API 會使用 ETags (HTTP 的標準部分) 處理這兩種情況。
ETag 這個 ID 可指定特定項目的特定版本。伺服器會將 ETag 附加至傳送給用戶端的項目和動態饋給元素。當項目或資訊提供有所變更時，其 ETag 也會跟著改變。
Google Data API 在以下兩個位置提供 ETag：ETag HTTP 標頭以及 <feed> 和 <entry> 元素的 gd:etag 屬性。
在 Google Data API 中，ETag 通常是由字母和數字組成的字串，有時包含連字號和半形句號；該字串通常用引號括住。(引號是 ETag 的一部分)。例如，以下是來自 Data API 項目的 ETag："S0wCTlpIIip7ImA0X0QI"。
ETag 有兩種類型：高強度與弱。強的 ETag 可以識別特定項目的特定版本，且有助於避免其他用戶端的變更。在 Google Data API 中，微弱的 ETag 只會用於條件式擷取。微弱的 ETag 一律會以 W/ 開頭。例如：W/"D08FQn8-eil7ImA9WxZbFEw."
並非所有 Google Data API 都支援嚴格的 ETag。以強而有力的 ETag 只會用於項目；資訊提供的 ETag 一律為低強度。
以下是從支援強大 ETag 的服務擷取的資訊提供 (包括部分 HTTP 標頭) 的範例：
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>
支援 Data API 第 2 版的用戶端程式庫可以為您公開處理 ETag。以下資訊適用於未使用用戶端程式庫的客戶，以及想要在通訊協定層級處理版本化的讀者。
注意：如要進一步瞭解 Data API 1.0 版使用的資源版本管理系統，請參閱 1.0 參考指南。
條件式擷取
如果您想擷取先前擷取的項目，可以指示伺服器只擷取自上次擷取之後的變更內容，藉此提升效率。
若要執行此類條件擷取作業，請傳送包含 HTTP If-None-Match 標頭的 HTTP GET 要求。在標頭中指定該項目的 ETag。
以下是 If-None-Match 標頭的範例：
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
伺服器收到這項要求時，會檢查您要求的項目是否與您指定的 ETag 相同。如果 ETag 相符，則項目維持不變，伺服器會傳回 HTTP 304 Not Modified 狀態碼。
如果 ETag 不匹配，則該項目自您上次要求後已經過修改，伺服器則會傳回該項目。
正在更新項目
想要避免覆寫其他用戶端的變更，最簡單的方法就是讓伺服器確保在用戶端傳送更新項目時，用戶端開頭的項目版本與伺服器儲存的目前版本相同。如果第二位用戶端在客戶進行更新之前進行更新，您的用戶端更新就會遭到拒絕，因為您的客戶不再根據最新版本做出修改。
當用戶端從支援強大 ETag 的服務擷取資料時，每個項目都有一個 ETag，作為該版本版本的獨立版本識別碼。
注意：只有使用功能強大的 ETag 才能更新使用 ETag。針對提供低 ETag 的服務，不論是否已有其他使用者更新其內容，所有更新都會成功；最新更新一律會覆寫任何其他先前的更新。因此，請勿在更新或刪除 ETag 時傳送微弱的 ETag；如果發生錯誤，系統會顯示錯誤訊息。
因此，當用戶端傳送更新至強式 ETag 服務時，需要指定要更新的項目版本。設定的方法有兩種：
- 使用
If-MatchHTTP 標頭。 - 在
<atom:entry>元素中使用gd:etag屬性。
我們建議盡量使用 If-Match 方法。
如要使用 If-Match 更新項目，請先取得您要更新的項目。視需要變更項目，然後建立包含修改項目的新 PUT 要求。(如要進一步瞭解要使用的網址，請參閱服務專用說明文件)。
在傳送 PUT 之前，請先新增 HTTP If-Match 標頭，其中包含原始項目中的 ETag：
If-Match: "S0wCTlpIIip7ImA0X0QI"
然後傳送 PUT 要求。
如果更新成功，伺服器會傳回 HTTP 200 OK 狀態碼和更新項目的副本。
如果指定的 ETag 與項目中的目前 ETag 不符 (這表示項目自您上次擷取後，已變更項目在伺服器上經過變更)，更新失敗，則伺服器會傳回 HTTP 412 Precondition Failed 狀態碼。
假使您無法輕易寫入 HTTP 標頭，或因其他原因而避免使用 If-Match 標頭，請改用 gd:etag 屬性。
如果您未傳送 If-Match 標頭，伺服器會使用更新項目的 gd:etag 屬性值做為隱含的 If-Match 值。
如要覆寫版本管理系統並更新項目，無論其他人在您擷取作業之後是否已更新，請使用 If-Match: * 而非在標頭中指定 ETag。
如要瞭解哪些服務支援嚴格的 ETag，請參閱遷移指南。
刪除項目
刪除使用強大 ETag 的項目與更新項目非常相似。
如要刪除含有大量 ETag 的項目，請先擷取要刪除的項目，然後將 DELETE 要求傳送至該項目的編輯網址。
如要確保不會刪除已擷取的另一個用戶端所變更的項目，則請納入包含原始項目 ETag 值的 HTTP If-Match 標頭。
如果您要覆寫版本編號系統，並刪除其他人的更新項目 (無論您是否已自行更新)，則請使用 If-Match: *，而不要在標頭中指定 ETag。
如果項目沒有強大的 ETag，則 DELETE 要求一律成功。
部分回應 (實驗功能)
根據預設，伺服器會在處理要求後，傳回目標資源的完整表示法。部分回應可讓您只要求感興趣的元素或屬性，而非完整的資源表示法。這可讓您的用戶端應用程式避免傳輸、剖析及儲存不需要的欄位，以便更有效率地使用網路、CPU 和記憶體資源。
如要確認您目前使用的產品是否有部分回應，請參閱其 API 說明文件。
如要提出部分回應，請使用 fields 查詢參數來指定您要傳回的元素或屬性。 範例如下：
http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))
伺服器的回應中只包含資訊提供的連結和進入元素，項目元素只含有 ETag、ID、已更新和編輯連結資訊。以下各節將介紹 fields 查詢參數的語法。如要進一步瞭解回應，請參閱處理部分回應。
注意：您可以使用 fields 查詢參數搭配任何傳回資料的要求，除了 GET 以外，這也包括 POST 和 PUT (以及用於進行部分更新的 PATCH)。不過，fields 查詢參數只會影響回應資料，不會影響您提供的資料，也不會影響更新或建立哪些欄位。
Fields 參數語法摘要
fields 查詢參數值的格式是以 XPath 語法為基礎，但僅支援部分有效的 XPath 運算式。支援的語法簡述如下，其他範例如下節所示。
- 使用逗號分隔的清單選取多個欄位。
- 使用
a/b來選取元素b內之巢狀元素a；使用a/b/c來選取位於b中的巢狀元素c。 - 使用
'@'前置字元識別具有指定名稱的屬性；省略'@'前置字元即可參照元素。 - 在您要限制的元素後方加上括號「
[ ]」，藉此套用欄位條件來選取符合特定條件的元素。舉例來說，
fields=entry[author/name='Elizabeth']只會傳回作者為伊莉莎白的作者項目。 - 如要指定只要求特定屬性或子元素，請在欄位指定元素後方加上括號「
( )」。舉例來說，
fields=entry(id,author/email)只會傳回每個資訊提供項目編號以及作者的電子郵件地址。 - 您可以使用雙引號或單引號
來限製字串。
如要逸出雙引號或單引號，請重複引號。例如，"""Hello,"" he said"會產生字串"Hello," he said，而'''Hello,'' he said'會產生字串'Hello,' he said。 - 您可以在欄位選擇中使用萬用字元。
例如，
entry/gd:*會選取gd命名空間中的所有項目元素，entry/@gd:*則會選取同一個命名空間中的子元素屬性。
fields 查詢參數可做為輸出篩選器。也就是說，系統只會在處理其餘的查詢後，才計算部分回應。舉例來說，如果您同時指定了 max-results 查詢參數，藉此指出您希望每個網頁達到 20 筆結果，系統就會產生前 20 筆結果，並從中得到部分回應。如果 fields 規格與查詢選取的前 20 個項目不符，系統會傳回空白的動態饋給；您「不會」傳回前 20 個相符的項目。
注意：請勿嘗試使用欄位條件做為查詢選取器。也就是說，請勿嘗試擷取完整的資訊提供，並套用欄位條件來過濾掉數量龐大的資料集。請盡可能使用其他查詢參數，例如 start-index 和 max-results，以將每個查詢結果減少到方便管理的大小。否則，如果使用不當回應，可能會因為不當使用而導致嚴重效能降低，超乎此舉。
設定欄位值參數值的格式
下列指南說明如何建構 fields 查詢參數值。每項指南都含有範例，並說明參數值對回應的影響。
附註：和所有查詢參數值一樣，fields 參數值也必須使用網址編碼。為了提高可讀性，下方範例省略了編碼。
- 找出您要傳回的欄位，或「選取欄位」。
fields查詢參數值是以逗號分隔的元素或屬性清單 (統稱為「欄位」)，而每個欄位都是依據資源表示法的根元素來指定。因此，擷取動態饋給時，系統會針對<feed>元素指定欄位；如果您要擷取單一項目，則會根據<entry>元素指定欄位。如果您選取的元素是動態饋給中的重複元素 (或屬於其一部分)，則服務會傳回該元素的所有例項。
以下提供幾個動態饋給層級範例：
範例 效果 entry傳回這些項目的所有 <entry>元素和所有子元素，但不傳回<feed>的其他任何子元素。id,entry傳回動態饋給 <id>和所有<entry>元素。entry/title傳回所有資訊提供項目的 <title>元素。
每當傳回巢狀元素時，回應會包含任何父項元素的封閉標記。除非有使用者明確選取，否則父項標記不會包含任何其他子元素或屬性。entry/author/uri為所有動態饋給項目只傳回 <author>元素的<uri>子元素。entry/*:rating在所有動態饋給項目中，只針對命名空間傳回本機名稱為 rating的子元素。
以下列舉幾個入門級的例子：
範例 效果 author傳回目標項目的 <author>子元素。@gd:etag傳回目標項目的 etag屬性。author/uri傳回目標項目的 <author>元素<uri>子元素。media:group/media:*傳回目標項目 media命名空間中<media:group>的所有子欄位。- 將回應限制於符合特定條件的所選欄位，或是使用欄位條件。
- 根據預設，如果要求指定某個元素超過一次，部分回應會包含該元素的所有例項。不過，您也可以指定在回應中只納入具有特定屬性值的元素，或使用「
[ ]」語法來滿足其他條件的元素，如以下範例所示。詳情請參閱欄位條件語法一節。範例 效果 entry[link/@rel='edit']傳回任何包含 <link>元素且rel屬性值為'edit'的資訊提供項目。entry/title[text()='Today']如果動態饋給項目有 'Today'元素，則會傳回<title>。entry/author[name='Jo']如果動態饋給項目中含有內含內容 'Jo'的<name>子元素，則傳回動態饋給項目中發生的<author>元素。author[name='Jo']如果目標項目的 <name>子元素包含'Jo'內容，則傳回目標項目中的<author>元素。 - 只要求所選元素的某些部分，或使用欄位子選取項目。
- 根據預設，如果您的要求指定特定元素，則服務會傳回整個元素。您可以指定回應只納入所選元素中的某些子元素。如要這麼做，請使用「
( )」子選取語法，如下方範例所示。範例 效果 entry/author(uri)只傳回資訊提供項目中作者的 <uri>子元素。entry/author[name='Jo'](uri)只針對作者名稱為 'Jo'的項目傳回<author>的<uri>子元素。entry(link(@rel,@href))只傳回動態饋給項目中每個 <link>元素的rel和href屬性值。entry(title,link[@rel='edit'])針對每個動態饋給項目，只傳回包含編輯 rel屬性的<title>和<link>元素。entry(title,author(uri)為每個動態饋給項目傳回 <title>元素和作者<uri>元素。
進一步瞭解欄位條件語法
您可以在欄位或子欄位中使用欄位條件。所選欄位的條件必須設為 True，才會列入結果。如果沒有欄位條件，系統就會納入所選類型的所有欄位。
所選欄位的文字值會用於比較。在這種情況下，如果欄位是元素，文字值就是其內容；如果欄位是屬性，文字值就是屬性值。如果該欄位沒有文字值，比較就會失敗，且該欄位也不會納入結果中。
下表列出支援欄位條件的 XPath 運算子，並提供部分範例。
| 運算子 | 語法 | 範例 |
|---|---|---|
| 字串比較 |
|
|
| 邏輯比較 | and |
|
| 數值比較 | = 或 eq!= 或 ne> 或 gt>= 或 ge< 或 lt<= 或 le
|
|
| 日期比較 | 請使用數字比較運算子，如範例所示。 | 如要比較日期或日期/時間，您可以將元素、屬性或字串文字投放到
|
| 存在感 | 請使用範例所示的元素或屬性名稱。 |
|
| 布林 | true()false()
|
測試時，布林值可以使用於強制將欄位條件設為「是」或「否」。
|
處理部分回應
支援部分回應的伺服器處理包含 fields 查詢參數的有效要求之後，系統會傳回 HTTP 200 OK 狀態碼和要求的屬性或元素。如果 fields 查詢參數發生錯誤或無效，伺服器會傳回 HTTP 400 Bad Request 狀態碼。
回應的根元素應為 <feed> 或 <entry>，視目標 URI 而定。根元素的內容只會包含該資訊提供或輸入項目所選取的欄位，以及任何父項元素的封閉標記。
要求 fields 查詢參數的值可採用下列兩種方式回呼：
- 根元素具有
gd:fields屬性，用於顯示要求中指定的fields查詢參數。 - 如果目標 URI 是動態饋給，每個可編輯項目都有
gd:fields屬性，用於顯示適用範圍的fields選項部分。
注意：如要在部分回應中查看這些 gd:fields 屬性值，就必須將這些值加入 fields 查詢參數規格中。您可以使用 @gd:fields 或更通用的 @gd:* (包括 ETag 資訊) 來明確執行這項作業。
以下查詢範例會要求伺服器傳回只包含 gd 命名空間屬性的文件 (動態饋給和項目層級)，以及每個資訊提供項目的資訊提供 ID、標題和編輯連結：
http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])
伺服器會傳回下列部分回應，以及 200 Successful HTTP 狀態碼：
<?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>
如果所選欄位不相符，服務仍會傳回 200 Successful HTTP 狀態碼，但部分回應是空白的動態饋給：
<?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>
部分更新 (實驗功能)
如果 Google 產品支援部分回應和可編輯資源，您還可以使用部分更新功能。使用部分更新時，您只需傳送想要更新的欄位，而不是傳送完整資源表示法的修改版本。這樣可以讓用戶端應用程式在更新時更有效率，並使用部分回應擷取資料。
然而，進行部分更新時，您必須使用 PATCH 要求，而不是使用 PUT。PATCH 的語意相當強大，能讓您透過單一要求，新增、取代及刪除特定項目的特定欄位。
如要確認您目前使用的產品是否有部分更新，請參閱產品專屬的說明文件。
提交部分更新要求
如要提交部分更新要求，請傳送 HTTP PATCH 要求至您平常使用 PUT 來更新資源的網址，PATCH 要求的主體是部分 <entry> 元素，用於指定要新增或修改的欄位。該項目的 gd:fields 屬性表示要刪除的欄位。
伺服器會依特定順序處理 PATCH 要求：
- 系統會先從資源表示法中移除
gd:fields屬性指定的欄位。gd:fields屬性的語法與要求部分回應時使用的fields查詢參數相同。詳情請參閱支援的語法。 - 然後合併至要求資源主體中提供的資料。
如要進一步瞭解資料合併的方式，請參閱下方的新增或更新欄位。
注意：由於 PATCH 要求的主體通常不符合 Atom 聯合發布格式，因此您在 PATCH 要求中使用的 Content-Type 為 application/xml。
以下是部分更新要求的範例：
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>
這個 PATCH 要求會對儲存在目標 URI 項目伺服器上的伺服器資源進行下列變更：
- 移除
<description>元素。 - 更新
<title>元素。
部分更新要求的語意
以下操作說明說明如何設定 PATCH 要求，以刪除、新增或更新項目內的特定欄位。單一 PATCH 要求可執行任何這些作業的組合。
刪除欄位。使用
<entry>元素的gd:fields屬性，找出您想要從資源中刪除的任何欄位。下列要求範例會刪除與項目相關聯的標題和摘要。不過，要求不會新增或更新這個項目的其他任何資料。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'/>新增或更新欄位。使用
<entry>元素的主體，指定要在資源中新增或更新的資料。刪除任何資料後，系統會根據下列規則，將這些欄位合併為資源的現有資料：系統會新增尚未存在的欄位。如果資源資料尚未指定欄位的值，則該欄位會新增至現有資料。例如，如果某個項目沒有標題，且您的
PATCH要求包含<title>元素，則系統會將新標題新增至該項目。已經存在的欄位會遭到取代或附加。合併資源中已指定的欄位的具體行為，取決於欄位的特性：
系統會取代非重複的欄位。如果資源資料已指定非重複元素的值，則您在
PATCH要求中指定的值會取代該元素的現有值。例如，在以下範例中，新標題會取代現有標題。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>以下提供較為複雜的範例。在這個例子中，假設該項目只能有一位作者，而且目標資源中已經有作者姓名和電子郵件地址的值。雖然
<author>元素具有兩個子欄位，但在提供的資料中只有<name>元素。因此，系統只會覆寫該欄位的值。您提供的資料中缺少的<email>元素值維持不變。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>隨附重複欄位。如果資源資料中已指定重複元素的值，則您提供的新元素會新增到現有的值組中。
請注意，有時你可能需要執行其他操作，而不是新增重複元素的新執行個體。舉例來說，您可以執行下列任一操作：
取代整個重複元素清單。您可以使用
gd:fields屬性 (例如gd:fields='ns:accessControl') 刪除所有重複的欄位，並提供完整的替換欄位組合。由於系統會刪除所有現有的元素，因此所提供的欄位組合在附加後不會與任何現有值發生衝突。針對重複元素取代一組現有值中的某個值。在這種情況下，只要將
gd:fields值縮小得夠窄，即可移除單一元素，以免想要刪除其他值。例如，如果只想移除action為embed的存取權控管，您可以使用gd:fields='ns:accessControl[@action="embed"]'。然後，在<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>
處理部分更新的回應
處理有效的部分更新要求後，API 會傳回 200 OK HTTP 回應代碼。根據預設，回應的主體是您更新的完整項目。成功處理 PATCH 要求時，伺服器會更新 ETag 值，就像使用 PUT 一樣。
如果 PATCH 要求產生的語法或語意新資源狀態無效，伺服器會傳回 HTTP 400 Bad Request 或 422 Unprocessable Entity HTTP 狀態碼，且資源狀態將維持不變。舉例來說，如果您嘗試刪除必填欄位而不提供替換欄位，伺服器就會傳回錯誤。
注意：請務必瞭解不同欄位彼此之間的關聯。僅更新部分互斥值的部分，或許可以讓資源處於不一致的狀態。舉例來說，您或許可以將開始時間更新為晚於結束時間的值。雖然 API 應該會傳回錯誤代碼，但還是建議您完整測試這類條件，以確保一致性。
不支援 PATCH 時的替代標記法
如果您的防火牆不允許 PATCH，請執行 HTTP POST 要求並將覆寫標頭設為 PATCH，如下所示：
POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...
使用部分回應進行部分更新
您可以使用部分回應，做為後續部分更新要求的基礎。做法是指定包含編輯連結的 fields 查詢參數以及 @gd:*。這可確保部分回應包含 ETag 和 gd:fields 屬性值等資訊，這些資訊在後續的請求中至關重要。
以下是會傳回部分回應做為範例的後續回應範例：
http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who
伺服器會回應：
<?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>
假設您想移除電子郵件地址為 'jane@gmail.com' 的使用者，並新增 'will@gmail.com' 使用者，並將目前列為 'jo@gmail.com' 的使用者電子郵件地址變更為 'josy@gmail.com'。
您只要從上一次回應的結果開始，只修改不同的欄位，並提交修改過的部分項目做為 PATCH 要求的主體，就可以進行這些變更。在這個範例中，需要修改的項目如下：
- 從提供的元素清單中刪除
<gd:who email='jane'/>。 - 將
<gd:who email='will@gmail.com'/>新增至所提供的元素清單。 - 以
<gd:who email='josy@gmail.com'/>取代<gd:who email='jo@gmail.com'/>。
根據具體部分回應所進行的 PATCH 要求如下所示：
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>
注意：這個方法必須使用 gd:fields 和 gd:etag (如果支援) 屬性在這個項目的部分回應中。部分項目的主體必須保留部分回應中所含的所有欄位和屬性，除非您明確想要移除的欄位。您可以使用新值更新主體中的任何現有欄位，並加入您要加入的任何新欄位。
驗證
當用戶端嘗試存取服務時，可能需要將憑證提供給服務，以證明使用者有權執行相關動作。
用戶端應採用哪種方法，取決於用戶端類型：
- 電腦版應用程式應使用名為帳戶驗證的 Google 專屬驗證系統 (又稱為「ClientLogin」)。(網頁式用戶端不應使用此系統)。
- 網路用戶端 (例如 Google 服務的第三方前端) 應使用名為「網頁式應用程式的帳戶驗證 Proxy」(亦稱「AuthSub」) 的 Google 專用驗證系統。
在 ClientLogin 系統中，桌面用戶端會要求使用者提供憑證，然後將這些憑證傳送到 Google 驗證系統。
如果驗證成功，驗證系統會傳回用戶端在傳送 Data API 要求時所使用的憑證 (在 HTTP 授權標頭中)。
如果驗證失敗，伺服器會傳回 403 Forbidden 狀態碼和 WWW-Authenticate 標頭，其中包含適用於驗證的驗證問題。
AuthSub 系統的運作方式類似，不過使用者不會要求他們提供憑證，而是將使用者導向要求憑證的 Google 服務。接著，服務會傳回一個憑證，供網路應用程式使用；這種方法的優點在於 Google (而非網站前端) 可以安全地處理及儲存使用者的憑證。
如要進一步瞭解這些驗證系統，請參閱 Google Data API 驗證總覽或 Google 帳戶驗證說明文件。
工作階段狀態
許多商業邏輯實作都需要工作階段黏著度，追蹤使用者工作階段的狀態。
Google 追蹤工作階段狀態的方法有兩種：使用 Cookie，以及使用可做為查詢參數傳送的憑證。這兩種方法的效果相同。我們建議客戶支援上述其中一種工作階段狀態追蹤方式 (其中一種)。如果客戶不支援上述任一方法，該用戶端仍可使用 Data API，但與支援這些方法的用戶端相比，效能可能較不理想。具體來說，如果用戶端不支援這些方法，則每個要求都會產生重新導向，因此每個要求 (以及任何相關聯的資料) 都會傳送到伺服器兩次，進而影響用戶端和伺服器的效能。
Google 用戶端程式庫會為您處理工作階段狀態，因此如果您使用了我們的程式庫，則無須執行任何動作，即可取得工作階段狀態支援。
其他資源
以下第三方文件或許能派上用場：
- Atoms 與 RSS 的比較
- IBM 的 Atom 總覽
- Dublin Core 擴充功能 (RSS)
- HTTP 1.1 方法定義；
GET、POST、PUT和DELETE的規格 - HTTP 1.1 狀態碼定義
- 如何建立 REST 通訊協定
- 以 REST 方式打造網路服務
- XML 技術簡介
- XML 命名空間範例
- HTTP 規格的 ETag 部分