Seletores

Os seletores ajudam o programador a construir a consulta que coleta as entidades desejadas do Google Ads. Com eles, é possível restringir a lista de entidades recuperadas e classificá-la. A maioria dos seletores usa os seguintes métodos:

withCondition()
Adiciona uma condição a um seletor. Se várias condições forem usadas, elas serão unidas por AND. Em outras palavras, o seletor só vai retornar entidades que satisfizerem todas as condições especificadas.
withIds()
Adiciona uma coleção de IDs como uma condição. Uma condição com base no ID será unida por AND a todas as outras.
forDateRange()
É necessário quando uma condição ou cláusula de ordenação referencia uma Estatísticas, como CTR ou impressões. Se você solicitar todas as campanhas com mais de 100 impressões, os scripts do Google Ads precisarão saber o período a ser analisado.
orderBy()
Especifica a ordem das entidades retornadas.
withLimit()
Limita o número de entidades retornadas ao valor especificado. É é muito útil em conjunto com orderBy() para buscar coisas como "10 palavras-chave com mais impressões ontem". Por padrão, todos os seletores definirá o limite como 50.000. É possível aumentar o limite especificando manualmente um limite.

Esses métodos podem ser chamados em qualquer ordem. Uma exceção é orderBy(), em que a ordem das chamadas realmente importa: várias chamadas a este método especificarão várias cláusulas de ordenação, e elas serão aplicadas em ordem. Considere o fragmento abaixo:

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

Os resultados serão classificados por cliques em ordem decrescente. Resultados com igual Os valores de cliques serão classificados por CTR, em ordem crescente.

As chamadas para os métodos de um seletor podem ser associadas. O código a seguir

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

pode ser reescrito de uma forma mais compacta:

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

Depois que o seletor é criado, é possível extrair um Iterator dele chamando selector.get().

Leia as dicas em Práticas recomendadas e truques sobre o uso eficiente de seletores.