AdSelector

包含用于对广告列表进行筛选和排序的方法。 有关选择器的信息，请参阅 选择器。

方法

方法名称 返回类型 说明
forDateRange (对象 dateFrom， 对象 dateTo) AdSelector 应用开始日期和结束日期来选择性能指标。
forDateRange (字符串 dateRange) AdSelector 应用预定义的日期范围来选择性能指标。
get AdIterator 获取用于循环访问广告列表的迭代器。
orderBy (字符串 orderBy) AdSelector 将指定顺序应用于所选广告。
withCondition (字符串条件) AdSelector 将筛选条件应用于广告。
withIds (string[] ids) AdSelector 获取具有指定 ID 的广告。
withLimit (int limit) AdSelector 获取与选择条件匹配的前 n 个广告。

forDateRange (对象 dateFrom， 对象 dateTo)

应用开始日期和结束日期来选择性能指标。

仅在以下情况下指定日期范围：

  • 应用引用性能指标字段的条件或顺序。
  • 你希望获取所选对象的性能数据。 例如，如果计划调用该 getStats() 方法。

可以使用字符串或对象指定日期参数。 若要使用字符串，请以 YYYYMMDD 格式指定日期。 如果使用对象，请使用以下字段创建对象：

  • year
  • month
  • day

例如：

var date = {year: 2018, month: 5, day: 13};

月份为基础，其中 1 为 1 月，12 为 12 月。

日期范围为包含。 如果指定多个日期范围，则仅使用最后一个日期范围。

参数

名称 类型 说明
dateFrom Object 日期范围的开始日期，该日期范围指定要包含在选择器中的性能数据。
dateTo Object 日期范围的结束日期，该日期范围指定要包含在选择器中的性能数据。

返回

类型 说明
AdSelector 应用日期范围的选择器。

forDateRange (字符串 dateRange)

应用预定义的日期范围来选择性能指标。

仅在以下情况下指定日期范围：

  • 应用引用性能指标字段的条件或顺序。
  • 你希望获取所选对象的性能数据。 例如，如果计划调用该 getStats() 方法。

如果指定多个日期范围，则仅使用最后一个日期范围。

支持的日期范围值：

  • TODAY
  • 昨天
  • LAST_WEEK
  • LAST_BUSINESS_WEEK
  • LAST_7_DAYS
  • THIS_WEEK_SUN_TODAY
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_WEEK_SUN_SAT
  • THIS_MONTH
  • LAST_MONTH
  • ALL_TIME

参数

名称 类型 说明
dateRange String 预定义的日期范围字符串，用于指定要包含在选择器中的性能数据。 预定义的日期范围字符串区分大小写。

返回

类型 说明
AdSelector 应用日期范围的选择器。

get

获取用于循环访问广告列表的 迭代器 。

返回

类型 说明
AdIterator 用于迭代所选广告的迭代器。

orderBy (字符串 orderBy)

将指定顺序应用于所选广告。

在“columnName orderDirection”格式中指定 orderBy 参数，其中：

  • columnName 是 受支持的列之一。
  • orderDirection 是对结果排序所依据的顺序。 设置为 ASC 以按升序对结果进行排序，设置为 DESC 以按降序对结果进行排序。 默认值为 ASC。

例如，以下调用按 AverageCPC 升序返回广告。

selector = selector.orderBy("AverageCpc");

选择器仅支持按一个字段对实体进行排序。 您不能按字段 x 排序实体列表，按字段 y 排序 x 内的实体列表，等等。 如果在链或单独的选择器调用中指定多个 orderBy() 调用，脚本将使用上次 orderBy() 调用中指定的字段对实体列表进行排序。 

参数

名称 类型 说明
orderBy string 要应用的顺序。

返回

类型 说明
AdSelector 应用了排序的选择器。

withCondition (字符串条件)

将筛选条件应用于广告。

在“columnName operator value”格式中指定 条件 参数，其中：

运算符

使用的运算符取决于列的类型。 运算符区分大小写。 例如，使用 STARTS_WITH 而不是 starts_with。

包含整数和长值的列的运算符：

<
<=
>
>=
=
!=

包含 double 值的列的运算符：

<
>

包含字符串值的列的运算符：

=
!=
STARTS_WITH
STARTS_WITH_IGNORE_CASE
CONTAINS
CONTAINS_IGNORE_CASE
DOES_NOT_CONTAIN
DOES_NOT_CONTAIN_IGNORE_CASE

包含枚举值的列的运算符：

=
!=
IN []
NOT_IN []

包含字符串数组的列的运算符：

CONTAINS_ALL
CONTAINS_ANY
CONTAINS_NONE

支持的列

支持用于筛选广告的列。 列名称需区分大小写。

以下是你可能指定的性能指标列。

列 类型 示例
AbsoluteTopImpressionRate double withCondition("AbsoluteTopImpressionRate > 0.25")
AverageCpc double withCondition("AverageCpc < 2.75")
AverageCpm double withCondition("AverageCpm > 0.65")
ClickConversionRate double withCondition("ClickConversionRate > 0.25")
点击次数 long withCondition("Clicks >= 33")
ConvertedClicks long withCondition("ConvertedClicks >= 10")
成本 double withCondition("Cost > 3.25")

成本以帐户货币为单位。
中心 double withCondition("Ctr > 0.05")

CTR 在 0..1 范围内，因此对于 5% 的 CTR 使用 0.05。
展现量 long withCondition("Impressions > 10")
TopImpressionRate double withCondition("TopImpressionRate > 0.25")

以下是可指定的实体属性。

列 类型 示例
状态 枚举 广告的状态。 可能的区分大小写的值为：
  • 已启用
  • 已暂停
  • 已删除
此示例仅返回已启用的广告。

withCondition("Status = ENABLED")
类型 枚举 广告的派生类型。 可能的区分大小写的值为：
  • EXPANDED_TEXT_AD
此示例仅返回展开文字广告。

withCondition("Type = EXPANDED_TEXT_AD")
CombinedApprovalStatus string 广告的审批状态。 可能的区分大小写的值为：
  • 已批准
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • 未批准
有关这些值的信息，请参阅 编辑审批状态值。

此示例返回需要注意的广告。

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
CreativeFinalUrls string 广告的最终 URL。

withCondition("CreativeFinalUrls CONTAINS_IGNORE_CASE 'contoso.com'")
AdGroupName string 广告所属的广告组的名称。

withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")
AdGroupStatus 枚举 广告所属的广告组的状态。 可能的区分大小写的值为：
  • 已启用
  • 已暂停
  • 已删除
此示例仅返回父广告组已暂停的广告。

withCondition("AdGroupStatus = PAUSED")
CampaignName string 广告所属市场活动的名称。

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
CampaignStatus 枚举 广告所属市场活动的状态。 可能的区分大小写的值为：
  • 已启用
  • 已暂停
  • 已删除
此示例仅返回父级市场活动已暂停的广告。

withCondition("CampaignStatus = PAUSED")
LabelNames 字符串集 一个或多个区分大小写的标签名称的列表。 用于获取与命名标签关联的广告。

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
Id 长型 要测试的广告的 ID。 例如，您可以使用此列来检查 ID 大于指定 ID 的广告。

withCondition('Id > 1234')

参数

名称 类型 说明
条件 string 要应用于选择器的条件。

返回

类型 说明
AdSelector 应用了条件的选择器。

withIds (string[] ids)

获取具有指定 ID 的广告。

可以对选择器应用一个或多个条件。 条件链被视为 AND 操作。 例如，仅当条件 A 为 True 且条件 B 为 true 时，才会选择实体。 例如，以下调用仅选择广告 33333。

var selector = AdsApp.ads()
    .withIds([11111, 22222, 33333])
    .withIds([33333, 44444, 55555]);

参数

名称 类型 说明
ids string[] 广告 ID 的数组。 有关限制，请参阅 脚本执行限制。

返回

类型 说明
AdSelector 应用了 ID 的选择器。

withLimit (int limit)

获取与选择条件匹配的前 n 个广告。

参数

名称 类型 说明
limit int 要返回的广告数。 实际数字可能更少。

返回

类型 说明
AdSelector 应用了限制的选择器。

另请参阅

AdsApp.ads ()

  • Last updated on