Limites et recommandations

L’API Facebook Insights fournit des données de performance issues des campagnes marketing Facebook. Pour protéger les performances et la stabilité du système, nous avons mis en place des mesures de protection afin de répartir équitablement les ressources du système entre les applications. Toutes les règles que nous décrivons ci-dessous peuvent être modifiées.

Limites applicables aux données par appel

Nous utilisons des limites pour les données des appels pour éviter qu’une requête récupère une trop grande quantité de données, qui dépasserait les capacités de gestion du système. Il existe deux types de limites applicables aux données :

1. par nombre de lignes dans la réponse, et
2. par nombre de points de données requis pour calculer le total, comme pour une ligne de résumé.

Ces limites s’appliquent aux appels /insights synchrones et asynchrones, et une erreur est renvoyée :

error_code = 100,  CodeException (error subcode: 1487534)

Recommandations, limites applicables aux données par appel

• Limitez votre requête en limitant la plage de dates ou le nombre d’ID publicité. Vous pouvez également limiter votre requête aux indicateurs nécessaires, ou la répartir sur plusieurs requêtes demandant chacune un sous-ensemble d’indicateurs.
• Évitez les requêtes au niveau du compte qui incluent des répartitions à cardinalité élevée, comme action_target_id ou product_id, ainsi que des plages de dates plus étendues, comme Depuis création.
• Utilisez l’arête /insights directement avec les objets publicitaires des niveaux inférieurs pour récupérer des données granulaires concernant ce niveau. Par exemple, commencez par utiliser la requête au niveau du compte pour chercher la liste des identifiants d’objet des niveaux inférieurs à l’aide des paramètres level et filtering. Dans cet exemple, nous cherchons toutes les campagnes qui ont enregistré des impressions :

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

• Nous pouvons alors utiliser /<campaign_id>/insights avec chaque valeur renvoyée pour lancer une requête et grouper les requêtes d’insights pour ces campagnes dans un seul appel :

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'

• Utilisez le paramètre filtering uniquement pour récupérer les insights concernant les objets publicitaires avec des données. La valeur de champ précisée dans filtering utilise la notation DOT pour indiquer les champs sous l’objet. Notez que les paramètres de filtrage STARTS_WITH et CONTAIN n’ont aucune incidence sur les données du résumé. Dans ce cas, utilisez l’opérateur IN. Voici un exemple de requête filtering :

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'

• Utilisez date_preset si possible. L’exécution des plages de dates personnalisées est moins efficace dans notre système.
• En cas d’appels synchrones et asynchrones multiples, effectuez des requêtes groupées pour demander un volume important de données et ainsi éviter les délais d’expiration.
• Essayez d’abord des appels synchrones, puis utilisez des appels asynchrones en cas de délai d’expiration des appels synchrones.
• Les insights sont actualisées toutes les 15 minutes et ne sont plus modifiées 28 jours après la génération des rapports.

Limites de charge des appels d'insights

90 jours à partir du lancement de la version 3.3 et une fois disponible pour toutes les versions publiques, nous modifions le plafond au niveau du compte publicitaire pour mieux refléter le nombre d’appels d’API nécessaires. Nous calculons ce plafond en fonction de votre niveau d’accès de l’API Marketing et pour l’entreprise qui possède votre application. Voir Accès et authentification. Cette modification s’appliquera à tous les points de terminaison API Ads Insights : GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights et POST {ad_ID}/insights.

Nous utilisons des limites de charge pour garantir une génération de rapports optimale. Nous mesurons les appels d’API en fonction de leur plafond ainsi que des ressources dont ils ont besoin. Nous autorisons une limite de charge par application, par seconde. Lorsque vous dépassez cette limite, vos requêtes échouent.

Vérifiez l’en-tête HTTP x-fb-ads-insights-throttle de chaque réponse d’API pour voir si votre application est proche de cette limite et pour estimer si une requête en particulier est lourde. Les appels d’insights sont également soumis aux limites par défaut du compte publicitaire affichées dans l’en-tête HTTP x-ad-account-usage. Vous trouverez davantage d’informations ici : API Marketing, Recommandations

Lorsqu’une application atteint sa limite, la réponse de l’appel contient une erreur indiquant error_code = 4, CodedException. Veillez à rester bien en dessous de votre limite. Si votre application atteint sa limite autorisée, seul un certain pourcentage de requêtes aboutit, selon la requête et le plafond.

Nous appliquons un plafond à chaque application qui envoie des appels synchrones et asynchrones /insights combinés. Les deux paramètres pris en compte dans les limites sont Par application et Par compte publicitaire.

Voici un exemple de l’en-tête HTTP contenant un indice accru en pourcentage par rapport aux limites :

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

L’en-tête « x-fb-ads-insights-throttle » est une valeur JSON contenant ces informations :

• app_id_util_pct : pourcentage de capacité allouée que l’app_id associé a consommé.
• acc_id_util_pct : pourcentage de capacité allouée que l’ID de compte publicitaire associé a consommé.
• ads_api_access_tier : les niveaux permettent à votre application d’accéder à l’API Marketing. standard_access autorise un plafond inférieur.

Plafonds globaux

Lorsque la charge du point de terminaison /insights est élevée, le système peut limiter les requêtes pour protéger le serveur backend. Cela peut se produire dans de rares cas lorsqu’un trop grand nombre de requêtes très complexes (plages de dates étendues, indicateurs complexes et/ou nombre élevé d’ID d’objets publicitaires) arrive en même temps. Une erreur similaire à celle-ci est renvoyée :

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

Pendant ces périodes, il est recommandé de réduire les appels, de patienter un instant et de relancer la requête.

Limites et recommandations en matière de plafond

• L’envoi de plusieurs requêtes en une fois est davantage susceptible de déclencher notre plafond. Essayez d’étaler vos requêtes /insights en intercalant des temps d’attente dans votre travail.
• Utilisez les informations de plafond de l’en-tête de la réponse HTTP pour modérer vos appels. Ajoutez un mécanisme de recul pour ralentir ou interrompre vos requêtes /insights lorsque vous approchez 100 % de la capacité pour votre application ou pour votre compte publicitaire.
• Nos rapports d'insights des publicités dépendent du fuseau horaire du compte publicitaire. Pour récupérer des insights pour le compte publicitaire associé au quotidien, prenez en compte l’heure de la journée à l’aide du fuseau horaire du compte. Cela permet de mieux répartir les requêtes tout au long de la journée.
• Vérifiez le niveau ads_api_access_tier qui vous permet d’accéder à l’API Marketing. Par défaut, les applications ont le niveau development_access et standard_access octroie un plafond inférieur. Pour obtenir un plafond supérieur et accéder au niveau standard, demandez un accès Avancé (« Advanced Access ») à la fonctionnalité Accès standard à la gestion des publicités.

Tâches asynchrones de l’API Insights

Récupérez des statistiques sur plusieurs objets et appliquez des filtres ainsi que la fonctionnalité de tri ; nous avons simplifié le processus asynchrone :

1. Envoyez une requête POST au point de terminaison <AD_OBJECT>/insights, qui renvoie l’id d’un rapport publicitaire.

{
  "report_run_id": 6023920149050,
}
    

Ne stockez pas le report_run_id pour l’utiliser sur le long terme, car il expirera après 30 jours.

1. Les rapports publicitaires contiennent des informations concernant cette tâche asynchrone, comme async_status. Interrogez ce champ jusqu’à ce que async_status indique Job Completed et que async_percent_completion affiche la valeur 100.

{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
    

1. Vous pouvez ensuite interroger l’arête <AD_REPORT_RUN_ID>/insights pour récupérer le résultat final.

{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}
    

Cette tâche extrait toutes les statistiques associées au compte et renvoie un ID de tâche asynchrone :

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

Statut de la tâche asynchrone

Exporter des rapports

Nous proposons un point de terminaison pratique pour exporter <AD_REPORT_RUN_ID> dans un format localisé lisible.

Remarque : ce point de terminaison ne fait pas partie de notre API Graph versionnée et n’est donc pas conforme à sa politique en matière de modification avec rupture. Les scripts et programmes ne doivent pas dépendre du format du résultat, car il peut changer inopinément.

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'