Compartilhar via

AdSelector

  • Artigo

Contém os métodos para filtrar e ordenar uma lista de anúncios. Para obter informações sobre seletores, consulte Seletores.

Métodos

Nome do Método Tipo de Devolução Descrição
forDateRange(Data do objetoA partir de, Data do objetoTo) AdSelector Aplica as datas de início e de fim para selecionar métricas de desempenho.
forDateRange(string dateRange) AdSelector Aplica o intervalo de datas predefinido para selecionar métricas de desempenho.
obter AdIterator Obtém um iterador utilizado para iterar através da lista de anúncios.
orderBy(string orderBy) AdSelector Aplica a ordenação especificada aos anúncios selecionados.
withCondition(condição de cadeia) AdSelector Aplica critérios de filtro aos anúncios.
withIds(string[] ids) AdSelector Obtém anúncios com os IDs especificados.
withLimit(int limit) AdSelector Obtém os n principais anúncios que correspondem aos critérios de seleção.

forDateRange(Data do objetoA partir de, Data do objetoTo)

Aplica as datas de início e de fim para selecionar métricas de desempenho.

Especifique um intervalo de datas apenas se:

  • Aplica condições ou ordenação que referenciam campos de métricas de desempenho.
  • Quer obter dados de desempenho para os objetos que está a selecionar. Por exemplo, se planear chamar o getStats() método .

Pode especificar os parâmetros de data com cadeias ou objetos. Para utilizar cadeias, especifique a data no formulário YYYYMMDD. Se utilizar objetos, crie um objeto com os seguintes campos:

  • ano
  • mês
  • dia

Por exemplo:

var date = {year: 2018, month: 5, day: 13};

O mês é baseado num, em que 1 é janeiro e 12 é dezembro.

O intervalo de datas é inclusivo. Se especificar vários intervalos de datas, só é utilizado o último intervalo de datas.

Argumentos

Name Tipo Descrição
dateFrom Objeto A data de início do intervalo de datas que especifica os dados de desempenho a incluir no seletor.
dateTo Objeto A data de fim do intervalo de datas que especifica os dados de desempenho a incluir no seletor.

Devoluções

Tipo Descrição
AdSelector Seletor com intervalo de datas aplicado.

forDateRange(String dateRange)

Aplica o intervalo de datas predefinido para selecionar métricas de desempenho.

Especifique um intervalo de datas apenas se:

  • Aplica condições ou ordenação que referenciam campos de métricas de desempenho.
  • Quer obter dados de desempenho para os objetos que está a selecionar. Por exemplo, se planear chamar o getStats() método .

Se especificar vários intervalos de datas, só é utilizado o último intervalo de datas.

Valores de intervalo de datas suportados:

  • HOJE
  • ONTEM
  • LAST_WEEK
  • LAST_BUSINESS_WEEK
  • LAST_7_DAYS
  • THIS_WEEK_SUN_TODAY
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_WEEK_SUN_SAT
  • THIS_MONTH
  • LAST_MONTH
  • ALL_TIME

Argumentos

Name Tipo Descrição
dateRange Cadeia A cadeia de intervalo de datas predefinida que especifica os dados de desempenho a incluir no seletor. A cadeia de intervalo de datas predefinida é sensível às maiúsculas e minúsculas.

Devoluções

Tipo Descrição
AdSelector Seletor com intervalo de datas aplicado.

obter

Obtém um iterador utilizado para iterar através da lista de anúncios.

Devoluções

Tipo Descrição
AdIterator Um iterador utilizado para iterar através dos anúncios selecionados.

orderBy(String orderBy)

Aplica a ordenação especificada aos anúncios selecionados.

Especifique o parâmetro orderBy no formulário "columnName orderDirection" em que:

  • columnName é uma das colunas suportadas.
  • orderDirection é a ordem para ordenar os resultados. Defina como ASC para ordenar os resultados por ordem ascendente ou DESC para ordenar os resultados por ordem descendente. A predefinição é ASC.

Por exemplo, a chamada seguinte devolve anúncios por ordem ascendente por AverageCpc.

selector = selector.orderBy("AverageCpc");

Os seletores suportam a ordenação de entidades apenas por um campo. Não pode ordenar a lista de entidades por campo x e dentro de x por campo y, etc. Se especificar mais do que uma orderBy() chamada numa cadeia ou em chamadas de seletor separadas, os scripts ordenam a lista de entidades utilizando o campo especificado na última orderBy() chamada. 

Argumentos

Name Tipo Descrição
orderBy cadeia A ordenação a aplicar.

Devoluções

Tipo Descrição
AdSelector Seletor com ordenação aplicada.

withCondition(Condição de cadeia)

Aplica critérios de filtro aos anúncios.

Especifique o parâmetro condition no formulário "columnName operator value" em que:

Operadores

O operador que utilizar depende do tipo da coluna. Os operadores são sensíveis às maiúsculas e minúsculas. Por exemplo, utilize STARTS_WITH em vez de starts_with.

Operadores para colunas que contêm números inteiros e valores longos:

<
<=
>
>=
=
!=

Operadores para colunas que contêm valores duplos:

<
>

Operadores para colunas que contêm valores de cadeia:

=
!=
STARTS_WITH
STARTS_WITH_IGNORE_CASE
CONTAINS
CONTAINS_IGNORE_CASE
DOES_NOT_CONTAIN
DOES_NOT_CONTAIN_IGNORE_CASE

Operadores para colunas que contêm valores de enumeração:

=
!=
IN []
NOT_IN []

Operadores para colunas que contêm uma matriz de cadeias:

CONTAINS_ALL
CONTAINS_ANY
CONTAINS_NONE

Colunas Suportadas

Colunas suportadas para filtrar anúncios. Os nomes das colunas são sensíveis às maiúsculas e minúsculas.

Seguem-se as colunas de métricas de desempenho que pode especificar.

Coluna Tipo Exemplos:
AbsoluteTopImpressionRate duplo withCondition("AbsoluteTopImpressionRate > 0.25")
AverageCpc duplo withCondition("AverageCpc < 2.75")
AverageCpm duplo withCondition("AverageCpm > 0.65")
ClickConversionRate duplo withCondition("ClickConversionRate > 0.25")
Cliques long withCondition("Clicks >= 33")
ConvertClicks long withCondition("ConvertedClicks >= 10")
Custo duplo withCondition("Cost > 3.25")

O custo está na moeda da conta.
Ctr duplo withCondition("Ctr > 0.05")

O CTR está no intervalo 0..1, por isso, utilize 0,05 para um CTR de 5%.
Impressões long withCondition("Impressions > 10")
TopImpressionRate duplo withCondition("TopImpressionRate > 0.25")

Seguem-se as propriedades da entidade que pode especificar.

Coluna Tipo Exemplos:
Estado enumeração O estado do anúncio. Os possíveis valores sensíveis às maiúsculas e minúsculas são:
  • ATIVADO
  • EM PAUSA
  • REMOVIDO
Este exemplo devolve apenas anúncios ativados.

withCondition("Status = ENABLED")
Tipo enumeração O tipo derivado do anúncio. Os possíveis valores sensíveis às maiúsculas e minúsculas são:
  • EXPANDED_TEXT_AD
Este exemplo devolve apenas anúncios de texto expandidos.

withCondition("Type = EXPANDED_TEXT_AD")
CombinedApprovalStatus cadeia O estado de aprovação do anúncio. Os possíveis valores sensíveis às maiúsculas e minúsculas são:
  • APROVADO
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • REPROVADO
Para obter informações sobre estes valores, veja Valores de estado de aprovação editorial.

Este exemplo devolve anúncios que precisam de atenção.

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
CreativeFinalUrls cadeia O URL final do anúncio.

withCondition("CreativeFinalUrls CONTAINS_IGNORE_CASE 'contoso.com'")
AdGroupName cadeia O nome do grupo de anúncios ao qual os anúncios pertencem.

withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")
AdGroupStatus enumeração O estado do grupo de anúncios ao qual os anúncios pertencem. Os possíveis valores sensíveis às maiúsculas e minúsculas são:
  • ATIVADO
  • EM PAUSA
  • REMOVIDO
Este exemplo devolve apenas anúncios cujo grupo de anúncios principal está em pausa.

withCondition("AdGroupStatus = PAUSED")
CampaignName cadeia O nome da campanha à qual os anúncios pertencem.

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
CampaignStatus enumeração O estado da campanha a que os anúncios pertencem. Os possíveis valores sensíveis às maiúsculas e minúsculas são:
  • ATIVADO
  • EM PAUSA
  • REMOVIDO
Este exemplo devolve apenas anúncios cuja campanha principal está em pausa.

withCondition("CampaignStatus = PAUSED")
Nomes de Etiqueta conjunto de cadeias Uma lista de um ou mais nomes de etiquetas sensíveis às maiúsculas e minúsculas. Utilize para obter anúncios associados às etiquetas nomeadas.

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
ID Longo O ID do anúncio a testar. Por exemplo, pode utilizar esta coluna para verificar a existência de anúncios com IDs superiores ao ID especificado.

withCondition('Id > 1234')

Argumentos

Name Tipo Descrição
condição cadeia A condição a aplicar ao seletor.

Devoluções

Tipo Descrição
AdSelector Seletor com a condição aplicada.

withIds(string[] ids)

Obtém anúncios com os IDs especificados.

Pode aplicar uma ou mais condições a um seletor. Uma cadeia de condições é considerada uma operação E. Por exemplo, a entidade só é selecionada se a condição A for verdadeira E a condição B for verdadeira. Por exemplo, a chamada seguinte seleciona apenas o anúncio 33333.

var selector = AdsApp.ads()
    .withIds([11111, 22222, 33333])
    .withIds([33333, 44444, 55555]);

Argumentos

Name Tipo Descrição
IDs cadeia[] Uma matriz de IDs de anúncios. Para obter limites, veja Limites de execução de scripts.

Devoluções

Tipo Descrição
AdSelector Seletor com os IDs aplicados.

withLimit(int limit)

Obtém os n principais anúncios que correspondem aos critérios de seleção.

Argumentos

Name Tipo Descrição
limite int O número de anúncios a devolver. O número real pode ser menor.

Devoluções

Tipo Descrição
AdSelector Seletor com limite aplicado.

Consulte também

AdsApp.ads()