次の方法で共有

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
  • 日

例:

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

月は 1 から始まります。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 String セレクターに含めるパフォーマンス データを指定する定義済みの日付範囲文字列。 定義済みの日付範囲文字列では、大文字と小文字が区別されます。

戻り値

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

取得

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

戻り値

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

orderBy(String orderBy)

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

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

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

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

selector = selector.orderBy("AverageCpc");

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

引数

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

戻り値

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

withCondition(String condition)

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

"columnName 演算子値" という形式で condition パラメーターを指定します。

演算子

使用する演算子は、列の型によって異なります。 演算子では大文字と小文字が区別されます。 たとえば、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

サポートされる列

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

指定できるパフォーマンス メトリック列を次に示します。

Column 型 例
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 であるため、5% の CTR には 0.05 を使用します。
インプレッション long withCondition("Impressions > 10")
TopImpressionRate double withCondition("TopImpressionRate > 0.25")

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

Column 型 例
状態 列挙 広告の状態。 大文字と小文字を区別する値は次のとおりです。
  • 有効
  • 一時 停止
  • 削除
この例では、有効な広告のみを返します。

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 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 つ以上の条件を適用できます。 条件のチェーンは 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()