Spécification d’évaluation

L’objectif principal de la valeur evaluation_spec d’une règle est de déterminer les objets auxquels la règle doit appliquer l’action qu’elle définit. La valeur evaluation_type détermine le type de méthode d’évaluation. Les options suivantes sont disponibles :

La valeur evaluation_spec contient un tableau filters, qui vous permet d’affiner davantage la liste des objets correspondants. Par exemple, vous pouvez élaborer des filtres portant sur des métadonnées de publicité, d’ensemble de publicités et de campagne publicitaire, ainsi que sur des indicateurs relatifs aux statistiques. Tous les filtres sont évalués ensemble à l’aide de l’opérateur AND.

Le tableau filters contient la liste des objets de filtrage. Ces objets sont des dictionnaires comportant les clés field, value et operator :

Chaque filtre est associé à une liste d’opérateurs logiques pris en charge. Voici les opérateurs logiques pris en charge dans les règles SCHEDULE et TRIGGER :

La valeur evaluation_spec requiert un déclencheur (trigger) pour le type d’évaluation TRIGGER. Le déclencheur contient un type et une spécification de filtre sous-jacente. La spécification de filtre peut être field, value et operator.

Le déclencheur détermine de manière dynamique si une règle doit être évaluée ou non. Il ne peut en exister qu’un. Reportez-vous à Règles avec déclencheur pour en savoir plus.

Nous définissons ci-après quelques filtres spéciaux et groupes généraux de filtres que vous pouvez utiliser.

Filtres spéciaux

time_preset

Le filtre time_preset détermine la période pour laquelle des indicateurs relatifs aux statistiques sont agrégés. À l’heure actuelle, nous n’autorisons qu’une seule valeur time_preset. Elle s’applique à tous les filtres de statistiques de la règle, y compris celui utilisé pour le déclencheur, le cas échéant.

Le seul opérateur pris en charge pour time_preset est EQUAL. Il est obligatoire tant qu’un déclencheur ou un filtre statistique est présent. Les règles avec déclencheur ne prennent en charge que les préréglages de temps qui incluent TODAY car une évaluation en temps réel est effectuée.

Les préréglages de temps des règles peuvent présenter un comportement différent dans d’autres interfaces. Certains préréglages de temps figurant ici incluent les données du jour. En effet, les données du jour sont cruciales pour les règles exécutées plus d’une fois par jour. Dans les autres interfaces, la valeur de préréglage LAST_N_DAYS n’inclut généralement pas les données du jour. Vous trouverez plus de détails à ce sujet dans les descriptions ci-après.

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

attribution_window

Le filtre attribution_window détermine la fenêtre d’observation pour laquelle agréger des indicateurs relatif aux statistiques. Pour en savoir plus, consultez la documentation Insights relative aux fenêtres d’attribution.

À l’heure actuelle, nous n’autorisons qu’une seule valeur attribution_window. Elle s’applique à tous les filtres de statistiques de la règle. Le seul opérateur pris en charge pour attribution_window est EQUAL. Il est uniquement pris en charge par les règles avec calendrier.

Qu’il soit indiqué ou pas, la seule valeur (value) autorisée pour attribution_window est ACCOUNT_DEFAULT.

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

Filtres de métadonnées

Avec les filtres de métadonnées, vous pouvez filtrer les objets en fonction de l’état actuel des champs de métadonnées correspondants. De plus, ces filtres prennent en charge le filtrage à plusieurs niveaux. Autrement dit, vous pouvez utiliser des préfixes pour appliquer un filtre de métadonnées au parent ou au grand-parent d’un objet. Cette opération n’affecte pas les autres filtres. Les filtres statistiques continuent à s’appliquer à l’objet standard.

Par exemple, si vous souhaitez définir une règle qui s’applique aux ensembles de publicités de campagnes dont l’objectif est WEBSITE_CLICKS, vous pouvez inclure deux filtres :

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

Filtres de métadonnées pris en charge par les règles avec déclencheur et avec calendrier

Filtres de métadonnées pris en charge uniquement par les règles avec calendrier

entity_type et id

Pour chaque règle dont le type d’évaluation est SCHEDULE ou TRIGGER, vous devez indiquer un filtre entity_type ou id.

Lorsque vous indiquez un filtre entity_type, vous déterminez un niveau d’objet dynamique auquel appliquer la règle. Par exemple, si entity_type est défini sur AD, la règle évalue automatiquement chaque nouvelle publicité ajoutée au compte publicitaire. Le moment auquel la règle est créée n’a pas d’impact. Si vous indiquez un filtre id, la règle s’applique uniquement à une liste statique d’objets.

Lorsque vous indiquez un filtre idsans préfixe, nous déterminons automatiquement le niveau d’objet auquel appliquer la règle. Par exemple, si vous voulez appliquer une règle aux publicités [123, 456], vous avez besoin d’un seul champ de filtre id, de la valeur [123, 456] et de l’opérateur IN. entity_type n’est ici pas nécessaire. En effet, vous avez déjà fourni une liste statique d’objets, qui permet de déterminer le niveau d’objet.

Vous pouvez utiliser entity_type et id en association avec le filtrage à plusieurs niveaux. Par exemple, si vous voulez une règle qui s’applique à toutes les publicités appartenant à des ensembles de publicités donnés, vous pouvez définir un filtre entity_type sur AD et un filtre adset.id avec les ensembles de publicités voulus.

Par défaut, si vous n’indiquez pas de filtre effective_status, nous ajoutons implicitement un filtre effective_status lors de l’évaluation de la règle.

Dans le cas des types d’exécution agissant sur des objets actifs, le filtre par défaut comporte l’opérateur IN et la valeur ['ACTIVE', 'PENDING_REVIEW']. Cela signifie que la règle évalue uniquement les objets dont la diffusion est ou sera active. Dans le cas des types d’exécution n’agissant pas sur des objets actifs (UNPAUSE), le filtre est ajouté avec l’opérateur NOT_IN et la valeur ['DELETED', 'ARCHIVED']. Le filtre par défaut est une optimisation interne pour nos types d’exécution.

Filtres statistiques

Nous évaluons les filtres statistiques par rapport aux valeurs actuelles renvoyées par l’API Insights pour un préréglage de temps (time_preset) donné. Ces filtres s’appliquent directement à la liste ou au niveau des objets. Ils ne prennent pas en charge le filtrage à plusieurs niveaux. Tous les filtres statistiques prennent en charge les opérateurs suivants : GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE.

Pour avoir accès à une description de chacun des champs ci-après, consultez les documents API Insights. Tous ces filtres sont pris en charge par les règles avec calendrier.

Vous trouverez ci-dessous la liste des filtres statistiques et l’indication de leur prise en charge ou non par les règles avec déclencheur :

Filtres avancés

Vous pouvez vous appuyer sur les filtres statistiques et de métadonnées ci-avant pour personnaliser et dériver des champs avancés. Pour en savoir plus, consultez la section relative aux filtres de spécification d’évaluation avancés.

Les filtres avancés prennent en charge les opérateurs suivants : GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE. Ils sont uniquement pris en charge par les règles avec calendrier.

Pour certains des filtres avancés les plus couramment utilisés, nous prenons en charge un alias en tant que filtre :