发出直接请求

我们建议您在实现过程中使用客户端库和示例。但是,如果您与该 API 的集成有特殊需求(例如使用不受支持的语言),则可以按照下述方式发出直接请求。

调用样式

REST 是一种软件架构样式,可提供便捷且一致的方法用于请求和修改数据。

术语 REST 是“具象状态传输”的简称。在 Google API 的上下文中,指的是使用 HTTP 谓词来检索和修改由 Google 存储的数据的表示法。

在 RESTful 系统中,资源存储在数据存储区中;在客户端发送要求服务器执行特定操作(例如创建、检索、更新或删除资源)的请求之后,服务器便会执行该操作并发送响应,此响应的格式通常为所指定资源的表示法。

在 Google 的 RESTful API 中,客户端会使用 HTTP 动词(例如 POSTGETPUTDELETE)指定操作。它通过以下形式的全局唯一 URI 指定资源:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

由于所有 API 资源都具有 HTTP 可访问的唯一 URI,因此 REST 启用了数据缓存,而且经过优化以与网络的分布式基础架构一起使用。

您可能会发现 HTTP 1.1 标准文档中的方法定义十分有用;这些定义中包含了 GETPOSTPUTDELETE 的规范。

AdSense Management API 中的 REST

受支持的操作直接映射到 REST HTTP 动词,如 AdSense Management API 操作中所述。

AdSense Management API URI 的具体格式为:

https://adsense.googleapis.com/v2/resourceID?parameters

其中 resourceID 是广告客户、广告单元、网址渠道、自定义渠道或报告集合的标识符,parameters 是应用于查询的任意参数。

resourceID 路径扩展的格式可让您标识当前所针对的资源,例如:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

AdSense Management API 参考文档中总结了用于 API 中每种受支持的操作的全部 URI。

下面的几个示例展示了它在 AdSense Management API 中的工作方式。

列出广告客户:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

在广告客户 ca-pub-1234567890123456 中列出广告单元:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

数据格式

JSON(JavaScript 对象表示法)是一种与语言无关的常见数据格式,可通过简单的文本来表示任意数据结构。如需了解详情,请参阅 json.org

向请求授权

请注意,AdSense 不支持服务帐号,您必须使用“已安装的应用”流程。

您的应用向 AdSense Management API 发送的每个请求都必须包含授权令牌。Google 也可通过此令牌识别您的应用。

关于授权协议

您的应用必须使用 OAuth 2.0 向请求授权,其他任何授权协议均不受支持。如果您的应用使用使用 Google 账号登录,系统会代您执行授权方面的某些操作。

使用 OAuth 2.0 向请求授权

所有发送至 AdSense Management API 的请求都必须由已通过身份验证的用户授权。

使用 OAuth 客户端 ID 可以简化此流程。

获取 OAuth 客户端 ID

或者在“凭据”页面中创建一个 OAuth 客户端 ID。

根据您所编写的应用的类型,OAuth 2.0 的具体授权流程可能会有所不同。下面是适用于所有应用类型的大致流程:

  1. 当您的应用需要访问用户数据时,它会请求 Google 提供特定范围的访问权限。
  2. Google 会向相应用户显示权限请求页面,让用户授权您的应用请求他们的某些数据。
  3. 待该用户同意后,Google 会为您的应用提供一个时效很短的访问令牌
  4. 您的应用会请求获取用户数据,并在请求中附上该访问令牌。
  5. 如果 Google 确定您的请求及令牌有效,就会返回您所请求的数据。

有些流程还包含其他步骤,例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的不同流程,请参阅 Google 的 OAuth 2.0 文档

以下是 AdSense Management API 的 OAuth 2.0 范围信息:

范围 含义
https://www.googleapis.com/auth/adsense 对 AdSense 数据的读/写权限。
https://www.googleapis.com/auth/adsense.readonly 拥有对 AdSense 数据的只读权限。

要通过 OAuth 2.0 请求访问权限,您的应用既需要授权范围信息,也需要 Google 在您注册应用时提供的信息(如客户端 ID 和客户端密钥)。

提示:Google API 客户端库可帮您处理部分授权流程,并且支持多种编程语言;有关详情,请参阅库和示例页面

发出请求

最后一步是发出 API 请求。如需了解具体信息,请参阅参考文档