Google advertiser api开发概述

对象、方法和服务

AdWords API 主要供 AdWords 的高级用户使用。如果您是 AdWords 新手，或需要复习 AdWords 基本概念，请查看 AdWords 基础知识页面。

对象层级结构和范围

可以将每个 AdWords 帐号视为由多个对象组成的层级结构。

每个帐号下都有一个或多个 Campaigns，表示您正在投放的广告系列。

每个广告系列有多个 AdGroups，用来按逻辑将您的广告加以组合。

每个 AdGroup 中有多个 AdGroupAds 和 AdGroupCriteria。AdGroupAd 表示您正在投放的广告。AdGroupCriterion 代表用于定义广告触发方式的条件，即关键字。

您可以指定广告系列条件，以定义整个广告系列广告触发方式的规则。您还可以指定整个广告系列的预算和日期。

最后，在广告系列一级可以使用广告附加信息，可让您在广告中提供额外信息，例如电话号码、街道地址等。

AdWords 中的每个对象都由自己的 ID 标识。其中某些 ID 在所有 AdWords 帐号中具有全局唯一性，而其他 ID 仅在限定范围内是唯一的。

AdWords 中每个对象 ID 的唯一性如下表所示。

对象 ID	唯一性的范围	是否在全局级别具有唯一性？
预算 ID	全局	是
广告系列 ID	全局	是
AdGroup ID	全局	是
广告 ID	广告组	否。(AdGroupId, AdId) 对在全局级别具有唯一性。
AdGroupCriterion ID	广告组	否。(AdGroupId, CriterionId) 对在全局级别具有唯一性。
CampaignCriterion ID	广告系列	否。(CampaignId, CriterionId) 对在全局级别具有唯一性。
广告附加信息	广告系列	否。(CampaignId, AdExtensionId) 对在全局级别具有唯一性。
Feed ID	全局	是
Feed Item ID	全局	是
Feed Attribute ID	Feed	否
Feed Mapping ID	全局	是
标签 ID	全局	是

在设计本地数据库以存储 AdWords 对象时，这些 ID 规则很有用。

如果某个对象是从其他对象衍生出来的，那么该对象还会有一个 Type 字段。

例如，TextAd 有一个表示它是衍生自 Ad 对象的 Type 字段。

如果您使用动态语言，可以使用此字段来检查对象的类型，例如，查看 Ad 对象是否为 TextAd 类型。

方法和操作

AdWords API 提供管理 AdWords 对象的服务。

例如，CampaignService 用于管理 Campaign，而 AdGroupService 用于管理 AdGroup，依此类推。

query() 方法

query() 方法是 get() 的替代方法，它使用类似于 SQL 语言的 AdWords 查询语言 (AWQL)，不使用选择器。在 AWQL 中对相同的请求进行编码通常更有效率。大多数常见服务都支持 query() 方法。请注意，AWQL 不支持对数据进行转变。

mutate() 方法

mutate() 方法用于转变（创建、更新或移除）AdWords 对象。

要转变对象，您必须构建相应的 Operation 对象。例如，要转变 Campaign，您必须创建 CampaignOperation。

并发转变

如果您有多个用户使用您的应用更新同一个对象，或者您使用多个线程并行转变 AdWords 对象以获得更高的吞吐量，那么请务必了解 AdWords 如何处理针对同一对象的并发 mutate 请求。

不能同时由多个来源并行修改 AdWords 对象。这包括从同一应用的多个线程或通过其他应用（例如，您的应用和一个同时进行的 AdWords 编辑器会话）更新对象。API 不提供在更新之前锁定对象的方法：如果两个源试图同时转变对象，则 API 会引发 CONCURRENT_MODIFICATION_ERROR 错误。

您可以在这篇博文中了解有关 AdWords API 并发管理的详情。

异步转变与同步转变

AdWords API mutate() 方法是同步的：只有在对象发生转变后，API 调用才会返回响应，因此需要等待对每个请求的响应。虽然这种方法在代码编写方面相对简单，但它可能会对负载平衡造成负面影响，在机器等待调用完成时会造成资源浪费。

另一种方法是使用 BatchJobService 异步转变对象，这种方法无需等待操作完成，即可对多个服务执行批处理操作。提交批处理作业后，AdWords API 服务器会异步执行操作，释放计算机的资源，以便执行其他操作，并定期检查作业状态是否为已完成。

有关异步处理的更多信息，请参见批处理指南。

转变验证

validateOnly SOAP 标头允许测试 API 调用，而不对真实数据实际执行调用：您可以测试缺少的参数和不正确的字段值，而不实际执行操作。

要使用此功能，请在 RequestHeader 中将 validateOnly 字段设置为 true。默认情况下，客户端库会将此字段设置为 false。

系统会对您的请求进行充分验证，就像即将执行该请求一样，但会跳过最终的执行步骤。

如果没有找到错误，则返回空响应。

如果验证失败，错误消息会指明失败点。

使用此会话进行的所有 API 调用都将 validateOnly 标头设置为 true。

validateOnly 标头在测试广告是否存在常见违规情形时特别有用。

如果广告违反了使用特定字词、标点符号、大小写或长度等相关政策，则系统会自动拒绝广告。

如果您尝试批量上传广告，那么一个不良广告就可能导致您的整个批量上传操作失败。

使用 validateOnly 测试新广告可让您轻松查看哪些广告会被拒绝。

请参阅处理违规错误的代码示例以查看实际操作情况。

如果不使用客户端库，则只需设置正确的 SOAP 标头，您仍可以验证您的 mutate() 请求。

AdWords API 服务

本节介绍了 AdWords API 提供的服务，并提供了指向各项服务其他详细信息所在参考页的链接。

AdWords API 服务可组合为四个功能类别：

• 广告系列数据管理
• 优化
• 帐号管理
• 实用工具

广告系列数据管理

使用广告系列数据管理服务来处理 AdWords 广告系列及其相关联的实体。每个广告系列数据管理服务都对应于广告系列数据层级结构中的实体

服务	说明
CampaignService	创建、更新和移除广告系列。广告系列由一个或多个广告组组成，并且有自己的预算、出价策略、投放日期范围和定位设置。
AdGroupService	创建、更新和移除广告组。广告组由一组广告和条件组成，并为其条件提供默认出价。
AdGroupAdService	创建、更新和移除广告。
CampaignExtensionSettingService	创建、更新和移除广告附加信息。广告系列的广告附加信息通过向广告系列中的所有广告添加地址信息、附加链接或电话号码来丰富标准文字广告。
CampaignCriterionService AdGroupCriterionService	创建、更新和移除条件。条件决定广告是否应该展示。
ConversionTrackerService OfflineConversionFeedService	了解用户点击您的广告后会发生什么，以衡量广告和关键字的效果。OfflineConversionFeedService 处理离线转化数据的导入。
DataService	根据指定的条件获取广告系列管理数据。
FeedService FeedItemService FeedMappingService AdGroupFeedService CampaignFeedService	创建自定义数据 Feed 以管理网站、电话和应用附加链接信息。
AdwordsUserListService	创建、更新和移除用户列表。用户列表和用户列表条件会向之前在您的网站上触发了转化事件的用户展示广告。
BudgetService	创建、更新和移除预算。用于管理可在广告系列之间共享的预算。

优化

使用优化服务获取效果统计信息并查找新条件的参考提示。

服务	说明
ReportDefinitionService	创建和下载各种效果报告。
TargetingIdeaService	根据您指定的参数生成新的关键字和展示位置参考提示。
TrafficEstimatorService	获取所提议的广告系列、广告组和关键字的流量估算值。
DraftService 和 TrialService	制作新的草稿和试用版，用于测试您的广告系列设置。有关详情，请参阅此指南。

帐号管理

使用帐号管理服务来跟踪您的帐号活动。

服务	说明
CustomerService	获取有关客户帐号的基本详细信息。
CustomerSyncService	获取指定日期范围内广告系列数据的更改记录。
ManagedCustomerService	管理客户帐号以及经理帐号和客户帐号之间的关联。

实用工具

使用这些实用工具服务通过 AdWords API 执行各种实用任务。

服务	说明
BatchJobService	异步处理大批量的广告系列数据操作。与对标准网络服务的同步调用相比，完成批处理作业所需的时间更长，不过具有其他优势（如批处理指南中所述）。
MediaService	上传和获取您在基于媒体的广告（例如图片广告或视频广告）中使用的媒体的 ID。
ConstantDataService	获取 API 使用的常量值。
LocationCriterionService	获取地理位置条件的 ID。

广告系列数据

处理广告系列数据是使用 AdWords API 执行的基本任务之一。下表说明了各个广告系列数据实体及各实体与其他广告系列数据的关系。

实体 子实体（数量）	数据类型	说明
广告系列 广告组 (1+) 广告系列定位列表 (7) 广告系列广告附加信息 (0+) 广告系列条件 (0+)	Campaign	广告系列由一个或多个广告组组成，并且有自己的预算、出价策略和投放日期范围。
广告组 广告 (1+) 条件 (1+)	AdGroup	广告组由一组广告和条件组成，并为其条件提供默认出价。
广告 广告附加信息覆盖 (0+)	AdGroupAd	可用广告类型在 API 参考中记录为抽象 Ad 类型的子类。
条件 无	AdGroupCriterion，CampaignCriterion	条件决定广告是应该得到展示（可出价条件）还是不应得到展示（排除条件）。广告组条件会影响父级广告组中的广告。广告系列条件（始终是排除条件）定义了阻止广告系列的广告进行展示的条件。
广告附加信息 无	CampaignExtensionSetting	广告系列的广告附加信息通过向广告系列中的所有广告添加地址信息、附加链接或电话号码来丰富标准文字广告。
Feed 无	Feed	Feed 可用作广告附加信息（附加链接、电话、应用）的数据渠道。
用户列表 无	UserList	用户列表跟踪曾对您的网站感兴趣的用户。通过创建用户列表条件并将其关联到现有用户列表，可以将广告定位到这组用户。
预算 无	Budget	预算用于管理在广告系列上花费的金额。可以在不同的广告系列之间共享预算，系统将确定最佳分配方式。

API 调用结构

OAuth2 身份验证

所有 AdWords API 调用都必须通过 OAuth2 授权。

OAuth2 可让您的 AdWords API 客户端应用访问用户的 AdWords 帐号，而无需处理或存储用户的登录信息。

生成 OAuth2 凭据

要生成 OAuth2 凭据，请按以下步骤操作：

确定您的应用类型

首先，为要构建的应用确定适当的应用类型。AdWords API 有两种应用类型选项：

• 已安装应用（推荐）
• 网络应用

请查看下表，了解哪种类型最适合您要构建的应用：

选择此应用类型	如果...
已安装应用（推荐）	您正在使用一个顶级经理帐号管理所有 AdWords 帐号。 您是首次使用的用户，或者想要使用最简单的设置快速上手。 您的应用会管理包含多个用户的同一组 AdWords 帐号。
网络应用	您希望以任何可授予您应用对 AdWords 帐号数据访问权限的用户身份进行验证。 您希望轻松生成多个授权凭据，比如用于管理第三方帐号。 您的应用需要回调网址。已安装应用流程不支持回调网址。

有关详情，请参阅有关已安装应用和网络应用的 Google 身份平台 OAuth 文档。

创建客户端 ID 和客户端密钥

确定应用类型后，请点击下面的相应标签，然后按照说明生成 OAuth2 客户端 ID 和客户端密钥：

OAuth2 Playground

生成 OAuth2 凭据的另一种选择是使用 OAuth2 Playground。OAuth2 Playground 与 Google API 控制台配合使用，可让您手动创建 OAuth2 令牌。

OAuth2 Playground 适用于只需访问单个经理帐号或 AdWords 用户帐号的用户。

如果您需要提示多个用户提供凭据，则可能最好使用上述基于客户端库的方法

OAuth2 服务帐号

本节讨论如何使用服务帐号访问 AdWords API。

服务帐号是属于您的应用而不是个别最终用户的帐号。服务帐号允许网络应用和 Google 服务之间进行服务器到服务器的互动。您的应用会代表服务帐号调用 Google API，因此用户不会直接参与。

AdWords API 允许通过 G Suite 网域访问服务帐号。

服务帐号使用 OAuth2 流程，无需人工授权，但需要使用只有您的应用可以访问的密钥文件。

使用服务帐号主要有以下两个优势：

• 对应用授予 Google API 访问权限的操作是作为配置步骤进行的，可以避免使用其他 OAuth2 流程所带来的复杂问题；用户不需要进行干预，应用也不必为避免将来需要用户干预而缓存令牌。
• OAuth2 断言流程允许您的应用在必要时模拟其他用户。

注意：我们强烈建议您使用已安装应用或网络流程，除非您需要使用网域所特有的功能（例如模拟），否则不建议您使用服务帐号。如果获得了对帐号的访问权限，OAuth2 已安装应用和网络流程只需要一次用户互动。

服务帐号的替代方法

开发者通常会考虑使用服务帐号，因为他们需要在不进行用户干预的情况下，使用 OAuth2 以编程方式访问 API。

考虑到为 AdWords API 设置服务帐号访问权限的复杂性，我们建议使用一个更简单的替代方案来实现相同的目标，即使用 OAuth2 已安装应用流程，并持久保留刷新令牌。这样，如有必要，您的应用始终能够请求新的访问令牌。

此过程需要您根据上述已安装应用过程配置您的客户端库，从而对您的应用进行授权。

前提条件

• 您拥有的 G Suite 网域（如 mydomain.com 或 mybusiness.com）。
• AdWords API 开发者令牌以及（可选）测试帐号。
• 您使用的语言的客户端库。

安全考虑

考虑到 G Suite 的网域级控制，因此一定要保护允许服务帐号访问其获授权的 Google 服务的密钥文件。因为该服务帐号能够模拟网域中的任何用户，所以尤其需要强调这一点。

另一个好的做法是每个服务帐号只允许访问一个 Google API（使用下一节中描述的范围字段）。这是一种先发制人的措施，即使服务帐号的密钥文件被泄露，仍能限制攻击者可以访问的数据量。

授权进行模拟

执行以下步骤，将模拟能力授予服务帐号：

1. 转到 https://admin.google.com/YOUR_DOMAIN/ManageOauthClients，将已获授权的新 API 客户端添加到您的 G Suite 网域中。 注意：请确保将 YOUR_DOMAIN 替换为您的实际域名（例如 mydomain.com）。
2. 使用您在上述步骤中为全网域委派启用服务帐号时生成的 JSON 文件中的客户端 ID，将已获授权的新 API 客户端添加为客户端名称。

3. 输入以下内容作为 API 范围：

   https://www.googleapis.com/auth/adwords

4. 对要向其授予模拟权的所有其他服务帐号重复此过程。

您现在即可使用服务帐号通过 OAuth2 断言流程访问您的 AdWords 帐号。

优化 OAuth2 请求

如果您的应用不能在服务器、进程和线程之间共享凭据，就可能会向 Google 发送过多的请求。这可能导致我们的服务器对您的应用强制执行速率限制，造成性能下降。

本节介绍如何优化 OAuth2 凭据管理，以便您的应用可以与 AdWords API 进行高效互动。

凭据共享策略

跨 API 请求共享凭据可提高性能，并避免可能引发速率限制错误的过多开销。

您的凭据共享策略取决于您的应用设计：

• 多线程应用共享对线程安全的凭据。
• 多进程或分布式应用通过共享数据存储共享凭据。

在多线程应用中，应该为每个线程的会话提供相同的凭据。

在多进程或分布式应用中，要跨进程共享凭据，必须实现一些基础架构。您还应该确保线程不会被阻止，并且自己的实现中不存在争用的情况。

如果应用的每次处理中同时具有多进程/分布式和多线程，则应该同时使用这两种策略。

下面介绍了对单个 AdWords 帐号（例如层级结构中的顶级经理帐号）进行身份验证的这些策略。

然后描述了如何改变这些策略，以便对多个 AdWords 帐号进行身份验证

多线程应用

多线程应用应在线程之间共享凭据。应同步执行对凭据的刷新，以避免出现争用情况。

该图显示了一个运行时，其中带有提取自会话（或用户）池的线程，可向 AdWords API 发出请求。请注意，每个会话应使用相同的凭据对象。在每个 API 请求中，由线程获得会话（或用户）。如果凭据需要访问令牌刷新，则必须同步执行，即凭据对象对线程必须是安全的，以避免出现争用情况。

客户端库可直接跨线程共享凭据。每个客户端库都有一个会话（或用户）对象，并带有可在其生命周期中重用的凭据。要跨线程共享凭据，只需使用相同的凭据构建每个会话即可。在所有客户端库中，凭据是当访问令牌期满时会对自身进行同步刷新的对线程安全的对象。

例如，在 Java 客户端库中，您可以将 Credential 创建为单实例模式，并在所有会话间共享。

多进程或分布式应用

要在多进程或分布式应用中共享凭据，需要实现对凭据的持久保留。为了确保多个进程或服务器不会同时尝试刷新凭据（从而导致刷新请求过多），我们建议在某中央位置主动刷新凭据，并在进程/服务器之间共享凭据。

例如，可以由独立的作业或服务负责周期性地刷新凭据，并且主动将其推送到数据存储，以供服务器池使用。

该图显示了定期运行的凭据刷新作业，并将凭据的属性写入数据存储。然后，每个服务器在向 API 发出请求之前都要获取凭据。

刷新作业

刷新作业会定期刷新凭据并将其存储在数据存储中。作业不应等到当前凭据到期才启动刷新，否则可能导致应用因缺少有效凭据而停止运行，开一个“天窗”。

较好的替代方法是定期强制刷新，每次都用新凭据替换数据存储中的凭据。刷新作业应该在当前凭据到期之前尽早运行，以便预留一些时间，防止出现瞬间失败。比如，可考虑先从每 15 分钟刷新一次开始。

注意：如果在处理 API 请求时，凭据的访问令牌到期，您的请求仍会完成。例如，如果您创建了一个运行时间很长的请求，而剩下的访问时间不到一分钟，系统仍会返回结果。

数据存储

中央数据存储可用于在进程和服务器之间共享凭据。

您既可以使用现有的数据存储，也可以部署一个特定于服务器间凭据共享的数据存储。解决方案既可以是缓存服务器（如 Memcached 或 Infinispan{/1），也可以是 NoSQL 数据存储（如MongoDB）。

对于向 API 发出请求的所有服务器，数据存储必须提供可靠的接口。它应该面向快速读取操作进行优化，原因是服务器或进程对当前凭据的读取频率要高于刷新作业的更新频率。

请记住，对凭据必须进行安全存储。

存储凭据时，应该随 access_token 存储计算出的 expiry_time（现在要 + expires_in）和 refresh_token。expiry_time 计算为 access_token 刷新请求的时间加上 expires_in 时间。

服务器池

池中的每个服务器或进程先从数据存储中获取最新的凭据，然后才发出请求。只要刷新作业成功运行，凭据就会有效。但是，如果刷新作业或数据存储失败，您应该有一个回退机制。

如果服务器或进程无法从数据存储获取凭据，或者凭据已过期，则服务器应刷新自己的凭据，以允许应用继续使用 API，直到问题解决。

在有多个线程的处理过程中，您应该使用上述共享策略在线程间共享凭据。

验证多个帐号的身份

为 AdWords 经理帐号生成的凭据可用于访问其所有子帐号。因此，对于具有单一经理帐号层级结构的用户，通常只需为顶级经理帐号生成凭据，即可为其下的所有 AdWords 帐号实现应用授权。

另一些情况下，您的应用必须访问在任何经理帐号层级结构中彼此都不相关的 AdWords 帐号。在这种情况下，对于不同的帐号（例如您访问的每个 AdWords 客户帐号，或您访问的独立层级结构中的每个顶级经理帐号），您应该生成并维护不同凭据。

只需进行最低程度的修改，即可对多线程和多进程/分布式应用采用相同的策略。使用共享数据存储时，必须通过帐号标识符 customerId 对凭据编制索引，以确保凭据与正确的帐号相关联。此外，刷新作业应保证对所有凭据进行刷新。如果关联了新帐号，则可能需要触发刷新作业。

最后，在多线程应用中，在其间共享凭据对象的线程应该操作于与该凭据对象关联的帐号上。

OAuth2 内部

就以下所涉及的详细信息而言，我们的客户端库会实现自动处理，因此只有在您对后台发生的情况感兴趣时，或者您没有使用我们的任何客户端库时，才需要继续阅读。

本部分的目标读者是熟悉 OAuth 2.0 规范并且了解如何结合使用 OAuth2 和 Google API 的高级用户。

范围

同一个访问令牌可授予对多个 API 的不同级别的访问权限。有一个称为 scope 的可变参数用于控制访问令牌允许的资源和操作集。在请求访问令牌期间，您的应用在 scope 参数中发送一个或多个值。

AdWords API 目前所使用的范围和已弃用的范围：

范围	含义
https://www.googleapis.com/auth/adwords	AdWords API 的读/写访问权限。
https://adwords.google.com/api/adwords/	此范围已弃用，不应再用于获取未来的授权。以前获授权的令牌将继续工作。

离线访问

AdWords API 客户端应用通常会请求进行离线访问。例如，当您的用户并未实际在线浏览您的网站时，您的应用可能会希望运行批处理作业。

要为某网络应用类型请求离线访问，请确保将 access_type 参数设置为 offline。您可以在 Google 的 OAuth2 指南中找到更多信息。

对于已安装应用类型，离线访问在默认情况下处于启用状态，因此您不必专门请求离线访问。

HTTP 请求标头

发送到 AdWords API 服务器的每个请求中的 HTTP 标头都必须包含以下形式的访问令牌：

 

Authorization: Bearer THE_ACCESS_TOKEN

访问令牌和刷新令牌

在大多数情况下，您需要安全地存储刷新令牌以备将来使用。要详细了解如何请求访问令牌和刷新令牌，请阅读与您的应用类型相对应的指南：

• 已安装应用（推荐）
• 使用网络流程的网络应用

访问令牌过期

访问令牌有一个基于 expires_in 值的过期时间；过期后，令牌即会失效。您可以使用刷新令牌刷新过期的访问令牌。

默认情况下，我们的客户端库会自动刷新过期的访问令牌。

AdWords 查询语言 (AWQL)

AWQL 是一种与 SQL 类似的语言，用于对最常见的 AdWords API 服务执行查询。这种语言支持所有提供 query() 方法的服务。

AWQL 的开发灵感源自 SQL，但它并没有全面支持所有 SQL 语汇。值得注意的是，这种语言省略了 JOIN 和 GROUP BY 子句。

对于每项服务，您可以从选择器字段中获取可查询字段的列表。

此外，还可以使用 AWQL 查询报告。有关可查询字段的完整列表，请参阅报告类型。

在服务调用中使用 AWQL

对于相同的调用，使用 AWQL 来编写调用代码通常更为高效

我们的客户端库主要提供的是使用 AWQL 的代码示例，

备注

• 因为请求所发送到的服务已确定数据源，所以不需要 FROM 子句。
• 服务调用中不允许使用 DURING 子句，但报告调用中可以使用这一子句。使用帐号的时区。
• 虽然关键字（如 WHERE）不区分大小写，但字段（列）名（如 Name）和字面值（如 ENABLED）区分大小写。
• 在 WHERE 子句中使用 IN 和 NOT_IN 运算符时，最多可以指定 10000 个条目。

将 AWQL 用于报告

AWQL 经常用在报告中。与通常在报告的“__rdxml”POST 参数中指定 XML 片段不同，需要提供以下两个参数：

1. “__rdquery”：包含 AWQL 查询字符串。
2. “__fmt”：定义报告的下载格式。

下面还列出了将 AWQL 用于报告时的一些用法差异：

• 查询必须在 FROM 子句中包含报告类型，例如：

  SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**

  请注意，尽管在服务调用中不允许使用 FROM，但在报告下载中必须使用该子句。

• 报告的日期范围在查询的 DURING 子句中定义。可以通过以下两种不同的方式指定日期范围：

• 要获取所有日期的数据（等效于 ALL_TIME），可以在查询中省略 DURING 子句。但是，只有当您的查询的 SELECT 子句没有包含 Date 或 Week 列时，才允许如此操作。

• 就报告而言，不支持 ORDER BY 和 LIMIT（排序和分页）。在查询中加入这些子句将发生错误。
• 要忽略展示次数为零的行，请加入 WHERE Impressions > 0 条件。

形式语法

下面列出了 AWQL 形式语法以供参考。

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause?3 LimitClause?4
SelectClause     -> SELECT ColumnList
FromClause       -> FROM SourceName
WhereClause      -> WHERE ConditionList
DuringClause     -> DURING DateRange
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT StartIndex , PageSize

ConditionList    -> Condition (AND Condition)*
Condition        -> ColumnName Operator Value
Value            -> ValueLiteral | String | ValueLiteralList | StringList
Ordering         -> ColumnName (DESC | ASC)?
DateRange        -> DateRangeLiteral | Date,Date
ColumnList       -> ColumnName (, ColumnName)*
ColumnName       -> Literal
SourceName       -> Literal
StartIndex       -> Non-negative integer
PageSize         -> Non-negative integer

Operator         -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
                    CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
                    CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String           -> StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> [ ValueLiteral (, ValueLiteral)* ]5
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
                    LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date             -> 8-digit integer: YYYYMMDD 

注意

• ¹ 在服务调用中不允许使用 FROM 子句，但在报告下载中必须使用该子句。
• ² 在服务调用中不允许使用 DURING 子句。如果您请求的 SELECT 子句包含 Date 或 Week 列，则在报告下载中必须使用该子句。
• ³ 在报告调用中不允许使用 ORDER BY 子句。
• ⁴ 在报告调用中不允许使用 LIMIT 子句。
• ⁵ 对于 ValueLiteralList，必须使用方括号 [ ]；方括号在其他地方用来表示范围。
• ? 表示可选；* 表示一个或多个。
• 顺序：SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT...
• 所有关键字均不区分大小写。
• 列名称和字面值是区分大小写的。
• 空格不起作用。
• 可以在字符串中使用双引号和单引号。相应的转义序列为 \"、\' 和 \\。

　　

• 要获取所有日期的数据（等效于 ALL_TIME），可以在查询中省略 DURING 子句。但是，只有当您的查询的 SELECT 子句没有包含 Date 或 Week 列时，才允许如此操作。

• 就报告而言，不支持 ORDER BY 和 LIMIT（排序和分页）。在查询中加入这些子句将发生错误。
• 要忽略展示次数为零的行，请加入 WHERE Impressions > 0 条件。