Search Ads 360 Reporting API 结构

Search Ads 360 Reporting API 的主要组成部分是资源和服务。资源表示 Search Ads 360 实体，您可以使用服务检索 Search Ads 360 实体。

对象层次结构

Search Ads 360 账号是一系列对象的层次结构。

  • 账号的顶级资源是客户。

  • 每个账号都包含一个或多个正在投放的广告系列。

  • 每个 Campaign 都包含一个或多个广告组，用于将您的广告划分到逻辑集合中。

  • 每个 AdGroup 都包含一个或多个广告组广告。

  • 您可以将一个或多个 AdGroupCriterion 或 CampaignCriterion 附加到广告组或广告系列。条件用于定义广告的触发方式。

    • 条件类型有很多，例如关键字、年龄段和地理位置。在广告系列一级定义的条件会影响广告系列中的所有其他资源。您还可以指定广告系列级预算和日期。

资源

资源代表 Search Ads 360 账号中的实体。示例资源包括 Customer、Campaign 和 AdGroup。

对象 ID

Search Ads 360 中的每个对象都有自己的 ID。有些 ID 在全球范围内是唯一的，也就是说，在所有 Search Ads 360 账号中都是唯一的；而有些 ID 仅在特定范围内是唯一的。

对象 ID 唯一性范围
预算 ID 全球
广告系列 ID 全球
广告组 ID 全球
广告 ID 广告组

每个 AdGroupId / AdId 对都是全局唯一的。
AdGroupCriterion ID 广告组

每个 AdGroupId / CriterionId 对都是全局唯一的。
CampaignCriterion ID 广告系列

每个 CampaignId / CriterionId 对都是全局唯一的。
广告附加信息 广告系列

每个 CampaignId / AdExtensionId 对都是全局唯一的。
Feed ID 全球
Feed Item ID 全球
Feed Attribute ID 动态
Feed Mapping ID 全球
标签 ID 全球
用户名单 ID 全球

在为 Search Ads 360 对象设计本地存储空间时，这些 ID 规则会很有用。

对象类型

某些对象可用于多种实体类型。如果是这种情况，该对象将包含一个用于描述其内容的 type 字段。例如，AdGroupAd 可以是指文字广告、酒店广告或本地广告。您可以通过 AdGroupAd.ad.type 字段访问类型值。其值会在 AdType 枚举中返回。

资源名称

每个资源都由一个 resource_name 字符串进行了唯一标识，该字符串会将相应资源及其父项连接到路径中。

例如，广告系列资源名称的格式如下：

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

客户 ID 为 1234567 的 Search Ads 360 账号中，ID 为 987654 的广告系列具有以下 resource_name：

customers/1234567/campaigns/987654

服务

借助服务，您可以检索 Search Ads 360 实体和元数据。有三种服务类型：

搜索服务
SearchAds360Service 是一项统一的服务，用于同时检索所有资源对象和效果统计信息。它提供了两种方法：Search 和 SearchStream。这两种方法都需要一个查询，以指定要查询的资源、要检索的资源属性和效果指标、用于过滤请求的谓词，以及用于进一步细分效果统计信息的细分。如需了解详情，请参阅创建搜索报告和 Search Ads 360 查询语言。
现场服务
SearchAds360FieldService 用于检索有关资源的元数据，例如资源的可用属性及其数据类型。您可以请求以下内容的目录：SearchAds360Service 搜索方法中提供的资源、资源字段、细分键和指标。如需了解详情，请参阅检索资源元数据。
特定于实体的服务

这些服务提供用于检索单个资源实例的 GET 请求方法。这对于检查资源的结构非常有用。

实体专用服务的示例包括：