开发者指南概览
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
警告：本页面介绍的是 Google 的旧版 API，即 Google 数据 API；它仅与 Google 数据 API 目录中列出的许多 API 相关，其中许多 API 已替换为较新的 API。如需了解特定新 API，请参阅新 API 的文档。如需了解如何使用较新的 API 向请求授权，请参阅 Google 帐号身份验证和授权。
Google 的使命是：整合全球信息，供大众使用，使人人受益。这包括使信息在除网络浏览器以外的情境中可访问，并可供 Google 以外的服务访问。
Google 数据协议为外部开发者提供了一种编写新应用的安全方式，让最终用户能够访问和更新许多 Google 产品所存储的数据。外部开发者可以直接使用 Google 数据协议，也可以使用客户端库提供的任何受支持编程语言。
观众
本系列文档适用于任何想要了解 Google 数据协议的人员。即使您只想编写使用特定语言的客户端库的代码，但如果您想了解客户端库的抽象层下面发生的情况，本文档组会很有帮助。
如果您正在寻找特定 API 的开发者指南，请访问 Google 数据协议 API 目录。
如果要使用您喜爱的编程语言访问 API，请访问客户端库下载页面。
背景
许多 Google 产品（如 Google 日历和电子表格）都提供基于 Google 数据协议的 API。作为开发者，您可以使用这些 API 编写客户端应用，为最终用户提供访问和操控这些 Google 产品中存储的数据的新方式。
注意：在这些和其他相关文档中，提供 API 的 Google 产品有时被称为“服务”。
如果您编写直接使用 Google 数据协议的代码，它会使用 GET 或 POST 等 HTTP 请求访问该 API。通过这些请求，Google 产品存储的数据可通过数据 Feed 以无线方式来回传输。数据 Feed 只是包含数据的结构化列表。过去，主要 Feed 格式一直是 AtomPub XML，但现在 JSON 或 JavaScript 对象表示法也可以作为备用格式使用。
如果您不想编写直接发出 HTTP 请求的代码，则可以使用提供的客户端库集中提供的一种编程语言来编写您的客户端应用。执行此操作时，HTTP 请求的详细信息将由客户端库处理；您可以使用客户端库提供的特定语言的方法和类在更概念的级别编写代码。
请参阅特定产品的文档，详细了解您目前使用的 API 或 API 版本可用的特定语言。
协议版本
协议版本 2.0 与协议版本 1.0
第一版 Google 数据协议是在 Atom 发布协议最终确定之前开发的。第二版 Google 数据协议完全符合 AtomPub RFC 5023 标准。
Google 数据协议 2.0 版还支持：
- HTTP ETag。一种 Web 标准，可帮助您的客户端应用更好地利用 HTTP 缓存。客户端库中支持协议 v2.0 的服务会自动处理 ETag。
- 部分响应和部分更新（实验性）。这些功能可让您发出传输较少数据的请求。通过只请求您真正需要的信息，或者发送仅包含您真正想要更改的数据的更新，您的客户端应用可以更加高效地使用网络、CPU 和内存资源。目前，只有部分产品支持部分响应和部分更新；如需了解特定 API 是否支持，请参阅特定产品的相关文档。
更新应用
如果您使用的 API 是基于最新版本的协议构建的，那么 Protocol v2.0 功能会包含在其文档中。一般而言，我们建议您将客户端应用升级到 API 可用的最新版本。
更新基于客户端库的客户端
如果您的客户端应用使用客户端库（例如 Java 客户端库或 .NET 客户端库），则其中可能包含支持协议 v2.0 功能的 API 版本。要确定这一点，请参阅您所使用的 Google 产品的 API 文档，确定同时满足以下两个条件：
- 有一个支持 Google 数据协议 v2.0 功能的 API 版本。
- 您使用的客户端库也支持该 API 版本。
如果客户端库支持，而您想更新现有应用，则只需下载并使用最新版本的客户端库即可。所有代码仍然有效，客户端库会在后台处理协议 v2.0 变更。
更新原始 HTTP 客户端
如果您直接使用 Google 数据协议编写客户端应用，则需要进行以下更改：
- 非默认版本请求。。为您发送的每个 HTTP 请求添加一个 HTTP 版本标头 (
GData-Version: X.0)，其中 X 是支持 Google 数据协议 v2.0 功能的 API 版本。或者，在每个请求的网址中添加查询参数 (v=X.0)，其中 X 再次是正确的 API 版本。如果您未指定更新版本，默认情况下，您的请求将发送至支持的最低 API 版本。
- 乐观并发。如果您使用的是支持乐观并发的 API 版本，则可能需要更改更新并删除代码，才能使用 ETag。有关详情，请参阅 Google 数据协议参考文档中的 ETag 部分，并参阅您的客户端应用所用协议的“更新”和“删除”部分。
- 自行或修改 URI如果客户自行跟踪 Feed 或条目的 URI 或修改 URI，请注意这些 URI 可能已更改。要获取新的 URI，请使用旧 URI 重新请求该项目，但将该请求标记为版本 X 请求 0，其中 X 是支持 Google 数据协议 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/”。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2023-03-01。
[null,null,["最后更新时间 (UTC)：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/`."]]
