イテレータ

イテレータは一般的なプログラミング パターンの一種で、次のような状況でオブジェクトのリストを順次処理する場合に使用します。

• 処理開始時にリストのサイズがわからない可能性がある。
• リスト全体を一度にメモリに読み込むと、リソースを消費しすぎる可能性がある。

イテレータは、boolean hasNext() と Object next() の 2 種類のメソッドを利用します。 AdWords スクリプトは AdWords エンティティの取得にイテレータ型のパターンを使用します。

イテレータは機能面では通常の配列とあまり変わりませんが、コードを簡潔にするのに役立つことがあります。次の例は、配列を順次処理するコードです。

for (var i = 0; i < myArray.length; i++) {
  var myObject = myArray[i];
}

これを、イテレータを順次処理する次のコードと比較してみましょう。

while (myIterator.hasNext()) {
  var myObject = myIterator.next();
}

次のコードは、アカウント内のすべてのキャンペーンを対象にイテレータを使用している例です。

var campaignIterator = AdWordsApp.campaigns().get();

while (campaignIterator.hasNext()) {
  var campaign = campaignIterator.next();
  Logger.log(campaign.getName() +
      "; active? " + campaign.isEnabled() +
      "; budget=" + campaign.getBudget());
}

AdWords スクリプトでは、エンティティ イテレータによるエンティティの取得は、最初の 50,000 件までに制限されることがよくあります（詳しくは制限事項をご覧ください）。ただし、iterator.totalNumEntities() を呼び出すことで、イテレータが本来取得するはずだったエンティティの総数を確認することは可能です。この方法は作業を分割する場合に便利です。次に例を示します。

var keywords = campaign.keywords()
    .withCondition("Ctr > 0.01")
    .forDateRange("YESTERDAY")
    .get();
// Did we fetch more keywords than we can handle?
if (keywords.totalNumEntities() > 50000) {
    // Adjust the condition to fetch fewer keywords.
    keywords = campaign.keywords()
      .withCondition("Ctr > 0.015")
      .forDateRange("YESTERDAY")
      .get();
}

セレクタに withLimit() を適用しても、totalNumEntities() の値は変化しません。次のスニペットで、x と y は同じ値になります。

var x = AdWordsApp.keywords().get().totalNumEntities();
var y = AdWordsApp.keywords().withLimit(5).get().totalNumEntities();

AdWords エンティティのイテレータを取得するには、あらかじめセレクタを構築する必要があります。