Ограничения и рекомендации

Facebook Insights API предоставляет данные о результативности маркетинговых кампаний на Facebook. Чтобы гарантировать высокую производительность и стабильность системы, мы разработали защитные меры, обеспечивающие равномерное распределение ресурсов по всем приложениям. Все приведенные ниже правила могут быть изменены.

Ограничение объема данных на вызов

Ограничения объема данных на вызов необходимы для того, чтобы запрос не получал больше данных, чем может обработать система. Есть два вида ограничения данных:

1. по количеству строк в ответе;
2. по количеству точек данных, необходимых для расчета итоговых значений, например строки сводки.

Эти ограничения применяются как к синхронным, так и к асинхронным вызовам /insights. Их превышение приводит к следующей ошибке:

error_code = 100,  CodeException (error subcode: 1487534)

Рекомендации по соблюдению ограничений объема данных на вызов

• Вы можете ограничить диапазон дат или количество ID объявлений. Кроме того, можно запросить только самые необходимые метрики или разбить один запрос на несколько разных, каждый из которых возвращает подмножество метрик.
• Рекомендуем не использовать на уровне аккаунта запросы со слишком подробными разбивками, например по action_target_id или product_id, а также слишком широкие диапазоны дат, например весь срок действия.
• Чтобы получить подробные данные о рекламных объектах низкого уровня, используйте границу контекста /insights. Например, выполните сначала запрос на уровне аккаунта, чтобы получить список ID рекламных объектов низкого уровня, с параметрами level и filtering. В этом примере мы собираем данные по всем кампаниям, в которых зарегистрированы показы:

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'

• Затем мы используем /<campaign_id>/insights с каждым полученным значением для запроса и объединяем запросы статистики для этих кампаний в одном вызове:

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'

• Используйте параметр filtering, чтобы получить статистику только для рекламных объектов с данными. В значении filtering поля отделяются от объектов точкой. Обратите внимание: фильтрация по критериям STARTS_WITH и CONTAIN не влияет на сводные данные. В этом случае используйте оператор IN. Вот пример запроса 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'

• По возможности используйте date_preset. Пользовательские диапазоны дат в нашей системе менее эффективны.
• Для выполнения нескольких синхронных вызовов используйте пакетные запросы. Чтобы не истекло время ожидания, для запроса больших объемов данных используйте асинхронные вызовы.
• Сначала попробуйте выполнить синхронные вызовы, а в тех случаях, когда заканчивается время ожидания, используйте асинхронные.
• Статистика обновляется каждые 15 минут и не меняется после 28 дней публикации.

Ограничения нагрузки вызовов статистики

Через 90 дней после выхода версии 3.3 максимальное количество обращений на уровне рекламного аккаунта для всех общедоступных версий изменится в соответствии с необходимым объемом вызовов API. Для каждого аккаунта ограничение вычисляется индивидуально, в зависимости от его уровня доступа к Marketing API и компании, которой принадлежит приложение. См. подробные сведения о доступе и аутентификации. Это изменение относится ко всем конечным точкам Ads Insights API: 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, POST {ad_ID}/insights.

Эти ограничения позволяют оптимизировать получение статистики. Мы измеряем частоту вызовов API, а также требуемые для них ресурсы. Мы допускаем фиксированную максимальную нагрузку на приложение в секунду. При превышении этого значения запросы не выполняются.

По заголовку HTTP x-fb-ads-insights-throttle, который возвращается в каждом ответе API, можно понять, насколько ваше приложение приблизилось к ограничению, и оценить, насколько объемным может быть отдельный запрос. Для вызовов статистики также действуют ограничения по умолчанию на уровне рекламного аккаунта, указанные в заголовке HTTP x-ad-account-usage. Подробные сведения см. в рекомендациях по Marketing API.

Когда приложение достигает ограничения, вызов возвращает сообщение об ошибке с error_code = 4, CodedException. Следите за тем, чтобы не приближаться к пороговому значению. Если приложение достигнет его, от него будет проходить только определенная доля запросов в зависимости от самого запроса и частоты.

Ограничение количества обращений применяется ко всем приложениям, которые отправляют синхронные и асинхронные вызовы /insights в любых сочетаниях. Действуют два основных ограничения: по приложению и по рекламному аккаунту.

Вот пример заголовка HTTP с накопленными баллами для приложения в виде процентной доли от пороговых значений:

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

Заголовок x-fb-ads-insights-throttle — это значение JSON, содержащее следующую информацию:

• app_id_util_pct — доля выделенного объема, использованная соответствующим app_id;
• acc_id_util_pct — доля выделенного объема, использованная соответствующим account_id рекламного аккаунта.
• ads_api_access_tier — уровни позволяют вашему приложению получить доступ к Marketing API. standard_access задействует более низкое ограничение числа обращений.

Глобальные ограничения числа обращений

В период повышенной глобальной нагрузки на конечную точку /insights система может регулировать запросы для защиты серверов. Это бывает нечасто и случается, если одновременно поступает слишком много запросов высокой сложности (большие временные диапазоны, сложные метрики и (или) большое количество ID рекламных объектов). Это приведет к следующей ошибке:

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

В такие периоды рекомендуется сократить количество вызовов, подождать некоторое время и повторить запрос.

Рекомендации по соблюдению ограничения числа обращений

• При отправке сразу нескольких запросов ограничение числа обращений сработает с большой вероятностью. Старайтесь распределять запросы /insights, оставляя между ними время на ожидание.
• Информация о частоте в заголовке ответа HTTP поможет вам управлять вызовами. Чтобы замедлить или приостановить запросы /insights, когда до достижения ограничения по приложению или рекламному аккаунту остается совсем немного, добавьте механизм отсрочки.
• Мы предоставляем статистику рекламы согласно часовому поясу, указанному в рекламном аккаунте. Для ежедневного получения статистики по рекламному аккаунту учитывайте время дня в соответствии с настроенным часовым поясом. Это поможет распределить запросы в течение дня.
• Проверьте ads_api_access_tier, который позволяет вам получить доступ к Marketing API. По умолчанию приложения находятся на уровне development_access, а standard_access позволяет уменьшить ограничение числа обращений. Чтобы увеличить ограничение числа обращений и перейти на стандартный уровень, вы можете подать заявку на расширенный доступа к функции Стандартный уровень доступа для управления рекламой.

Асинхронные задания Insights API

Мы упростили работу с асинхронными заданиями, и вы можете собирать статистику по множеству объектов и применять фильтры и сортировку.

1. Отправьте запрос POST на конечную точку <AD_OBJECT>/insights. В ответе вы получите id для результата запуска отчета по рекламе.

{
  "report_run_id": 6023920149050,
}
    

Срок действия report_run_id составляет 30 дней.

1. Результаты запусков отчетов по рекламе содержат информацию об этом асинхронном задании, например async_status. Опрашивайте это поле до тех пор, пока для async_status не будет получено значение Job Completed, а для async_percent_completion — 100.

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

1. Затем можно запросить границу контекста <AD_REPORT_RUN_ID>/insights, чтобы получить конечный результат.

{
  "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"
    }
  }
}
    

Это задание получает всю статистику для аккаунта и возвращает ID асинхронного задания:

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

Статус асинхронного задания

Экспорт отчетов

Мы предлагаем конечную точку для экспорта <AD_REPORT_RUN_ID> в локализованном удобном для чтения формате.

Примечание. Эта конечная точка не является частью API Graph разных версий, поэтому политика важных изменений Graph API на нее не распространяется. Скрипты и программы не должны опираться на этот формат результата, поскольку он может быть изменен без предупреждения.

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