Seletores

Os seletores ajudam o programador a criar a consulta que busca as entidades solicitadas 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 combinadas com a função AND. Em outras palavras, o seletor só vai retornar entidades que atendam a todas as condições especificadas.
withIds()
Adiciona uma coleção de IDs como uma condição. Uma condição baseada em ID será combinada com todas as outras.
forDateRange()
É necessário quando uma condição ou cláusula de ordenação faz referência a um campo de 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. É particularmente útil em conjunto com orderBy() para buscar itens como "10 palavras-chave com mais impressões ontem". Por padrão, todos os seletores definem o limite como 50.000. Você pode aumentar o limite especificando um valor manualmente.

Esses métodos podem ser chamados em qualquer ordem. Uma exceção é orderBy(), em que a ordem das chamadas é importante: várias chamadas para esse método vão especificar várias cláusulas de ordenação, e elas serão aplicadas em ordem. Considere o snippet a seguir:

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

Os resultados serão classificados por cliques em ordem decrescente. Os resultados com valores de cliques iguais 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 é construído, é possível receber um iterador dele chamando selector.get().

Leia as práticas recomendadas para conferir dicas e truques sobre o uso eficiente de seletores.