セレクタは、必要な Google 広告エンティティを取得するクエリをプログラマが作成する際に役立ちます。セレクタを使用すると、取得したエンティティのリストを絞り込み、順序を付けることができます。ほとんどのセレクタには、次のようなメソッドがあります。
withCondition()- セレクタに条件を追加します。複数の条件を使用する場合は、それらの条件が AND 演算で結合されます。つまり、セレクタは指定された条件のすべてを満たすエンティティのみを返します。
withIds()- 条件として ID のコレクションを追加します。ID ベースの条件は、他のすべての条件と AND 演算で結合されます。
forDateRange()- 条件または順序句が 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 を基準にして、降順で並べ替えられます。クリック数の値が同じ結果は、クリック率の昇順で並べ替えられます。
セレクタのメソッドの呼び出しは連結できます。次のコードをご覧ください。
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() を呼び出してイテレータを取得できます。
セレクタの効率的な使用に関するヒントとコツについては、ベスト プラクティスをご覧ください。