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 um conjunto de IDs como uma condição. Uma condição baseada em ID será combinada com todas as outras.
forDateRange()
É necessário quando uma cláusula de condição ou 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. É 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 para esse método especificam várias cláusulas de ordenação, e elas sã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. Os resultados com valores de cliques iguais serão ordenados 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 práticas recomendadas para conferir dicas e truques sobre o uso eficiente de seletores.