背景

前期准备

  1. 请您的客户代表为您的应用将要访问的帐号设置适当的权限。
  2. 如果您不熟悉 Authorized Buyers 概念,请访问 Authorized Buyers 帮助中心,并试用界面。 如果您希望使用自己的应用执行实时出价,请阅读 RTB 协议文档。
  3. 请访问 API 控制台设置新项目。登录您的 Google 开发者账号或创建一个账号。系统将提示您创建一个项目并签署一些服务条款。

父级帐号和子帐号

如果您使用的是包含父级帐号和子帐号的帐号结构,那么了解两者之间的互动方式也许能更有效地开展工作。简要总结如下:

子账号

若用户的凭据授予对子帐号的访问权限,则只能查看和修改与其帐号关联的资源。子帐号无法查看或修改属于其他子帐号或父级帐号的资源。

家长账号

如果用户的凭据可授予对父帐号的访问权限,那么除了所有关联的子帐号外,还可以查看和修改父帐号的资源。对于列出所有给定资源的操作,此用户将收到一个响应,其中包含其帐号及其所有子帐号的数据。请注意,对于针对子帐号的资源的其他类型的请求,父级帐号需要为子帐号指定 accountId 路径参数,而不是为其自己的 accountId 指定。

REST API 数据模型

资源是具有唯一标识符的单个数据实体。Accounts 资源代表 Authorized Buyers 帐号条目,也是 Ad Exchange Buyer API 的根数据类。该 API 的方法可作用于个别帐号资源以及一系列帐号资源。

Accounts 资源包括:帐号 ID、Cookie 匹配中使用的信息、出价工具位置、将出价请求发送到的网址,以及用于指定广告交易平台每秒发送的最大查询数的请求。

除了 Accounts 资源和集合之外,Ad Exchange Buyer API 还定义了以下数据结构:

出价方地理位置

出价方位置是与帐号资源一起返回的结构,用于提供广告交易平台应将出价请求发送到的网址,以及广告交易平台每秒应发送的最大查询数。以下是出价工具位置的示例,以 JSON 表示:

"bidderLocation": [
    {
      "url": "http://bid.url.com/bidder",
      "maximumQps": 1500
    }
  ],

内容

用于提供帐号列表。以下是项目的示例,以 JSON 表示:

{
  "kind": "adexchangebuyer#accountsList",
  "items": [
    accounts Resource
  ]
}

支持的操作

您可以在 Ad Exchange Buyer API 中对集合和资源调用三种不同的方法,如下表所述。所有操作都需要授权

操作 说明 REST HTTP 映射
list 列出当前已通过身份验证的用户可以访问的所有帐号。 对集合 URI 执行 GET
get 获取特定的帐号资源。 对资源 URI 执行 GET
update 更新特定的帐号资源。 对资源 URI 执行 PUT,您可以在其中传入更新后的资源的数据。

调用样式

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 的规范。

Ad Exchange 买方 API 中的 REST

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

API URI 的具体格式为:

https://www.googleapis.com/adexchangebuyer/v1.4/resourceID?parameters

其中 resourceID 是 Accounts 资源的标识符,parameters 是要应用于查询的任何参数。如需了解详情,请参阅标准查询参数参考文档

通过 resourceID 路径扩展的格式,您可以标识当前操作的资源,例如:

https://www.googleapis.com/adexchangebuyer/v1.4/accounts
https://www.googleapis.com/adexchangebuyer/v1.4/accounts/id

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

以下示例展示了它在 Ad Exchange 买方 API 中的运作方式。

获取经过身份验证的用户的帐号列表:

GET https://www.googleapis.com/adexchangebuyer/v1.4/accounts

数据格式

JSON

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