セレクタは、プログラマーが目的の 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 を取得できます。
効率的なセレクタの使用に関するヒントやコツについては、ベスト プラクティスをご覧ください。