KeywordSelector

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

用法示例：

    var iterator = AdsApp.keywords()
        .withCondition("AdGroupName = 'AD GROUP NAME GOES HERE'")
        .withCondition("CampaignName = 'CAMPAIGN NAME GOES HERE'")
        .get();

    while (iterator.hasNext()) {
        var keyword = iterator.next();
    }

方法

方法名称	返回类型	说明
forDateRange (Object dateFrom、Object dateTo)	KeywordSelector	应用开始和结束日期以选择性能指标。
forDateRange (字符串 dateRange)	KeywordSelector	应用预定义的日期范围来选择性能指标。
get	KeywordIterator	获取用于循环访问关键字列表的迭代器。
orderBy (字符串 orderBy)	KeywordSelector	将指定的排序应用于所选关键字。
withCondition (字符串条件)	KeywordSelector	将筛选条件应用于 关键字。
withIds (string[] ids)	KeywordSelector	获取具有指定 ID 的关键字。
withLimit (int limit)	KeywordSelector	获取与选择条件匹配的前 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	日期范围的结束日期，指定要包含在选择器中的性能数据。

返回

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

forDateRange (String 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	预定义的日期范围字符串，指定要包含在选择器中的性能数据。 预定义的日期范围字符串区分大小写。

返回

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

获取

获取用于循环访问关键字列表的迭代 器 。

返回

类型	说明
KeywordIterator	用于循环访问所选关键字的迭代器。

orderBy (string orderBy)

将指定的排序应用于所选关键字。

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

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

例如，以下调用按 AverageCpc 按升序返回结果。

selector = selector.orderBy("AverageCpc");

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

参数

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

返回

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

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

支持用于关键字 (keyword) 筛选的列。 列名称需区分大小写。

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

Column	类型	示例	Microsoft Advertising Web UI 筛选器
AbsoluteTopImpressionRate	double	withCondition("AbsoluteTopImpressionRate > 0.25")	Abs. Top Impr. 比率
AverageCpc	double	withCondition("AverageCpc < 2.75")	平均 CPC
AverageCpm	double	withCondition("AverageCpm > 0.65")	平均 CPM
ClickConversionRate	double	withCondition("ClickConversionRate > 0.25")	Conv. Rate
点击	long	withCondition("Clicks >= 33")	点击
ConvertedClicks	long	withCondition("ConvertedClicks >= 10")	Conv。
成本	double	withCondition("Cost > 3.25") 成本采用帐户的货币。	花
点击率	double	withCondition("Ctr > 0.05") CTR 在 0..1 范围内，因此使用 0.05 作为 5% 的 CTR。	点击率
展现量	long	withCondition("Impressions > 10")	Impr。
TopImpressionRate	double	withCondition("TopImpressionRate > 0.25")	Top Impr。 比率

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

Column	类型	示例	Microsoft Advertising Web UI 筛选器
状态	枚举	关键字 (keyword) 的状态。 可能区分大小写的值包括： 启用 暂停 删除 withCondition("Status = ENABLED")	状态
CombinedApprovalStatus	string	关键字 (keyword) 的审批状态。 可能区分大小写的值包括： 批准 APPROVED_LIMITED UNDER_REVIEW 反对 有关这些值的信息，请参阅 编辑审批状态值。 此示例返回需要注意的关键字。 withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
Text	string	关键字 (keyword) 的文本。 仅包含关键字 (keyword) 的文本。 不要在文本中包含关键字 (keyword) 的匹配类型。 例如，如果关键字 (keyword) 是完全匹配关键字 (keyword) （如 [books]），则使用书籍而不是 [books]。 withCondition("Text STARTS_WITH 'flowers'")	关键字文本
KeywordMatchType	枚举	关键字 (keyword) 的匹配类型。 可能区分大小写的值包括： 广泛 确切 PHRASE withCondition("KeywordMatchType = EXACT")	匹配类型
MaxCpc	double	关键字 (keyword) 的最大 CPC 出价金额。 CPC 采用帐户的货币。 withCondition("MaxCpc > 0.40")	出价
DestinationUrl	string	withCondition("DestinationUrl STARTS_WITH 'http://www.contoso.com'")	目标 URL
FinalUrls	string	withCondition("FinalUrls CONTAINS 'http://www.contoso.com'")
QualityScore	int	withCondition("QualityScore > 5")	Qual。 得分
FirstPageCpc	double	广告客户每次在边栏上显示广告时，其广告被点击时所收取的平均费用。 例如，如果广告客户共为 300 次点击支付了 48.35 美元，则广告客户的平均 CPC 为 0.16 美元。 使用此信息来帮助确定是否提高关键字 (keyword) 出价，以提高广告显示在边栏上的机会。 CPC 采用帐户的货币。 withCondition("FirstPageCpc > 6.00")	Est。 首页出价
TopOfPageCpc	double	广告客户在广告显示在自然搜索结果上方时，每次点击广告时所收取的平均费用。 例如，如果广告客户共为 300 次点击支付了 48.35 美元，则广告客户的平均 CPC 为 0.16 美元。 使用此信息来帮助确定是否提高关键字 (keyword) 出价，以提高广告显示在自然搜索结果上方的机会。 CPC 采用当前帐户的货币。 withCondition("TopOfPageCpc > 8.00")	最佳位置
AdGroupName	string	包含关键字的广告组的名称。 withCondition("AdGroupName = 'foo'")
AdGroupStatus	枚举	广告组的状态。 可能区分大小写的值包括： 启用 暂停 删除 withCondition("AdGroupStatus = ENABLED")
CampaignName	string	包含关键字的市场活动的名称。 withCondition("CampaignName = 'bar'")
CampaignStatus	枚举	市场活动的状态。 可能区分大小写的值包括： 启用 暂停 删除 withCondition("CampaignStatus = ENABLED")
LabelNames	字符串集	一个或多个区分大小写的标签名称的列表。 使用 获取与命名标签关联的关键字。 withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
Id	长型	要测试的关键字 (keyword) 的 ID。 例如，可以使用此列检查 ID 大于指定 ID 的关键字。 withCondition('Id > 1234')

参数

名称	类型	说明
条件	string	要添加到选择器的条件。

返回

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

withIds (string[] ids)

获取具有指定 ID 的关键字。

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

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

参数

名称	类型	说明
ids	string[]	关键字 (keyword) ID 的数组。 有关限制，请参阅 脚本执行限制。

返回

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

withLimit (int 限制)

获取与选择条件匹配的前 n 个关键字。

参数

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

返回

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

另请参阅

• AdsApp.keywords ()
• KeywordIterator
• 关键字