Google Data API 通訊協定基本概念

本文件將說明 Google Data API 所使用的通訊協定基本概念，包括查詢的外觀和顯示結果等。

如要進一步瞭解 Google Data API，請參閱 Google Data 開發人員指南文件和參考指南。

目標對象

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

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

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

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

範例

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

要求動態饋給或其他資源

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

GET /myFeed

伺服器會回應：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>

請注意，雖然資訊提供不包含任何項目，但是資訊提供仍然有中繼資料，例如書名和作者姓名。

插入新項目

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

POST /myFeed

<?xml version="1.0"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

更新項目

如要更新現有項目，請使用 PUT 搭配該項目的編輯 URI (如上一個範例中的伺服器所提供的 <link rel="edit"> 元素)。

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

X-HTTP-Method-Override: PUT

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

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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>

請注意，編輯 URI 已經變更；現在以「/2/」取代「/1/」。編輯 URI 的最後一個數字是版本號碼。如要進一步瞭解版本，請參閱通訊協定參考說明文件的最佳並行一節。

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

GET /myFeed

伺服器會回應：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

刪除項目

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

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

 X-HTTP-Method-Override: DELETE

以下範例會刪除項目：

DELETE /myFeed/1/2/

伺服器會回應：

200 OK

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

GET /myFeed

伺服器會回應：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 狀態碼。

其他資源

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

返回頁首