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

返回

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

forDateRange (字符串 dateRange)

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

支持的日期范围值：

  • 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

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

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

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

参数

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

返回

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

get

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

返回

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

orderBy (字符串 orderBy)

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

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

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

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

selector = selector.orderBy("AverageCpc");

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

参数

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

返回

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

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

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

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

列 类型 示例 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") 平均每千次展示费用
ClickConversionRate double withCondition("ClickConversionRate > 0.25") 转换率
点击次数 long withCondition("Clicks >= 33") 点击次数
ConvertedClicks long withCondition("ConvertedClicks >= 10") Conv.
成本 double withCondition("Cost > 3.25")

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

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

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

列 类型 示例 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) 的匹配类型。 可能的区分大小写的值为：
  • 广泛
  • EXACT
  • 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 美元，则广告商的平均每次点击费用为 0.16 美元。 使用这些信息来帮助决定是否提高关键字 (keyword) 出价，以提高广告出现在边栏上的机会。 CPC 以帐户的货币表示。

withCondition("FirstPageCpc > 6.00")		 估计 首页出价
TopOfPageCpc double 每次点击广告时，当广告显示在自然搜索结果上方时，广告商平均收取的费用。 例如，如果广告商为 300 次点击支付了总计 48.35 美元，则广告商的平均每次点击费用为 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 limit)

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

参数

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

返回

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

另请参阅

  • 上次更新时间为