Especificação de avaliação

O objetivo principal da evaluation_spec de uma regra é determinar os objetos sobre os quais a regra deve executar a ação. O evaluation_type define o tipo de método de avaliação e inclui as seguintes opções:

A evaluation_spec contém uma matriz de filters, o que permite restringir ainda mais a lista de objetos correspondentes. Por exemplo, você pode criar filtros em metadados de anúncios, conjuntos de anúncios e campanhas, assim como em métricas de insights. Todos os filtros são avaliados juntos usando o operador AND.

A matriz de filters contém uma lista de objetos de filtro. Esses objetos são dicionários com chaves de field, value e operator:

Cada filtro tem uma lista de operadores lógicos compatíveis. Estes são os operadores lógicos aceitos em regras SCHEDULE e TRIGGER:

A evaluation_spec requer um trigger para o tipo de avaliação TRIGGER. O gatilho contém um tipo e uma especificação de filtro subjacente. A especificação de filtro pode ser field, value e operator.

O gatilho determina dinamicamente se devemos ou não avaliar uma regra, e você pode ter apenas uma opção. Leia sobre as regras baseadas em gatilho para obter mais informações.

Abaixo, definimos alguns filtros especiais e grupos gerais que você pode usar.

Filtros especiais

time_preset

O filtro time_preset determina o período de tempo sobre o qual agregamos métricas de insights. No momento, apenas uma time_preset é permitida. Ela é aplicada a todos os filtros de estatísticas na regra, incluindo aquele usado para o gatilho, se for o caso.

O único operador aceito para time_preset é EQUAL, e ele será necessário enquanto houver um gatilho ou um filtro de insights presente. As regras baseadas em gatilho são compatíveis apenas com as predefinições de tempo que incluem TODAY porque a avaliação é executada em tempo real.

As predefinições de tempo para regras podem se comportar de maneira diferente de outras interfaces. Algumas das predefinições de tempo aqui incluem os dados de hoje. Isso ocorre porque os dados atuais são essenciais para regras executadas com uma frequência maior do que diariamente. Para outras interfaces, um valor predefinido de LAST_N_DAYS geralmente não inclui dados de hoje. Veja as descrições abaixo para obter mais detalhes.

{
  "field": "time_preset",
  "value": "TODAY",
  "operator": "EQUAL"
}

attribution_window

O filtro attribution_window determina a janela de lookback sobre a qual as métricas de insights são agregadas. Para obter mais informações, veja a documentação de insights sobre janelas de atribuição.

No momento, só é possível usar uma attribution_window, e ela será aplicada a todos os filtros de estatísticas na regra. O único operador aceito para attribution_window é EQUAL, e ele só é compatível com regras baseadas em programação.

Especificado ou não, o único value permitido para a attribution_window é ACCOUNT_DEFAULT.

{
  "field": "attribution_window",
  "value": "ACCOUNT_DEFAULT",
  "operator": "EQUAL"
}

Filtros de metadados

Com os filtros de metadados, você pode filtrar objetos com base no estado atual dos respectivos campos de metadados. Eles também são compatíveis com a filtragem multinível, o que significa que você pode usar prefixos para aplicar um filtro de metadados em um objeto "parent" ou "grandparent". Isso não afeta outros filtros. Os filtros de insights ainda se aplicam ao objeto normal.

Por exemplo, se você quiser usar uma regra que se aplique a conjuntos de anúncios de campanhas cujo objetivo seja WEBSITE_CLICKS, será possível incluir dois filtros:

 "filters" : [
  {
    "field": "entity_type",
    "value": "ADSET",
    "operator": "EQUAL",
  },
  {
    "field": "campaign.objective",
    "value": "WEBSITE_CLICKS",
    "operator": "EQUAL"
  }
]

Filtros de metadados compatíveis com regras baseadas em programação e gatilho

Filtros de metadados compatíveis apenas com regras baseadas em programação

entity_type e id

Para cada tipo de avaliação de SCHEDULE ou TRIGGER, você deve especificar um filtro entity_type ou id.

Ao especificar um filtro entity_type, você determina um nível de objeto dinâmico ao qual aplicar a regra. Por exemplo, se o entity_type for AD, essa regra avaliará automaticamente cada novo anúncio adicionado à conta de anúncios. Isso acontece independentemente de quando você cria a regra. Com a especificação de um filtro id, a regra só será aplicada a uma lista estática de objetos.

Quando você especifica um filtro idsem prefixo, calculamos automaticamente o nível do objeto ao qual aplicar a regra. Por exemplo, se você quiser aplicar uma regra a anúncios [123, 456], só será necessário um campo de filtro id, valor [123, 456] e operador IN. Nesse caso, entity_type não é obrigatório, já que você forneceu uma lista estática inicial de objetos e podemos calcular o nível do objeto a partir desses objetos.

É possível usar entity_type e id com a filtragem multinível. Por exemplo, se você quiser uma regra que se aplique a todos os anúncios de conjuntos de anúncios específicos, será possível usar um filtro entity_type de AD e um filtro adset.id com os conjuntos especificados.

Por padrão, quando um filtro effective_status não é especificado, adicionamos implicitamente um filtro effective_status ao avaliamos a regra.

Para todos os tipos de execução que atuam sobre objetos ativos, esse filtro-padrão possui um operador de IN e um valor de ['ACTIVE', 'PENDING_REVIEW']. Isso significa que a regra avalia apenas objetos que têm ou terão veiculação ativa. Para tipos de execução que não atuam em objetos ativos (UNPAUSE), adicionamos o filtro com um operador de NOT_IN e um valor de ['DELETED', 'ARCHIVED']. O filtro-padrão é uma otimização interna para nossos tipos de execução.

Filtros de insights

Avaliamos os filtros de insights em relação aos valores atuais retornados pela API de Insights para uma determinada time_preset. Esses filtros se aplicam diretamente à lista ou ao nível de objetos e não são compatíveis com a filtragem multinível. Todos os filtros de insights são compatíveis com os seguintes operadores: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE.

Para obter uma descrição de cada um dos campos abaixo, consulte a documentação sobre a API de Insights. Todos os filtros mencionados são compatíveis com as regras baseadas em programação.

Veja uma lista de filtros de insights e confira se eles são compatíveis com as regras baseadas em gatilho:

Filtros avançados

Você pode personalizar e derivar campos avançados com base nos filtros de insights e metadados acima. Para obter mais informações, leia sobre os filtros avançados da especificação de avaliação.

Os filtros avançados aceitam estes operadores: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE. Eles são compatíveis apenas com regras baseadas em programação.

Para alguns dos filtros avançados mais usados, aceitamos um alias como o filtro: