包含篩選及排序廣告清單的方法。 如需選取器的相關資訊，請參閱 選取器。
方法
| 方法名稱 | 傳回類型 | 描述 |
|---|---|---|
| forDateRange (Object dateFrom， Object dateTo) | AdSelector | 套用選取效能指標的開始日期和結束日期。 |
| forDateRange (字串 dateRange) | AdSelector | 套用預先定義的日期範圍以選取效能指標。 |
| get | AdIterator | 取得用來逐一查看廣告清單的反覆運算器。 |
| orderBy (字串 orderBy) | AdSelector | 將指定的排序套用至選取的廣告。 |
| withCondition (字串條件) | AdSelector | 將篩選條件套用至廣告。 |
| withIds (string[] ids) | AdSelector | 取得具有指定識別碼的廣告。 |
| withLimit (int limit) | 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 (字串 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 (字串 orderBy)
將指定的排序套用至選取的廣告。
在 “columnName orderDirection” 表單中指定 orderBy 參數，其中：
- columnName 是支援的其中一個 欄位。
- orderDirection 是要針對結果排序的順序。 設定為 ASC 以遞增順序排序結果，或設定為 DESC 以遞減順序排序結果。 預設值為 ASC。
例如，下列呼叫會依 AverageCpc 遞增順序傳回廣告。
selector = selector.orderBy("AverageCpc");
選取器僅支援依一個欄位來排序實體。 您不得依欄位 x、在 x 內依欄位 y 排序實體清單，依此類推。 如果您在鏈結或單獨的選擇器呼叫中指定多個 orderBy() 呼叫，則指令碼會使用上次 orderBy() 呼叫中指定的欄位對實體清單進行排序。
引數
| 名稱 | 類型 | 描述 |
|---|---|---|
| orderBy | 字串 | 要申請的順序。 |
傳回
| 類型 | 描述 |
|---|---|
| AdSelector | 已套用排序的選擇器。 |
withCondition (字串條件)
將篩選條件套用至廣告。
在「columnName operator value」表單中指定 條件 參數，其中：
- columnName 是 支援的資料行之一。 如果 columName 設定為效能計量資料行名稱，您必須使用 forDateRange (字串 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
支援的資料欄位
篩選廣告支援的資料欄位。 欄名稱會區分大小寫。
以下是您可以指定的效能計量資料欄位。
| 欄位 | 類型 | 範例 |
|---|---|---|
| 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")費用以帳戶貨幣表示。 |
| Ctr | double | withCondition("Ctr > 0.05")點選率在 0..1 的範圍內，因此使用 0.05 表示 5% 的點選率。 |
| 閱聽 | long | withCondition("Impressions > 10") |
| TopImpressionRate | double | withCondition("TopImpressionRate > 0.25") |
以下是您可以指定的實體屬性。
| 欄位 | 類型 | 範例 |
|---|---|---|
| 狀態 | 列舉 | 廣告的狀態。 可能會區分大小寫的值如下：
withCondition("Status = ENABLED") |
| 類型 | 列舉 | 廣告的衍生類型。 可能會區分大小寫的值如下：
withCondition("Type = EXPANDED_TEXT_AD") |
| CombinedApprovalStatus | 字串 | 廣告的核准狀態。 可能會區分大小寫的值如下：
此範例會傳回需要注意的廣告。 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 | 要測試的廣告識別碼。 例如，您可以使用此資料欄位檢查是否有 ID 大於指定識別碼的廣告。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]);
引數
| 名稱 | 類型 | 描述 |
|---|---|---|
| IDS | string[] | 廣告識別碼的陣列。 如需限制，請參閱 指令碼執行限制。 |
傳回
| 類型 | 描述 |
|---|---|
| AdSelector | 具有套用識別碼的選擇器。 |
withLimit (int limit)
取得符合選取準則的前 n 個 廣告。
引數
| 名稱 | 類型 | 描述 |
|---|---|---|
| 限制 | int | 要返回的廣告數目。 實際數字可能會更少。 |
傳回
| 類型 | 描述 |
|---|---|
| AdSelector | 已套用限制的選取器。 |