開發人員指南總覽
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
警告：本頁面說明 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 通訊協定，該程式碼會使用 GET 或 POST 等 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/。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2023-03-01 (世界標準時間)。
[null,null,["上次更新時間：2023-03-01 (世界標準時間)。"],[[["\u003cp\u003eThe Google Data Protocol enables external developers to build applications that access and update data stored in various Google products.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can use the protocol directly via HTTP requests or leverage client libraries for supported programming languages.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Data Protocol v2.0, aligned with AtomPub RFC 5023, introduces features like HTTP ETags, Partial Response, and Partial Update for enhanced efficiency.\u003c/p\u003e\n"],["\u003cp\u003eUpgrading to Protocol v2.0 may require updating client applications to handle changes related to version requests, optimistic concurrency, URIs, and namespaces.\u003c/p\u003e\n"],["\u003cp\u003eRefer to specific product documentation and the Google Data APIs directory for API details and compatibility.\u003c/p\u003e\n"]]],[],null,["# Developer's Guide Overview\n\n**Warning** : This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the [Google Data APIs directory](/gdata/docs/directory), many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see [Google Accounts Authentication and Authorization](/accounts).\n\nGoogle's mission is to organize the world's information and make it universally accessible and useful. This includes making information accessible in contexts other than a web browser and accessible to services outside of Google.\n\nThe Google Data Protocol provides a secure means for external developers to write new applications that let end users access and update the data stored by many Google products. External developers can use the Google Data Protocol directly, or they can use any of the supported programming languages provided by the client libraries. \n\nAudience\n========\n\nThis set of documents is intended for anyone who wants to understand Google Data Protocol. Even if you just want to write code that uses the language-specific [client libraries](/gdata/docs/client-libraries), this document set can be helpful if you want to understand what's going on beneath the client-library abstraction layer.\n\nIf you're looking for the Developer's Guide for a specific API, visit the Google Data Protocol [API Directory](/gdata/docs/directory).\n\nIf you want to access an API in your favorite programming language, visit the [Client Libraries](/gdata/docs/client-libraries) download page.\n\nBackground\n==========\n\nA number of Google products, such as Calendar and Spreadsheets, provide APIs that are based on the Google Data Protocol. You, the developer, can use these APIs to write client applications that give end users new ways to access and manipulate the data they store in those Google products.\n\n**Note:** Google products that provide APIs are sometimes referred to as *services* in these and other related documents.\n\nIf you write code that uses the Google Data Protocol directly, it accesses the API using HTTP requests like `GET` or `POST`. With these requests, data stored by the Google product is transferred back and forth over the wire in the form of data feeds. The data feeds are simply structured lists that contain the data. Historically, the primary feed format has been AtomPub XML, but now JSON, or JavaScript Object Notation, is also available as an [alternate format](/gdata/docs/json).\n\nIf you prefer not to write code that makes HTTP requests directly, you can instead program your client application using one of the programming languages available in the set of client libraries provided. When you do this, the details of the HTTP requests are handled by the client library; you write your code at a more conceptual level using the language-specific methods and classes provided by the client library.\n\nRefer to the product-specific documentation for more information about the particular languages available for the API, or API version, you are using.\n\nVersions of the protocol\n========================\n\n### Protocol Version 2.0 vs. Protocol Version 1.0\n\nThe first version of the Google Data Protocol was developed before the Atom Publishing Protocol was finalized. The second version of the Google Data Protocol is fully compliant with the AtomPub [RFC 5023](http://www.rfc-editor.org/rfc/rfc5023.txt) standard.\n\nThe Google Data Protocol Version 2.0 also includes support for:\n\n- [HTTP ETags](/gdata/docs/2.0/reference#ResourceVersioning). A web standard that helps your client applications make better use of HTTP caching. The services included in the client libraries that support Protocol v2.0 handle ETags automatically.\n- [Partial Response](/gdata/docs/2.0/reference#PartialResponse) and [Partial Update](/gdata/docs/2.0/reference#PartialUpdate) (Experimental). Features that let you make requests that transfer less data. By requesting only the information that you actually need, or by sending updates that include only the data that you actually want to change, your client application can be much more efficient in its use of network, CPU, and memory resources. Currently, partial response and partial update are available only for some products; see the product-specific documentation to find out if your API supports it.\n\n### Updating your application\n\nIf the API you are using was built upon the latest version of the protocol, then the Protocol v2.0 functionality is included in its documentation. In general, we recommend that you upgrade your client application to the latest version available for your API.\n\n#### Updating a client-library-based client\n\nIf your client application uses a client library, such as the Java client library or the .NET client library, it may contain a version of the API that supports Protocol v2.0 features. To find out, refer to the API documentation for the Google product you are using to find out if both of the following are true:\n\n- There is an API version that supports Google Data Protocol v2.0 features.\n- The client library you are using also supports that API version.\n\nIf the client library supports it and you want to update your existing application, just download and use the latest version of the client library. All of your code still works, and the client library takes care of the Protocol v2.0 changes under the hood.\n\n#### Updating a raw HTTP client\n\nIf you wrote your client application using the Google Data Protocol directly, you need to make these changes:\n\n- **Non-default version requests.** Add an HTTP version header (`GData-Version: `*X*`.0`) to every HTTP request you send, where *`X`* is the version of the API that supports Google Data Protocol v2.0 features. Alternatively, add a query parameter (`v=`*X*`.0`) to the URL of every request, where *`X`* is, again, the correct version of the API. If you do not specify a later version, your requests are sent to the earliest supported version of the API by default.\n- **Optimistic concurrency.** If you were using a version of an API that supported optimistic concurrency, you may need to change your update and delete code to use ETags. For more information, read the [ETags section](/gdata/docs/2.0/reference#ResourceVersioning) of the Google Data Protocol reference documentation, and read the Update and Delete sections of the Protocol developer's guide for the service your client application is using.\n- **Self or edit URIs.** If your client keeps track of self or edit URIs for feeds or entries, note that those URIs may have changed. To get the new URI, re-request the item using the old URI, but mark the request as a version *X* .0 request, where *X* is the version of the API that supports Google Data Protocol v2.0 features. The server returns the new representation of the entry, including the new URIs, which you can store in place of the old ones.\n- **Namespace URIs.** If your client stores Google Data Protocol API namespace URIs locally, or has them hard-coded, you'll need to update them:\n - The AtomPub namespace (prefix `app`) has been changed from `http://purl.org/atom/app` to `http://www.w3.org/2007/app`.\n - The OpenSearch namespace (prefix `openSearch`) has been changed from `http://a9.com/-/spec/opensearchrss/1.0/` to `http://a9.com/-/spec/opensearch/1.1/`."]]
