セレクタ

セレクタは、リクエストされた Google 広告エンティティを取得するクエリをプログラマーが構築するのに役立ちます。セレクタを使用すると、取得したエンティティのリストを絞り込み、順序を付けることができます。ほとんどのセレクタには、次のようなメソッドがあります。

withCondition()
セレクタに条件を追加します。複数の条件が使用されている場合、それらは AND 演算で結合されます。つまり、セレクタは、指定されたすべての条件を満たすエンティティのみを返します。
withIds()
ID のコレクションを条件として追加します。ID ベースの条件は、他のすべての条件と AND で結合されます。
forDateRange()
は、条件句または順序句が Ctr や Impressions などの Stats フィールドを参照する場合に必要です。100 回以上のインプレッションが発生したすべてのキャンペーンをリクエストする場合は、Google 広告スクリプトで検索する期間を指定する必要があります。
orderBy()
返されたエンティティの順序を指定します。
withLimit()
返されるエンティティの数を指定された値に制限します。これは、orderBy() と組み合わせて「昨日のインプレッション数が最も多い 10 個のキーワード」などの情報を取得する場合に特に便利です。デフォルトでは、すべてのセレクタで上限が 50,000 に設定されます。上限を手動で指定することで、上限を引き上げることができます。

これらのメソッドは任意の順序で呼び出すことができます。例外は orderBy() です。このメソッドへの複数の呼び出しは複数の順序付け句を指定し、それらは順番に適用されます。次のスニペットを考えてみましょう。

selector = selector.forDateRange("LAST_14_DAYS")
    .orderBy("metrics.clicks DESC")
    .orderBy("metrics.ctr ASC");

この場合、結果は Clicks を基準にして、降順で並べ替えられます。クリック数が同じ結果は、クリック率の昇順で並べ替えられます。

セレクタのメソッドの呼び出しは連鎖させることができます。次のコードをご覧ください。

var campaignSelector = AdsApp.campaigns();
campaignSelector.withCondition("metrics.clicks > 10");
campaignSelector.withCondition("metrics.impressions > 1000");
campaignSelector.orderBy("metrics.impressions DESC");
campaignSelector.forDateRange("YESTERDAY");

は、次のように簡潔に書き直すことができます。

var campaignSelector = AdsApp.campaigns()
  .withCondition("metrics.clicks > 10")
  .withCondition("metrics.impressions > 1000")
  .orderBy("metrics.impressions DESC")
  .forDateRange("YESTERDAY");

セレクタを構築したら、selector.get() を呼び出して Iterator を取得できます。

効率的なセレクタの使用に関するヒントとコツについては、ベスト プラクティスをご覧ください。