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 取得具有指定識別碼的關鍵字。
withLimit (int limit) KeywordSelector 取得符合選取準則的前 n 個 關鍵字。

forDateRange (Object dateFrom， Object dateTo)

套用選取效能指標的開始日期和結束日期。

只有在下列情況下才指定日期範圍：

  • 您套用參照效能計量欄位的條件或排序。
  • 您想要取得所選取物件的效能資料。 例如，如果您打算呼叫 getStats() 方法。

您可以使用字串或物件指定日期參數。 若要使用字串，請以 YYYYMMDD 的形式指定日期。 如果您使用物件，請建立具有下列欄位的物件：

  • 年
  • 月
  • 天

例如：

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

月份為以一為基礎，其中 1 是 1 月，12 為 12 月。

日期範圍包括周邊。 如果您指定多個日期範圍，則只會使用最後一個日期範圍。

引數

名稱 類型 描述
dateFrom 物件 指定要包含在選取器中的廣告成效資料的日期範圍的開始日期。
dateTo 物件 指定要包含在選取器中的廣告成效資料之日期範圍的結束日期。

傳回

類型 描述
KeywordSelector 已套用日期範圍的選取器。

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 字串 預先定義的日期範圍字串，指定要包含在選取器中的廣告成效資料。 預先定義的日期範圍字串會區分大小寫。

傳回

類型 描述
KeywordSelector 已套用日期範圍的選取器。

取得

取得用來逐一查看關鍵字清單的 反覆運算器 。

傳回

類型 描述
KeywordIterator 用來逐一查看所選關鍵字的反覆運算器。

orderBy (字串 orderBy)

將指定的順序套用至選取的關鍵字。

在 “columnName orderDirection” 表單中指定 orderBy 參數，其中：

  • columnName 是支援的其中一個 欄位。
  • orderDirection 是要針對結果排序的順序。 設定為 ASC 以遞增順序排序結果，或設定為 DESC 以遞減順序排序結果。 預設值為 ASC。

例如，下列呼叫會依 AverageCpc 遞增順序傳回結果。

selector = selector.orderBy("AverageCpc");

選取器僅支援依一個欄位來排序實體。 您不得依欄位 x、在 x 內依欄位 y 排序實體清單，依此類推。 如果您在鏈結或單獨的選擇器呼叫中指定多個 orderBy() 呼叫，則指令碼會使用上次 orderBy() 呼叫中指定的欄位對實體清單進行排序。 

引數

名稱 類型 描述
orderBy 字串 要申請的順序。

傳回

類型 描述
KeywordSelector 已套用排序的選擇器。

withCondition (字串條件)

將篩選準則套用至關鍵字。

在「columnName operator value」表單中指定 條件 參數，其中：

運算子

您使用的運算子取決於資料欄位的類型。 運算子會區分大小寫。 例如，使用 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

關鍵字篩選支援的資料行。 欄名稱會區分大小寫。

以下是您可以指定的效能計量資料欄位。

欄位 類型 範例 Microsoft Advertising Web UI 篩選條件
AbsoluteTopImpressionRate double withCondition("AbsoluteTopImpressionRate > 0.25") Abs. Top Impr. Rate
AverageCpc double withCondition("AverageCpc < 2.75") 平均 CPC
AverageCpm double withCondition("AverageCpm > 0.65") 平均 CPM
ClickConversionRate double withCondition("ClickConversionRate > 0.25") 成交率
點選次數 long withCondition("Clicks >= 33") 點選次數
ConvertedClicks long withCondition("ConvertedClicks >= 10") 成交
成本 double withCondition("Cost > 3.25")

費用以帳戶貨幣表示。		 花費
Ctr double withCondition("Ctr > 0.05")

點選率在 0..1 的範圍內，因此使用 0.05 表示 5% 的點選率。		 點選率
閱聽 long withCondition("Impressions > 10") IMPR.
TopImpressionRate double withCondition("TopImpressionRate > 0.25") 要害 Rate

以下是您可以指定的實體屬性。

欄位 類型 範例 Microsoft Advertising Web UI 篩選條件
狀態 列舉 關鍵字的狀態。 可能會區分大小寫的值如下：
  • 已啟用
  • 已暫停
  • 已移除
withCondition("Status = ENABLED")		 狀態
CombinedApprovalStatus 字串 關鍵字的核准狀態。 可能會區分大小寫的值如下：
  • 已核准
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • 未核准
如需這些值的相關資訊，請參閱 編輯核准狀態值。

此範例會傳回需要注意的關鍵字。

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
Text 字串 關鍵字的文字。 只包含關鍵字的文字。 請勿在文字中包含關鍵字的比對類型。 例如，如果關鍵字是完全比對關鍵字，例如 [books]，請使用 books 而不是 [books]。

withCondition("Text STARTS_WITH 'flowers'")		 關鍵字文字
KeywordMatchType 列舉 關鍵字的比對類型。 可能會區分大小寫的值如下：
  • 廣泛
  • EXACT
  • 字詞
withCondition("KeywordMatchType = EXACT")		 符合類型
MaxCpc double 關鍵字的最高每次點選成本出價金額。 每次點選成本是採用帳戶的貨幣。

withCondition("MaxCpc > 0.40")		 出價
DestinationUrl 字串 withCondition("DestinationUrl STARTS_WITH 'http://www.contoso.com'") 連結 URL
FinalUrls 字串 withCondition("FinalUrls CONTAINS 'http://www.contoso.com'")
QualityScore int withCondition("QualityScore > 5") Qual. 分數
FirstPageCpc double 廣告客戶在側邊欄上顯示時，每次點擊廣告時所收取的平均金額。 例如，如果廣告客戶為 300 次點選數支付了總共 48.35 美元，則廣告客戶的平均點選成本為 0.16 美元。 使用此資訊來協助決定是否要增加關鍵字出價，以提高您的廣告出現在側邊欄上的機會。 每次點選成本是採用帳戶的貨幣。

withCondition("FirstPageCpc > 6.00")		 估計 第一頁出價
TopOfPageCpc double 當廣告顯示在自然搜尋結果上方時，每次有人點選廣告客戶時向廣告客戶收取的平均金額。 例如，如果廣告客戶為 300 次點選數支付了總共 48.35 美元，則廣告客戶的平均點選成本為 0.16 美元。 請參考此資訊來協助決定是否要提高關鍵字出價，以提高您的廣告顯示在自然搜尋結果上方的機會。 CPC 是以經常帳戶的貨幣表示。

withCondition("TopOfPageCpc > 8.00")		 「最佳位置」
AdGroupName 字串 含有關鍵字的廣告群組名稱。

withCondition("AdGroupName = 'foo'")
AdGroupStatus 列舉 廣告群組的狀態。 可能會區分大小寫的值如下：
  • 已啟用
  • 已暫停
  • 已移除
withCondition("AdGroupStatus = ENABLED")
CampaignName 字串 包含關鍵字的廣告活動名稱。

withCondition("CampaignName = 'bar'")
CampaignStatus 列舉 行銷活動的狀態。 可能會區分大小寫的值如下：
  • 已啟用
  • 已暫停
  • 已移除
withCondition("CampaignStatus = ENABLED")
LabelNames 字串集 一或多個區分大小寫的標籤名稱清單。 用來取得與具名標籤相關聯的關鍵字。

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
識別碼 Long 要測試的關鍵字 ID。 例如，您可以使用此資料欄位來檢查識別碼大於指定識別碼的關鍵字。

withCondition('Id > 1234')

引數

名稱 類型 描述
條件 字串 要新增至選取器的條件。

傳回

類型 描述
KeywordSelector 具有套用條件的選擇器。

withIds (string[] ids)

取得具有指定識別碼的關鍵字。

您可以將一或多個條件套用至選取器。 條件鏈會被視為 AND 運算。 例如，只有在條件 A 為 True 且條件 B 為 True 時，才會選取實體。 例如，下列呼叫只會選取關鍵字 33333。

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

引數

名稱 類型 描述
IDS string[] 關鍵字 ID 的陣列。 如需限制，請參閱 指令碼執行限制。

傳回

類型 描述
KeywordSelector 具有套用識別碼的選擇器。

withLimit (int limit)

取得符合選取準則的前 n 個 關鍵字。

引數

名稱 類型 描述
限制 int 要傳回的關鍵字數目。 實際數字可能會更少。

傳回

類型 描述
KeywordSelector 已套用限制的選取器。

另請參閱

  • Last updated on