Limitaciones y prácticas recomendadas

La API de estadísticas de Facebook proporciona datos sobre el rendimiento de las campañas de marketing de Facebook. Para proteger el rendimiento y la estabilidad del sistema, aplicamos medidas de protección que garantizan que los recursos del sistema se distribuyan de manera equitativa entre las apps. Todas las políticas que se describen a continuación están sujetas a cambios.

Límites de datos por llamada

Usamos límites de datos por llamada para evitar que en una sola consulta se recupere una cantidad de datos superior a la que el sistema puede manejar. Hay dos tipos de límites de datos:

1. Por el número de filas en la respuesta
2. Por el número de puntos de datos que se requieren para calcular el total (como la fila de resumen)

Estos límites se aplican a las llamadas /insights tanto sincrónicas como asincrónicas, y se devuelve este error:

error_code = 100,  CodeException (error subcode: 1487534)

Prácticas recomendadas sobre límites de datos por llamada

• Para limitar tu consulta, limita el intervalo de fechas o el número de identificadores de anuncios. También puedes acotar la consulta a las métricas necesarias o desglosarla en varias consultas y solicitar un subconjunto de métricas en cada una.
• Evita realizar consultas del nivel de cuenta que incluyan desgloses con un número elevado de elementos, como action_target_id o product_id, e intervalos de fechas más extensos, por ejemplo, de un largo plazo.
• Usa el perímetro /insights directamente con objetos de anuncio de nivel inferior para obtener datos detallados de ese nivel. Por ejemplo, usa primero una consulta de nivel de cuenta para obtener la lista de los identificadores de objeto de niveles más bajos con los parámetros level y filtering. En este ejemplo, recuperamos la información de todas las campañas que registraron impresiones:

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'

• Después, podemos usar /<campaign_id>/insights con los valores devueltos en relación con la consulta y agrupar por lotes las solicitudes de estadísticas de estas campañas en una sola llamada:

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'

• Usa el parámetro filtering solo para obtener estadísticas de objetos de anuncio con datos. El valor de campo especificado en filtering usa la notación de PUNTO para indicar los campos contenidos en el objeto. Ten en cuenta que el filtrado con STARTS_WITH y CONTAIN no cambia los datos del resumen. En este caso, utiliza el operador IN. Este es un ejemplo de una solicitud 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'

• Si es posible, usa date_preset. Los intervalos de fechas personalizados ofrecen un rendimiento menos eficaz en nuestro sistema.
• Usa las solicitudes por lotes a fin de realizar varias llamadas sincrónicas y asincrónicas para consultar grandes volúmenes de datos y evita exceder los tiempos de espera.
• Cuando las llamadas sincrónicas excedan el tiempo de espera, ejecuta primero las llamadas sincrónicas y después las asincrónicas.
• Las estadísticas se actualizan cada 15 minutos y dejan de cambiar a los 28 días de haberse registrado.

Límites de carga de las llamadas de estadísticas

90 días después del lanzamiento de la versión 3.3 y con efecto en todas las versiones públicas, cambiamos la limitación de frecuencia en el nivel de la cuenta publicitaria para reflejar mejor el volumen de llamadas a la API necesarias. Calculamos el cupo de la limitación de frecuencia en tu nivel de acceso a la API de marketing y la empresa que es dueña de la app. Consulta Acceso y autenticación. Este cambio se aplica a todos los puntos de conexión de la API de estadísticas de anuncios: 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 y POST {ad_ID}/insights.

Usamos límites de carga para ofrecer una experiencia de informes óptima. Medimos tanto la frecuencia de las llamadas de API como los recursos que necesiten. Admitimos un límite de carga fijo por app por segundo. Si se supera ese límite, las solicitudes fallan.

Controla el encabezado de HTTP x-fb-ads-insights-throttle en cada respuesta de la API para ver qué tan cerca de su límite está tu app y para calcular el peso estimado de una consulta concreta. Las llamadas de estadísticas también están sujetas a los límites de la cuenta publicitaria predeterminados que se muestran en el encabezado de HTTP x-ad-account-usage. Puedes obtener más detalles en API de marketing, Prácticas recomendadas

Cuando una app alcanza su límite, la llamada recibe una respuesta de error con error_code = 4, CodedException. Procura mantenerte lejos del límite. Si una app alcanza sus límites permitidos, solo se procesa un porcentaje determinado de solicitudes, dependiendo de la consulta y la frecuencia.

Aplicamos la limitación de frecuencia a cada app que envíe llamadas /insights sincrónicas y asincrónicas combinadas. Los dos límites de parámetros principales se cuentan a efectos de cada app y cada cuenta publicitaria.

Este es un ejemplo de encabezado de HTTP con la puntuación acumulada de una app como porcentaje de los límites:

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

El encabezado "X-FB-Ads-Insights-Throttle" es un valor JSON, que contiene la siguiente información:

• app_id_util_pct: el porcentaje de la capacidad asignada que consumió el app_id asociado.
• acc_id_util_pct: el porcentaje de la capacidad asignada que consumió el account_id del anuncio asociado.
• ads_api_access_tier: los niveles permiten que tu app acceda a la API de marketing. standard_access logra una limitación de frecuencia menor.

Límites de frecuencia globales

Durante los períodos de carga global elevada en el punto de conexión /insights, el sistema puede acelerar las solicitudes con el fin de proteger el backend. Esto puede ocurrir en casos poco habituales, cuando llegan demasiadas consultas de alta complejidad al mismo tiempo (grandes intervalos de tiempo, métricas complejas y/o alto número de identificadores de objetos publicitarios). El error se verá de la siguiente manera:

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

Durante estos períodos, se aconseja reducir las llamadas, esperar un momento y volver a realizar la consulta.

Prácticas recomendadas relativas a los límites de frecuencia

• Si envías varias consultas de manera simultánea, es más probable que se activen nuestras limitaciones de frecuencia. Distribuye las consultas /insights mediante la asignación de una frecuencia con tiempo de espera en tu trabajo.
• Usa la información de la frecuencia en el encabezado de la respuesta HTTP para moderar tus llamadas. Agrega un mecanismo de retracción a fin de disminuir la frecuencia de tus consultas de /insights o de ponerlas en pausa cuando te aproximes al 100% de tu capacidad en tu app o en tu cuenta publicitaria.
• Los datos de las estadísticas de anuncios se informan con la zona horaria de la cuenta publicitaria. Para recuperar datos de estadísticas de la cuenta publicitaria asociada diariamente, usa la zona horaria de la cuenta para determinar la hora del día. Eso permite distribuir las consultas a lo largo del día.
• Revisa el ads_api_access_tier que te permite acceder a la API de marketing. De modo predeterminado, las apps se ubican en el nivel development_access, y el standard_access permite lograr una limitación de frecuencia menor. Para obtener un límite de frecuencia más alto y llegar al nivel estándar, puedes solicitar el "acceso avanzado" a la función Acceso estándar a administración de anuncios.

Trabajos asincrónicos de la API de estadísticas

Busca estadísticas en muchos objetos, filtra los resultados y ordénalos. El flujo de trabajo asincrónico ahora es más sencillo:

1. Envía una solicitud POST al punto de conexión <AD_OBJECT>/insights y responderá con el id para la ejecución del informe publicitario.

{
  "report_run_id": 6023920149050,
}
    

No guardes el report_run_id para usarlo a largo plazo, ya que caducará después de 30 días.

1. Las ejecuciones de los informes publicitarios contienen información sobre este trabajo asincrónico, como async_status. Consulta este campo hasta que async_status sea Job Completed y async_percent_completion sea 100.

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

1. Luego, puedes realizar la consulta al perímetro <AD_REPORT_RUN_ID>/insights para obtener el resultado 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"
    }
  }
}
    

Este trabajo obtiene todas las estadísticas de la cuenta y devuelve un identificador de trabajo asincrónico:

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

Estado del trabajo asincrónico

Exportar los informes

Proporcionamos un práctico extremo para exportar <AD_REPORT_RUN_ID> a un formato localizado y fácil de leer.

Nota: Este extremo no forma parte de nuestra versión de la API Graph y, por lo tanto, no se incluye en la política de cambios radicales. Los scripts y los programas no deben depender del formato del resultado, ya que este puede cambiar sin previo aviso.

  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/'