AdSelector

広告のリストをフィルタリングおよび並べ替えるメソッドが含まれています。 セレクターの詳細については、「 セレクター」を参照してください。

メソッド

メソッド名 戻り値の型 説明
forDateRange(Object dateFrom, Object dateTo) AdSelector パフォーマンス メトリックを選択するために開始日と終了日を適用します。
forDateRange(string dateRange) AdSelector パフォーマンス メトリックを選択するために定義済みの日付範囲を適用します。
get AdIterator 広告の一覧を反復処理するために使用される反復子を取得します。
orderBy(string, orderBy) AdSelector 選択した広告に指定した順序を適用します。
withCondition(string condition) AdSelector フィルター条件を広告に適用します。
withIds(string[], ids) AdSelector 指定した ID の広告を取得します。
withLimit(int limit) AdSelector 選択条件に一致する上位 n 個 の広告を取得します。

forDateRange(Object dateFrom, Object dateTo)

パフォーマンス メトリックを選択するために開始日と終了日を適用します。

以下の場合にのみ日付範囲を指定します。

  • パフォーマンス メトリック フィールドを参照する条件または順序を適用します。
  • 選択しているオブジェクトのパフォーマンス データを取得したい場合。 たとえば、 getStats() メソッドを呼び出す予定の場合などです。

日付パラメータは、文字列またはオブジェクトを使用して指定できます。 文字列を使用するには、YYYYMMDD というフォームで日付を指定します。 オブジェクトを使用する場合は、次のフィールドを持つオブジェクトを作成します。

  • year
  • month
  • day

例:

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

月は 1 ベースで、1 は 1 月、12 は 12 月です。

日付範囲は両端を含む。 複数の日付範囲を指定した場合は、最後の日付範囲のみが使用されます。

引数

名前 型 説明
dateFrom オブジェクト セレクターに含めるパフォーマンス データを指定する日付範囲の開始日。
dateTo オブジェクト セレクターに含めるパフォーマンス データを指定する日付範囲の終了日。

戻り値

型 説明
AdSelector 日付範囲が適用されたセレクター。

forDateRange(String dateRange)

パフォーマンス メトリックを選択するために定義済みの日付範囲を適用します。

以下の場合にのみ日付範囲を指定します。

  • パフォーマンス メトリック フィールドを参照する条件または順序を適用します。
  • 選択しているオブジェクトのパフォーマンス データを取得したい場合。 たとえば、 getStats() メソッドを呼び出す予定の場合などです。

複数の日付範囲を指定した場合は、最後の日付範囲のみが使用されます。

サポートされている日付範囲の値:

  • 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

引数

名前 型 説明
dateRange 文字列 セレクターに含めるパフォーマンス データを指定する定義済みの日付範囲文字列。 定義済みの日付範囲文字列では、大文字と小文字が区別されます。

戻り値

型 説明
AdSelector 日付範囲が適用されたセレクター。

get

広告の一覧を反復処理するために使用される 反復子 を取得します。

戻り値

型 説明
AdIterator 選択した広告を反復処理するために使用される反復子。

orderBy(String orderBy)

選択した広告に指定した順序を適用します。

orderBy パラメーターを "columnName orderDirection" の形式で指定します。

  • columnName は 、サポートされている列の 1 つです。
  • orderDirection は、結果を並べ替える順序です。 結果を昇順で並べ替える場合は ASC に設定し、結果を降順で並べ替える場合は DESC に設定します。 既定値は ASC です。

たとえば、次の呼び出しは AverageCpc の昇順で広告を返します。

selector = selector.orderBy("AverageCpc");

セレクターは、1 つのフィールドによるエンティティの順序付けのみをサポートします。 エンティティのリストは、フィールド x で並べ替えることはできません。x 内ではフィールド y で並べ替えるというようにもできません。 チェーンまたは個別のセレクター呼び出しで複数の orderBy() 呼び出しを指定した場合、スクリプトは最後の orderBy() 呼び出しで指定されたフィールドを使用してエンティティのリストを並べ替えます。 

引数

名前 型 説明
orderBy string 適用する順序。

戻り値

型 説明
AdSelector 順序が適用されたセレクター。

withCondition(String condition)

フィルター条件を広告に適用します。

条件パラメーターを "columnName operator value" の形式で指定します。

演算子

使用する演算子は、列の型によって異なります。 演算子では大文字と小文字が区別されます。 たとえば、starts_with の代わりに STARTS_WITH を使用します。

整数値と long 値を含む列の演算子:

<
<=
>
>=
=
!=

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

サポートされている列

広告のフィルタリングでサポートされている列。 列名は大文字と小文字を区別します。

指定可能なパフォーマンス メトリック列を次に示します。

列 型 例
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")

CTR は 0..1 の範囲なので、CTR が 5% の場合は 0.05 を使用します。
インプレッション long withCondition("Impressions > 10")
TopImpressionRate double withCondition("TopImpressionRate > 0.25")

指定できるエンティティ プロパティを次に示します。

列 型 例
状態 列挙型 広告のステータス。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
この例では、有効な広告のみが返されます。

withCondition("Status = ENABLED")
型 列挙型 広告の派生タイプ。 大文字と小文字を区別できる値は次のとおりです。
  • EXPANDED_TEXT_AD
この例では、拡張テキスト広告のみが返されます。

withCondition("Type = EXPANDED_TEXT_AD")
CombinedApprovalStatus string 広告の承認ステータス。 大文字と小文字を区別できる値は次のとおりです。
  • APPROVED
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • 不承認
これらの値の詳細については、「 編集承認状態の値」を参照してください。

この例では、注目が必要な広告が返されます。

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
CreativeFinalUrls string 広告の最終ページ URL。

withCondition("CreativeFinalUrls CONTAINS_IGNORE_CASE 'contoso.com'")
AdGroupName string 広告が属する広告グループの名前。

withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")
AdGroupStatus 列挙型 広告が属する広告グループのステータス。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
この例では、親広告グループが一時停止されている広告のみを返します。

withCondition("AdGroupStatus = PAUSED")
CampaignName string 広告が属するキャンペーンの名前。

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
CampaignStatus 列挙型 広告が属するキャンペーンの状態。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
この例では、親キャンペーンが一時停止されている広告のみを返します。

withCondition("CampaignStatus = PAUSED")
LabelNames 文字列セット 大文字と小文字が区別される 1 つ以上のラベル名の一覧。 名前付きラベルに関連付けられている広告を取得するために使用します。

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
ID Long テストする広告の ID。 たとえば、この列を使用して、指定した ID より大きい ID の広告をチェックできます。

withCondition('Id > 1234')

引数

名前 型 説明
condition string セレクターに適用する条件。

戻り値

型 説明
AdSelector 条件が適用されたセレクター。

withIds(string[], ids)

指定した ID の広告を取得します。

1 つのセレクターに 1 つ以上の条件を適用できます。 条件のチェーンは、AND 演算と見なされます。 たとえば、条件 A が True かつ条件 B が True の場合にのみエンティティが選択されます。 たとえば、次の呼び出しでは広告 33333 のみが選択されます。

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

引数

名前 型 説明
ids string[] 広告 ID の配列。 制限については、「 スクリプト実行制限」を参照してください。

戻り値

型 説明
AdSelector ID が適用されたセレクター。

withLimit(int limit)

選択条件に一致する上位 n 個 の広告を取得します。

引数

名前 型 説明
limit int 返される広告の数。 実際の数は少ない場合があります。

戻り値

型 説明
AdSelector 制限が適用されたセレクター。

関連項目

AdsApp.ads()

  • Last updated on