本頁面由 Cloud Translation API 翻譯而成。

通訊協定基本概念

警告：本頁面說明 Google 的舊版 API (即 Google Data API)；該 API 只與 Google Data API 目錄中列出的 API 相關，其中許多 API 已由新版 API 取代。如需特定新的 API 的相關資訊，請參閱新 API 的說明文件。如要瞭解如何使用新版 API 授權要求，請參閱 Google 帳戶驗證與授權。

本文件說明許多 Google API 所使用的 Google Data 通訊協定相關基本概念，包括查詢的示例、結果的外觀等。

如要進一步瞭解 Google 資料通訊協定，請參閱《開發人員指南》總覽頁面和通訊協定參考資料。

目標對象

本文件旨在協助大家瞭解 Google Data API 使用的 XML 格式和通訊協定的一般概念。

即使您只是想要編寫使用特定語言專屬用戶端程式庫的程式碼，我們還是建議您閱讀本文，以瞭解用戶端程式庫抽象層背後的情況。

本文件假設您瞭解 XML、命名空間、聯合發布的動態饋給、HTTP 中的 GET、POST、PUT 和 DELETE 要求，以及 HTTP 的「資源」概念。如要進一步瞭解相關資訊，請參閱本文的其他資源一節。

本文件不依賴任何特定的程式設計語言；您的用戶端可以使用任何程式設計語言來與伺服器互動，讓您發出 HTTP 要求及剖析 XML 回應。

如果您想嘗試本文件中的範例，而不用撰寫任何程式碼，不妨看看命令列公用程式 cURL 或 Wget 對您有幫助。如需詳細資訊，請參閱這些公用程式的手動頁面或使用 cURL 的文件，與使用 Google Data 通訊協定的服務互動。

範例

以下示例顯示您可以直接使用 Google Data Protocol API 通訊協定傳送至一般服務的 HTTP 要求，以及您可能收到的結果。如需如何使用各種程式設計語言來傳送要求，請參閱特定語言的範例和用戶端程式庫。如要瞭解如何將 Google Data Protocol 與特定 Google 服務搭配使用，請參閱該服務的專屬說明文件。

要求動態饋給或其他資源

假設有一個名稱為 /myFeed 的資訊提供，並假設目前並未包含任何項目。如要查看，請傳送下列 HTTP 要求至伺服器：

GET /myFeed

伺服器會回應：

200 OK

<?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."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

請注意，雖然資訊提供不包含任何項目，但是資訊提供仍然有中繼資料，例如書名和作者姓名。也會包含 HTTP ETag 格式的版本 ID。

插入新項目

如要建立新項目，請傳送 POST 要求，並提供新項目的 XML 表示法：

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

請注意，您未提供標準 Atom <id>、<link> 或 <updated> 元素；伺服器會針對您的 POST 要求建立這些元素。另請注意，資訊提供的作者不一定要與項目的作者相同。

伺服器會回應：

201 CREATED

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

搜尋字串

如要對特定字串執行全文搜尋，當您使用支援全文搜尋的服務時，請傳送 GET 要求和 q 參數。如要進一步瞭解查詢參數，請參閱通訊協定參考說明文件中的查詢要求。

GET /myFeed?q=This

伺服器傳送的動態饋給包含與搜尋字串 This 相符的所有項目。(本例中只有一個項目)。

200 OK

<?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/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

更新項目

如要更新現有項目，您必須執行下列步驟。

擷取您要更新的項目。
視需要進行修改。
將 PUT 要求，連同訊息中的更新項目傳送至項目的編輯 URI。在上述範例中，編輯 URI 會顯示為 <link rel='edit'> 元素的 href 屬性。

您還必須指定原始項目的 ETag，以確保不會覆寫他人的變更。

在以下範例中，我們會將該項目的文字從舊值 (「這是我的輸入內容」) 變更為新的值 (「這是我的第一個項目」)。

PUT /myFeed/1/1/

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

伺服器會回應：

200 OK

<?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='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

請注意，ETag 已變更。如要進一步瞭解資源版本，請參閱通訊協定參考說明文件的資源版本管理 (ETags) 一節。

如要在結構定義中查看新項目，請再次要求整個資源：

GET /myFeed

伺服器會回應：

200 OK

<?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/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

附註：如果防火牆不允許 PUT，請執行 HTTP POST 並設定方法覆寫標頭，如下所示：

X-HTTP-Method-Override: PUT

刪除項目

如要刪除現有項目，請使用該項目的編輯 URI (如上例中的伺服器所提供的 URI) 傳送 DELETE 要求。

如果您的防火牆不允許 DELETE，請執行 HTTP POST 並設定方法覆寫標頭，如下所示：

X-HTTP-Method-Override: DELETE

刪除項目時，您可以選擇要刪除條件式刪除作業 (僅在上次擷取項目後未變更時才予以刪除) 或無條件刪除。詳情請參閱通訊協定參考說明文件的資源版本管理 (ETags) 一節。若要進行無條件的刪除作業，請設定下列 HTTP 標頭：

If-Match: *

以下範例會刪除項目 (如果已正確設定標頭)：

DELETE /myFeed/1/

伺服器會回應：

200 OK

再執行另一個 GET，看看動態饋給現在沒有任何項目：

GET /myFeed

伺服器以一個只有中繼資料之外的資訊提供進行回應：

200 OK

<?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/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

如果刪除失敗，伺服器會傳回錯誤代碼。詳情請參閱通訊協定參考說明文件中的 HTTP 狀態碼。

要求部分資訊提供或項目 (實驗功能)

相較於本文提供的簡單範例資訊提供，資訊提供可能相當複雜。使用部分 API 時，您可以只要求所需的元素或屬性，而不顯示完整的資源表示法。避免擷取及剖析不必要的資料，可大幅改善用戶端應用程式的效率。

如要提出部分回應，請使用 fields 查詢參數來指定您要傳回的元素或屬性。詳情請參閱通訊協定參考說明文件中的部分回應。

以下範例中只會要求資訊提供 ID，以及每個資訊提供項目的作者和標題。

GET /myFeed?fields=id,entry(author)

伺服器會回應：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

您可以使用 fields 參數搭配任何傳回資料的要求要求。除了 GET 以外，這也包括 POST 和 PUT (以及用於發出部分更新要求的 PATCH)。

注意事項：fields 查詢參數只會控管回應要求而傳回的資料；這不會影響您在 PUT、POST 或 PATCH 要求主體中提供的資料。

以下為 POST 和 PUT 的範例。

當您提出部分回應的 POST 要求時，您仍須提供與插入新項目一節中相同的資料。下列範例要求部分回應，只包含新項目的標題：
```
POST /myFeed?fields=title
      
...data...
```
伺服器會回應：
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
```
當您針對部分回應提出 PUT 要求時，仍須提供完整資源表示法的修改版本，如更新項目一節中所述。下列範例要求部分回應，只包含經過修改項目的新 ETag 值：
```
PUT /myFeed/1/1?fields=@gd:etag
  
...data...
```
伺服器會回應：
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>
```

更新特定欄位 (實驗功能)

若您使用的 API 支援部分回應，且具有可編輯的欄位，則您在修改項目時，也可以避免傳送不必要的資料。「部分更新」可讓您針對想要變更的欄位，傳送資料。

如要使用部分更新，請將 PATCH 要求傳送至您在 PUT 中使用的相同編輯 URI。你透過 PATCH 傳送的資料必須符合特定慣例。然而，語意相當有彈性，可讓您以單一要求取代目標資源中的資料、新增資料，甚至刪除資料。

注意：和 PUT 一樣，您必須指定原始項目的 ETag，以確保您不會覆寫他人的變更。

如要進一步瞭解 PATCH 及其語意，請參閱通訊協定參考說明文件中的部分更新。

這個範例顯示部分更新要求，可修改項目標題：

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

伺服器收到 PATCH 要求時，會先移除該項目 gd:fields 屬性指定的任何欄位 (如果有的話)，然後將要求主體中提供的所有資料與目標資源合併。在此範例中，標題元素會先從目標資源中移除，然後合併新的標題值。實際上，這項要求會取代舊標題。

不過請注意，PATCH 的語意是將部分表示法「合併」至現有資源。您不一定要移除欄位來更新欄位值。

如果該欄位在目標項目中只能存在一次，合併後，部分表示中的欄位會覆寫目標項目中對應的欄位。
如果該欄位在目標項目中可以重複出現，那麼合併後，系統會將部分欄位加到目標項目中。

重複的和非重複的欄位合併方式會有所不同，下一個範例將新增標題和作者，但不使用 gd:fields 屬性移除其中一個欄位。

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

由於部分項目表示法不含 gd:fields 屬性，因此系統不會移除任何欄位。不過，<title> 和 <author> 元素的新值會與目標資源合併：

由於 Atom 每個項目只允許使用一個標題，因此新標題會覆寫現有值。
由於 Atom 允許每個項目擁有多位作者，因此新作者會附加至目標資源中現有的作者元素清單。

注意：並非所有 API 都符合 Atom 標準。例如，有些 API 只允許每個項目使用一個 <author> 元素；而其他 API 會繼承資訊提供層級的項目作者將欄位設定為唯讀。

伺服器處理有效的 PATCH 要求後，會傳回 HTTP 200 狀態碼，以及更新項目的完整表示法副本。

如果您希望伺服器只傳回特定元素或屬性，可以搭配使用 fields 查詢參數 (搭配 PATCH) 來要求部分回應。

其他資源

以下第三方文件或許能派上用場：

IBM 的 Atom 總覽
HTTP 1.1 方法定義；GET、POST、PUT 和 DELETE 的規格
HTTP 1.1 狀態碼定義
如何建立 REST 通訊協定
以 REST 方式打造網路服務
XML 技術簡介
XML 命名空間範例

返回頁首