Límites y prácticas recomendadas

Gracias la API de insights de Facebook, se pueden obtener datos sobre el rendimiento de las campañas de marketing de la plataforma. A fin de proteger el rendimiento y la estabilidad del sistema, disponemos de medidas de protección para distribuir los recursos del sistema de forma equitativa entre las aplicaciones. Todas las políticas que se describen a continuación están sujetas a cambios.

Límites de datos por llamada

Utilizamos los límites de datos por llamada para evitar que una consulta recupere demasiados datos (más de los que el sistema sea capaz de gestionar). Hay dos tipos de límites de datos:

1. en función del número de filas en la respuesta,
2. en función de los puntos de datos necesarios para calcular el total, como en el caso de una fila de resumen.

Estos límites se aplican tanto a las llamadas de /insights síncronas como asíncronas, y se devuelve un error:

error_code = 100,  CodeException (error subcode: 1487534)

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

• Reduce el intervalo de fechas o el número de identificadores de anuncio para limitar la consulta. También puedes limitar la consulta únicamente a los resultados que necesites o desglosarla en varias consultas que soliciten un subconjunto de resultados.
• Evita las consultas a nivel de cuenta que incluyan desgloses cardinales, como action_target_id o product_id, e intervalos de fechas más amplios, como la duración total.
• Usa el perímetro /insights directamente con objetos de anuncios de nivel inferior para recuperar datos detallados de ese nivel. Por ejemplo, en primer lugar usa la consulta de nivel de cuenta para recuperar la lista de identificadores de objeto de nivel inferior con los parámetros level y filtering. En este ejemplo se recuperan todas las campañas que han registrado 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'

• A continuación, podemos usar /<campaign_id>/insights con cada valor devuelto para consultar y agrupar por lotes las solicitudes de insights 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 únicamente para recuperar insights de los objetos de anuncios con datos. El valor del campo que se especifica en filtering utiliza la notación de punto para indicar los campos del objeto. Ten en cuenta que filtrar con STARTS_WITH y CONTAIN no cambia los datos del resumen. En este caso, usa el operador IN. A continuación, se incluye un ejemplo de una solicitud con 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. En nuestro sistema, los intervalos de fechas personalizados ofrecen una eficacia menor.
• Usa las solicitudes por lotes para realizar varias llamadas síncronas y asíncronas a fin de consultar grandes volúmenes de datos y evitar que se agote el tiempo de espera.
• Empieza probando las llamadas síncronas; usa las asíncronas en los casos en que las primeras agoten el tiempo de espera.
• Los insights se actualizan cada 15 minutos y no cambian hasta 28 días después de haberse registrado.

Límites de carga de llamadas de insights

Cambiamos el límite de frecuencia a nivel de cuenta publicitaria pasados noventa días desde el lanzamiento de la versión 3.3 y con vigencia en todas las versiones públicas para reflejar mejor el volumen de llamadas a la API necesarias. Para obtener información sobre cómo calculamos la cuota del límite de frecuencia en tu nivel de acceso a la API de marketing y en la empresa a la que pertenece la aplicación, consulta Acceso y autenticación. Este cambio se aplica a todos los extremos de la API de insights 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.

Utilizamos límites de carga con el fin de ofrecer una experiencia óptima. Medimos la frecuencia de las llamadas a la API, así como los recursos que requieren. Permitimos un límite de carga fijo por segundo y por aplicación. Cuando superes el límite, se producirá un error en las solicitudes.

Consulta el encabezado HTTP x-fb-ads-insights-throttle en cada respuesta de la API para saber lo cerca que está la aplicación del límite, así como para estimar el tamaño aproximado que tendrá una consulta concreta. Las llamadas de insights también están sujetas a los límites predeterminados de las cuentas publicitarias que se muestran en el encabezado HTTP x-ad-account-usage. Encontrarás más información aquí: Prácticas recomendadas de la API de marketing.

Cuando una aplicación alcanza su límite, la llamada recibe una respuesta de error con error_code = 4, CodedException. Lo ideal es mantenerte alejado del límite. Si una aplicación alcanza su límite permitido, solo se completa un porcentaje concreto de solicitudes, en función de la consulta y la frecuencia.

Aplicamos limitación de frecuencia a todas las aplicaciones que envían llamadas de /insights síncronas y asíncronas combinadas. Los dos límites de parámetros principales se fijan por aplicación y por cuenta publicitaria.

A continuación, se muestra un ejemplo de encabezado HTTP que incluye la puntuación acumulada de una aplicación expresada como un 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 incluye la siguiente información:

• app_id_util_pct: porcentaje utilizado de la capacidad asignada al identificador de aplicación asociado.
• acc_id_util_pct: porcentaje utilizado de la capacidad asignada al identificador de la cuenta publicitaria asociado.
• ads_api_access_tier: los niveles permiten que la aplicación acceda a la API de marketing. standard_access permite una limitación de frecuencia menor.

Límites de frecuencia globales

En periodos en los que el extremo /insights reciba una carga global elevada, el sistema puede limitar las solicitudes para proteger el entorno de backend. Esto puede ocurrir de manera poco frecuente cuando se reciben demasiadas consultas de gran complejidad (intervalos de tiempo grandes, métricas complejas o cantidades elevadas de identificadores de objetos de anuncios) al mismo tiempo. Esto se manifestará como un error similar a este:

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

En estos casos, se aconseja reducir las llamadas, esperar un periodo corto de tiempo y volver a realizar la consulta.

Prácticas recomendadas de los límites de frecuencia

• Si se envían varias consultas a la vez, hay más probabilidades de que se active nuestra limitación de frecuencia. Intenta distribuir las consultas de /insights espaciándolas con tiempos de espera en el trabajo.
• Utiliza la información sobre frecuencia incluida en el encabezado de la respuesta HTTP para controlar las llamadas. Añade un mecanismo de limitación para ralentizar o pausar las consultas de /insights cuando estés cerca de alcanzar el 100 % de uso en la aplicación o en la cuenta publicitaria.
• Registramos los datos de los insights de anuncios según la zona horaria de la cuenta publicitaria. Para recuperar a diario los datos de insights de la cuenta publicitaria asociada, ten en cuenta la hora del día usando la zona horaria de la cuenta. De esta forma, se pueden espaciar las consultas durante el día.
• Consulta el ads_api_access_tier que te permite acceder a la API de marketing. De forma predeterminada, las aplicaciones están en el nivel development_access, y standard_access permite una limitación de frecuencia menor. Para obtener un límite de frecuencia mayor y llegar al nivel estándar, puedes solicitar “acceso avanzado” a la función Acceso estándar a la administración de anuncios.

Trabajos asíncronos de la API de insights

Recupera las estadísticas de varios objetos, fíltralas y ordénalas. El proceso asíncrono ahora resulta mucho más sencillo:

1. Envía una solicitud POST al extremo <AD_OBJECT>/insights, que responderá con el id de una ejecución de un informe de anuncios.

{
  "report_run_id": 6023920149050,
}
    

No conserves el report_run_id para usarlo a largo plazo, ya que caducará pasados 30 días.

1. Las ejecuciones de informes de anuncios contienen información sobre este trabajo asíncrono, como async_status. Sondea 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. A continuación, puedes consultar el perímetro <AD_REPORT_RUN_ID>/insights para recuperar 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 asíncrono:

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 asíncrono

Exportación de informes

Ponemos a disposición un extremo para exportar <AD_REPORT_RUN_ID> a un formato legible localizado.

Nota: Ten en cuenta que este extremo no forma parte de las versiones de nuestra API Graph, por lo que no sigue su política sobre cambios de última hora. Los scripts y programas no deben depender del formato resultante, ya que este podría 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/'