CampaignSelector

项目
11/13/2024

包含用于筛选和排序市场活动列表的方法。有关选择器的信息，请参阅选择器。

用法示例：

    var iterator = AdsApp.campaigns()
        .withCondition("ClickConversionRate > 0.3")
        .forDateRange("LAST_WEEK")
        .orderBy("Clicks DESC")
        .get();

    while (iterator.hasNext()) {
        var campaign = iterator.next();
        var metrics = campaign.getStats();
    }

方法

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

forDateRange (Object dateFrom、Object dateTo)

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

仅当：

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

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

year
month
一天

例如：

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

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

日期范围是非独占的。如果指定多个日期范围，则仅使用最后一个日期范围。

参数

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

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

forDateRange (字符串 dateRange)

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

支持的日期范围值：

今天
昨天
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

仅当：

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

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

参数

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

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

获取

获取用于循环访问市场活动列表的迭代器。

类型	说明
CampaignIterator	用于循环访问所选市场活动的迭代器。

orderBy (string orderBy)

将指定的排序应用于所选市场活动。

在“columnName orderDirection”窗体中指定 orderBy 参数，其中：

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

例如，以下调用按 AverageCpc 按升序返回市场活动。

selector = selector.orderBy("AverageCpc");

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

参数

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

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

withCondition (字符串条件)

将筛选器应用于市场活动列表。

以“columnName 运算符值”的形式指定条件参数，其中：

columnName 是受支持的列之一。如果 columName 设置为性能指标列名称，则必须使用 forDateRange (String dateRange) 或 forDateRange (Object dateFrom、Object dateTo) 指定日期范围。
运算符 是受支持的运算符之一。

运算符

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

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

<
<=
>
>=
=
!=

包含双精度值的列的运算符：

<
>

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

=
!=
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

支持用于市场活动筛选的列。列名称需区分大小写。

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

Column	类型	示例
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 范围内，因此使用 0.05 作为 5% 的 CTR。
展现量	long	`withCondition("Impressions > 10")`
TopImpressionRate	double	`withCondition("TopImpressionRate > 0.25")`

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

Column	类型	示例
状态	枚举	市场活动的状态。可能区分大小写的值包括：启用暂停删除 BUDGET_PAUSED BUDGET_AND_USER_PAUSED 此示例仅返回 enabled enabled。 `withCondition("Status = ENABLED")`
名称	string	市场活动的名称。 `withCondition("Name CONTAINS_IGNORE_CASE 'clearance'")`
预算	double	竞选活动的预算。 `withCondition("Budget > 500.0")`
BudgetType	枚举	市场活动的预算类型。可能区分大小写的值包括：标准加速 `withCondition("BudgetType = 'STANDARD'")`
DeliveryStatus	枚举	市场活动的交付状态。可能区分大小写的值包括：资格 LIMITED_BY_BUDGET HOLD CAMPAIGN_OUT_OF_BUDGET CAMPAIGN_SUSPENDED CAMPAIGN_PAUSED `withCondition("DeliveryStatus NOT_IN ['LIMITED_BY_BUDGET', 'HOLD', 'CAMPAIGN_OUT_OF_BUDGET']")`
LabelNames	字符串集	一个或多个区分大小写的标签名称的列表。使用获取与命名标签关联的市场活动。 `withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")`
类型	枚举	市场活动的类型。可能区分大小写的值包括： SEARCH_AND_CONTENT 购物 DYNAMIC_SEARCH_ADS 此示例仅返回类型为“购物”的市场活动。 `withCondition("CampaignType = SHOPPING")`

参数

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

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

withIds (string[] ids)

获取具有指定 ID 的活动。

可以将一个或多个条件应用于选择器。条件链被视为 AND 操作。例如，仅当条件 A 为 true 且条件 B 为 true 时，才会选择实体。例如，以下调用仅选择市场活动 33333。

AdsApp.campaigns()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

参数

名称	类型	说明
ids	string[]	市场活动 ID 数组。有关限制，请参阅脚本执行限制。

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

withLimit (int 限制)

获取与选择条件匹配的前 n 个 市场活动。

参数

名称	类型	说明
limit	int	要返回的市场活动数。实际数字可能更少。

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

通过