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

在 Search Ads 360 账号（客户 ID 为 1234567）中，ID 为 987654 的广告系列的 resource_name：

customers/1234567/campaigns/987654

服务

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

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

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

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