セレクタ

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

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

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

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

この場合、結果は Clicks を基準にして、降順で並べ替えられます。Clicks 値が等しい結果は、Ctr によって昇順で並べ替えられます。

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

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 を取得できます。

セレクタを効率的に使用するためのヒントについては、おすすめの方法をご覧ください。