使用入门

本文档适用于想要通过AdSense Host API了解其AdSense帐户相关信息的开发者。本文档假设您熟悉网络编程的概念和网络数据格式。

目录

前期准备

获得AdSense帐户

您需要一个用来进行测试的AdSense帐户。如果您已经拥有测试帐户,说明一切准备就绪,您可以访问AdSense界面设置、修改或查看您的测试数据。

熟悉AdSense

如果您不熟悉AdSense概念,请在开始编码之前阅读AdSense介绍信息,并练习使用用户界面

注册应用

要使用AdSense Host API,您必须向Google注册您开发的应用:

  1. 进入API控制台
  2. 登录您的Google帐户或创建一个帐户。
  3. 创建一个新项目。
  4. 在新创建的项目中,点击AdSense Host API下方的“请求访问权限”链接。

如果是OAuth 2.0应用,请执行使用OAuth 2.0访问Google API中描述的额外步骤。

注意:用于注册的Google帐户应该是您的开发者帐户,也就是您希望应用的用户将其视为应用开发者的帐户。该帐户无需与AdSense登录信息相关联,因为用户在使用该应用时将获得对自己帐户的访问权限。

了解AdSense Host API

基本概念

AdSense Host API是基于一些基本的AdSense概念构建的:

  • 广告客户端:广告客户端代表AdSense帐户与AdSense产品(如展示广告或搜索广告)之间的一种关联。每个AdSense帐户可以有一个或多个广告客户端。
  • 渠道:渠道工具可让您跟踪特定网页或网域的广告效果。
  • 报告:报告可让您深入了解自己的收入以及影响这些收入的因素。通过使用渠道,可以针对整个帐户生成报告,也可以针对一部分广告资源生成报告。

支持的操作

API目前支持的操作如下表所示。

操作 说明 REST HTTP映射
list 列出集合中的所有资源。 对集合URI执行GET
get 获取特定资源。 对资源URI执行GET
generate 基于特定资源生成结果集。仅用于报告。 对集合URI执行GET/POST,您需要将资源作为生成操作的定义传入。

所有操作均需要身份验证

调用样式

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

术语REST是“具象状态传输”的简称。就Google API而言,它是指使用HTTP谓词来检索和修改由Google存储的数据的表示形式。

在REST型系统中,资源存储在数据存储区中;在客户端发送要求服务器执行特定操作(如创建、获取、更新或删除资源)的请求之后,服务器便会执行此操作并发送响应,此响应通常会采用已指定资源的表示形式。

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

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

因为所有API资源都具有唯一的HTTP可访问的URI,因此REST不仅支持数据缓存,而且经过优化适用于网络的分布式基础架构。

如需详细了解REST,您可以参考以下第三方文档:


AdSense Host API中的REST

受支持的操作直接对应到REST HTTP谓词,如AdSense Host API操作中所述。

AdSense Host API URI的具体格式为:

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

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

resourceID路径扩展的格式可以让您标识目前操作针对的资源,例如:

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

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

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

列出广告客户端:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

数据格式

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

发出请求

给请求授权

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

关于授权协议

您的应用必须使用OAuth 2.0给请求授权,不支持其他授权协议。

使用OAuth 2.0给请求授权

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

OAuth 2.0的具体授权流程可能会因您所编写的应用类型而异。下面是适用于所有应用类型的通用流程:

  1. 创建应用时,您需要使用Google Developers Console进行注册。然后,Google会提供您后面需要用到的信息,例如客户端ID和客户端密钥。
  2. 在Google Developers Console中激活AdSense Host API。(如果Developers Console中未列出该API,请跳过这一步。)
  3. 当您的应用需要访问用户数据时,它会请求Google提供特定范围的访问权限。
  4. Google会向用户显示同意界面,请用户授权您的应用请求其某些数据。
  5. 如果用户批准,Google会为您的应用提供一个短期访问令牌
  6. 您的应用请求用户数据,在请求中随附该访问令牌。
  7. 如果Google确定您的请求和令牌有效,会返回您请求的数据。

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

以下是适用于AdSense Host API的OAuth 2.0范围信息:

范围 含义
https://www.googleapis.com/auth/adsensehost 对AdSense数据的读取/写入权限。

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

提示:Google API客户端库可帮您处理某些授权流程,且支持多种编程语言;要了解详情,请参阅库和示例页面

有关详情,请参阅OAuth 2.0部分。

发出请求

最后一步是发出API请求。如果您未使用任何客户端库,请参阅参考文档

如果您使用了客户端库,此任务就非常简单。请参阅示例和库,获取有关如何通过Java、Python、PHP或JavaScript客户端库发出首个请求的完整指南。

OAuth 2.0

AdSense Host API中的身份验证和授权由OAuth 2.0处理。不过,由于AdSense Host使用模式方面存在一些特殊要求,处理的过程可能与您在其他Google API中经历的稍有不同。

参与者

OAuth 2.0请求涉及三方:

  • 用户 - 提供个人数据访问权限
  • 开发者 - 通过应用请求访问用户数据
  • Google - 验证上述两方的身份并提供API服务。

不过在使用AdSense Host API时,用户和开发者实际上是同一人,因为您(开发者)将使用API访问您自己的AdSense帐户及您发布商的帐户。

创建项目

您可以在APIs Console页面上创建新的项目。
图1:在API控制台上新建项目

开始之前,您需要在API控制台上创建新项目,就像使用其他任何Google API时一样。您用于创建开发者项目的Google帐户应能访问AdSense Host API,因此请务必使用在您注册时我们提供的沙盒帐户,或者您的AdSense生产帐户(如果您已完成该API的实施并已投入使用)。

您可以在“服务”标签下选择项目中有效的API。
图2:为项目启用和停用的API

有关如何创建Google API项目的详细信息,请参阅API控制台文档

设置API访问权限

创建项目之后,您需要创建OAuth 2.0客户端ID以为其启用API访问权限。

您可以在“API访问”标签中创建OAuth 2.0客户端。
图3:在API控制台中创建新的OAuth 2.0客户端

您有多个选项可以选择,不过我们建议您创建“安装版应用”项目,这样能使后续步骤更容易执行。

一次身份验证,永久存储

现在,您需要使用自己的AdSense帐户进行身份验证,可利用一小段脚本或一个测试应用来执行此操作(有关示例,请参阅示例代码)。

完成身份验证后,请务必存储系统在授权步骤中返回的刷新令牌。此为长效令牌,只要访问权限没有被明确撤销就不会过期,而身为用户,您不能撤销访问自己应用的权限!

您应将刷新令牌保存到应用的数据存储区中,以供日后的所有身份验证请求使用。

在应用中使用保存的令牌

获得刷新令牌后,无需考虑令牌是在“网络服务器应用”流程还是“已安装应用”流程中生成的。如有需要,您可以直接使用该令牌来发出令牌刷新请求,以获取新的访问令牌。如果您使用了我们的某个客户端库,请参阅相关文档,了解如何自行指定令牌;您可能需要修改自动生成的文件或某数据库条目。

总结

最终的结果是,OAuth 2.0流程仅需执行一次,此后所有请求都将在后台进行,无需您网站上的最终用户(发布商)或您(开发者)进行任何人工干预。

通知

请查看AdSense API通告,了解新版本、新功能以及重要服务的最新动态。

发送以下问题的反馈:

此网页
AdSense Host API
AdSense Host API