共用方式為

AdSelector

  • 發行項

包含篩選和排序廣告清單的方法。 如需選取器的相關資訊，請參閱 選取器。

方法

方法名稱 傳回類型 說明
forDateRange (Object dateFrom， Object dateTo) AdSelector 套用開始和結束日期以選取效能計量。
forDateRange (字串 dateRange) AdSelector 套用預先定義的日期範圍，以選取效能計量。
get AdIterator 取得用來逐一查看廣告清單的反覆運算器。
orderBy (字串 orderBy) AdSelector 將指定的順序套用至選取的廣告。
withCondition (字串條件) AdSelector 將篩選準則套用至廣告。
withIds (string[] ids) AdSelector 取得具有指定識別碼的廣告。
withLimit (int 限制) AdSelector 取得符合選取準則的前 n 個廣告。

forDateRange (Object dateFrom， Object dateTo)

套用開始和結束日期以選取效能計量。

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

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

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

  • 年
  • 月
  • 一天

例如：

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

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

日期範圍包含在內。 如果您指定多個日期範圍，則只會使用最後一個日期範圍。

引數

名稱 類型 說明
dateFrom 物件 日期範圍的開始日期，指定要包含在選取器中的效能資料。
dateTo 物件 日期範圍的結束日期，指定要包含在選取器中的效能資料。

傳回

類型 說明
AdSelector 已套用日期範圍的選取器。

forDateRange (String dateRange)

套用預先定義的日期範圍，以選取效能計量。

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

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

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

支援的日期範圍值：

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

傳回

類型 說明
AdSelector 已套用日期範圍的選取器。

獲取

取得用來逐一查看廣告清單的 反覆運算器 。

傳回

類型 說明
AdIterator 用來逐一查看所選廣告的反覆運算器。

orderBy (String orderBy)

將指定的順序套用至選取的廣告。

以 「columnName orderDirection」 格式指定 orderBy 參數，其中：

  • columnName 是其中一個 支援的資料行。
  • orderDirection 是排序結果的順序。 設定為 ASC，以遞增順序排序結果或 DESC，以遞減順序排序結果。 預設值為 ASC。

例如，下列呼叫會依 AverageCpc 以遞增順序傳回廣告。

selector = selector.orderBy("AverageCpc");

選取器僅支援依一個欄位排序實體。 您不能依欄位 x 排序實體清單，也無法依欄位 y 排序 x 中的實體清單，依此類推。 如果您在鏈結或個別選取器呼叫中指定多個呼叫，則腳本會使用上 orderBy() 一個 orderBy() 呼叫中指定的欄位來排序實體清單。 

引數

名稱 類型 說明
orderBy 字串 要套用的順序。

傳回

類型 說明
AdSelector 已套用排序的選取器。

withCondition (字串條件)

將篩選準則套用至廣告。

指定 「columnName 運算子值」 格式 的條件 參數，其中：

運算子

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

支援的資料行

用於篩選廣告的支援資料行。 資料行名稱會區分大小寫。

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

欄位 類型 範例
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")

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

欄位 類型 範例
狀態 枚舉 廣告的狀態。 可能區分大小寫的值為：
  • 啟用
  • 暫停
  • 刪除
此範例只會傳回已啟用的廣告。

withCondition("Status = ENABLED")
類型 枚舉 廣告的衍生類型。 可能區分大小寫的值為：
  • EXPANDED_TEXT_AD
此範例只會傳回展開的文字廣告。

withCondition("Type = EXPANDED_TEXT_AD")
CombinedApprovalStatus 字串 廣告的核准狀態。 可能區分大小寫的值為：
  • 批准
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • 反對
如需這些值的相關資訊，請 參閱編輯核准狀態值。

此範例會傳回需要注意的廣告。

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
CreativeFinalUrls 字串 廣告的最後一個 URL。

withCondition("CreativeFinalUrls CONTAINS_IGNORE_CASE 'contoso.com'")
AdGroupName 字串 廣告所屬的廣告組名。

withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")
AdGroupStatus 枚舉 廣告所屬廣告群組的狀態。 可能區分大小寫的值為：
  • 啟用
  • 暫停
  • 刪除
此範例只會傳回其父代廣告群組已暫停的廣告。

withCondition("AdGroupStatus = PAUSED")
CampaignName 字串 廣告所屬的行銷活動名稱。

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
CampaignStatus 枚舉 廣告所屬行銷活動的狀態。 可能區分大小寫的值為：
  • 啟用
  • 暫停
  • 刪除
此範例只會傳回其父活動已暫停的廣告。

withCondition("CampaignStatus = PAUSED")
LabelNames 字串集 一或多個區分大小寫的標籤名稱清單。 使用 取得與具名標籤相關聯的廣告。

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

withCondition('Id > 1234')

引數

名稱 類型 說明
條件 字串 要套用至選取器的條件。

傳回

類型 說明
AdSelector 已套用條件的選取器。

withIds (string[] ids)

取得具有指定識別碼的廣告。

您可以將一或多個條件套用至選取器。 條件鏈結會被視為 AND 作業。 例如，只有在條件 A 為 true 且條件 B 為 true 時，才會選取實體。 例如，下列呼叫只會選取廣告 33333。

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

引數

名稱 類型 說明
Id string[] 廣告識別碼的陣列。 如需限制，請參閱 腳本執行限制。

傳回

類型 說明
AdSelector 已套用識別碼的選取器。

withLimit (int 限制)

取得符合選取準則的前 n 個廣告。

引數

名稱 類型 說明
限制 int 要傳回的廣告數目。 實際數目可能較少。

傳回

類型 說明
AdSelector 已套用限制的選取器。

另請參閱

AdsApp.ads ()