開發人員指南總覽

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

Google 的使命是彙整全球資訊供大眾使用,讓人人受惠。其中包括在網路瀏覽器以外的環境存取資訊,以及透過 Google 以外的服務存取資訊。

Google 資料通訊協定提供安全的方式,可讓外部開發人員編寫新的應用程式,讓使用者存取及更新許多 Google 產品儲存的資料。外部開發人員可以直接使用 Google Data 通訊協定,也可以使用用戶端程式庫提供的任何支援程式設計語言。

目標對象

本說明文件的適用對象為有意瞭解「Google Data 通訊協定」的使用者。即使您想編寫使用語言專屬用戶端程式庫的程式碼,如果您想瞭解用戶端程式庫抽象層下發生的狀況,這個文件集也能派上用場。

如果您需要特定 API 的開發人員指南,請前往 Google Data 通訊協定的 API 目錄

若要以您偏好的程式設計語言存取 API,請前往用戶端程式庫下載頁面。

背景資訊

許多 Google 產品 (例如日曆和試算表) 都提供以 Google Data 通訊協定為基礎的 API。開發人員可以使用這些 API 撰寫用戶端應用程式,讓使用者透過新的方式存取及操控儲存在 Google 產品中的資料。

注意:在這些 API 和其他相關文件中,提供 API 的 Google 產品有時也稱為「服務」

如果您編寫的程式碼直接使用 Google Data 通訊協定,該程式碼會使用 GETPOST 等 HTTP 要求來存取 API。透過這些要求,Google 產品儲存的資料會以有線形式,以資料動態饋給的形式傳輸。資料動態饋給是包含資料的結構化清單,以往主要動態饋給格式一直都採用 AtomPub XML,但現在 JSON 也可採用替代格式

如果您不想直接撰寫能發出 HTTP 要求的程式碼,可以改用我們提供的用戶端程式庫中提供的一種程式設計語言來編寫用戶端應用程式。這樣做時,HTTP 要求的詳細資料將由用戶端程式庫處理;您可以使用用戶端程式庫所提供的語言專屬方法和類別,以更概念化的方式編寫程式碼。

請參閱產品相關說明文件,進一步瞭解您使用的 API 或 API 版本適用的特定語言。

通訊協定版本

通訊協定版本 2.0 與通訊協定版本 1.0

第一個版本的 Google Data Protocol 是在 Atom 發布通訊協定定案前開發而成。第二版 Google 資料通訊協定完全符合 AtomPub RFC 5023 標準,

Google 資料通訊協定 2.0 版也支援以下功能:

  • HTTP ETag。一種網路標準,可協助用戶端應用程式使用 HTTP 快取。用戶端程式庫支援採用通訊協定 v2.0 的服務,會自動處理 ETag。
  • 部分回應部分更新 (實驗功能)。使用可發出資料傳輸要求的功能。透過只要求實際需要的資訊,或傳送只包含您真正想要變更的資料的更新,您的用戶端應用程式可以更有效率地使用網路、CPU 和記憶體資源。目前只有部分產品支援部分回應和部分更新,請參閱產品專屬的說明文件,瞭解您的 API 是否支援這項功能。

更新申請

如果您使用的 API 是以最新版的通訊協定為基礎,則說明文件中會包含通訊協定 v2.0 的功能。一般而言,我們建議您將用戶端應用程式升級至您的 API 適用的最新版本。

更新以用戶端程式庫為基礎的用戶端

如果您的用戶端應用程式使用用戶端程式庫 (例如 Java 用戶端程式庫或 .NET 用戶端程式庫),其中可能包含支援通訊協定 v2.0 功能的 API 版本。如要瞭解情況,請參閱您所使用 Google 產品的 API 說明文件,瞭解以下兩項敘述是否正確:

  • 有一個 API 版本支援 Google Data Protocol v2.0 功能。
  • 您使用的用戶端程式庫也支援該 API 版本。

如果用戶端程式庫支援該功能,而您想更新現有的應用程式,只要下載並使用最新版的用戶端程式庫即可。您所有的程式碼仍可正常運作,用戶端程式庫會負責處理通訊協定 v2.0 的異動。

更新原始 HTTP 用戶端

如果您使用 Google Data 通訊協定直接編寫用戶端應用程式,則必須進行以下變更:

  • 非預設版本要求。每次傳送 HTTP 要求時,請加上 HTTP 版本標頭 (GData-Version: X.0),其中 X 是支援 Google Data Protocol v2.0 功能的 API 版本。您也可以在每個要求的網址中加入查詢參數 (v=X.0),其中 X 再次是正確的 API 版本。如未指定較新的版本,系統預設會將你的要求傳送至 API 最早支援的版本。
  • 樂觀並行。如果您使用的 API 版本支援樂觀並行,您可能需要變更更新及刪除程式碼,才能使用 ETag。如需詳情,請參閱 Google Data 通訊協定參考說明文件的 ETag 部分,以及讀取用戶端應用程式所用通訊協定的「通訊協定開發人員指南」的「更新和刪除」一節。
  • 自行編輯或編輯 URI。如果你的用戶端持續追蹤動態饋給或項目的 URI,請注意,這些 URI 可能已變更。如要取得新的 URI,請使用舊的 URI 重新要求項目,但將要求標示為 X.0 版本,其中 X 是支援 Google Data Protocol v2.0 功能的 API 版本。伺服器會傳回項目的新表示法,包括新的 URI,您可以儲存新 URI。
  • 命名空間 URI。如果您的用戶端將 Google Data Protocol API 命名空間 URI 儲存在本機,或以硬式編碼方式寫入,就必須更新:
    • AtomPub 命名空間 (前置字串 app) 已從 http://purl.org/atom/app 變更為 http://www.w3.org/2007/app
    • OpenSearch 命名空間 (前置字元 openSearch) 已從 http://a9.com/-/spec/opensearchrss/1.0/ 變更為 http://a9.com/-/spec/opensearch/1.1/