마케팅 API

제한 및 모범 사례

Facebook 인사이트 API는 Facebook 마케팅 캠페인의 성과 데이터를 제공합니다. 시스템 성능 및 안정성을 보호하기 위해 Facebook은 시스템 리소스가 앱 전체에 균등하게 분포될 수 있도록 보호 조치를 취하고 있습니다. 아래 설명된 모든 정책은 변경될 수 있습니다.

호출당 데이터 제한

Facebook에서는 쿼리에서 시스템이 처리할 수 있는 수준을 넘어 지나치게 많은 데이터를 가져오지 않도록 호출당 데이터 제한을 적용하고 있습니다. 데이터 제한에는 두 가지 유형이 있습니다.

  1. 응답에 포함된 행의 숫자 기준
  2. 총 수치를 계산하는 데 필요한 데이터 포인트의 숫자 기준(예: 요약 행)

이러한 제한은 동기 및 비동기 /insights 호출 모두에 적용되며, 다음과 같은 오류를 반환합니다.

error_code = 100,  CodeException (error subcode: 1487534)

모범 사례, 호출당 데이터 제한

  • 기간 또는 광고 ID 수를 규제하여 쿼리를 제한하세요. 필요한 지표로 쿼리를 제한하거나, 각각 하위 지표를 요청하는 여러 개의 쿼리로 분류할 수 있습니다.
  • action_target_id 또는 product_id와 같은 높은 기수의 분석 데이터나 전체 기간과 같이 범위가 넓은 계정 수준의 쿼리는 피하세요.
  • /insights 에지를 낮은 수준의 광고 개체와 직접 함께 사용하여 해당 수준의 세부 데이터를 가져오면 됩니다. 예를 들어 처음에는 계정 수준 쿼리를 사용해 level 및 filtering 매개변수를 포함한 낮은 수준의 개체 ID 리스트를 가져옵니다. 이 예에서는 노출 일부가 기록된 모든 캠페인을 가져옵니다.
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에 지정된 필드 값은 DOT 표기를 사용하여 개체에 포함된 필드를 나타냅니다. 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를 사용합니다. 맞춤 기간은 Facebook 시스템에서 효율이 떨어집니다.
  • 대량의 데이터를 쿼리할 때는 복수의 동기 및 비동기식 호출에 일괄 요청을 사용하면 시간 초과를 방지할 수 있습니다.
  • 동기식 호출의 시간이 초과되면 동기식 호출을 먼저 시도한 다음 비동기식 호출을 사용합니다.
  • 인사이트는 15분마다 새로 고침되며, 보고된 후 28일이 지나면 변경되지 않습니다.

인사이트 호출 로드 제한

v3.3 릴리스로부터 90일이 지나서 모든 전체 공개 버전에 적용되면 필요한 API 호출량을 더욱 잘 반영할 수 있도록 광고 계정 수준 사용 제한을 변경합니다. Facebook은 마케팅 API 액세스 계층과 앱을 소유한 비즈니스에 대한 사용 제한 할당량을 계산합니다. 액세스 및 인증을 참조하세요. 이 변경 사항은 모든 광고 인사이트 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)에 적용됩니다.

로드 제한은 최적의 보고 경험을 제공하기 위해 사용합니다. Facebook에서는 API 호출의 속도는 물론 호출에 필요한 리소스도 측정합니다. 앱별로 1초당 고정된 로드 제한이 허용됩니다. 그 제한을 초과하면 요청이 실패합니다.

모든 API 응답에서 x-fb-ads-insights-throttle HTTP 헤더를 확인하여 앱이 얼마나 제한에 가까운지 알아보고, 특정 쿼리의 로드 부담이 얼마나 되는지 추산할 수 있습니다. 인사이트 호출은 x-ad-account-usage HTTP 헤더에 표시된 기본 광고 계정 제한에도 좌우됩니다. 더 자세한 내용은 마케팅 API, 모범 사례를 참조하세요.

앱이 제한에 도달하면 호출에서 error_code = 4, CodedException이 포함된 오류 응답을 받습니다. 제한보다 한참 못 미치는 수준을 유지하는 것이 좋습니다. 앱이 허용된 제한에 도달하면 쿼리와 속도에 따라 요청의 특정 비율만 처리됩니다.

Facebook에서는 동기 및 비동기 /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 — 티어를 사용하면 앱이 마케팅 API에 액세스할 수 있습니다. standard_access는 더욱 낮은 사용 제한을 지원합니다.

글로벌 사용 제한

전 세계적으로 /insights 엔드포인트에 대한 부하가 상승하는 기간에는 백엔드를 보호하기 위해 시스템에서 요청을 제한할 수 있습니다. 이는 매우 복잡한 쿼리(큰 시간 범위, 복잡한 지표 및/또는 많은 수의 광고 개체 ID)가 동시에 지나치게 많이 수신되는 드문 경우에 발생할 수 있습니다. 이 제한은 다음과 같은 오류로 표시됩니다.

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

이와 같은 기간에는 호출을 줄이고 잠시 기다렸다가 다시 쿼리하는 것이 좋습니다.

사용 제한 및 모범 사례

  • 한꺼번에 여러 쿼리를 전송하면 사용 제한이 트러거될 가능성이 높습니다. 작업의 대기 시간을 사용해 속도를 조절해서 /insights 쿼리를 널리 분산시켜보세요.
  • 호출을 관리하려면 HTTP 응답 헤더의 사용 정보를 사용하면 됩니다. 앱 또는 광고 계정에 대하여 사용률 100%에 근접할 때 /insights 쿼리 속도를 늦추거나 일시 중지하기 위한 백오프 메커니즘을 추가하세요.
  • 광고 인사이트 데이터는 광고 계정의 표준 시간대에 따라 보고합니다. 매일 연결된 광고 계정의 인사이트 데이터를 가져오려면 계정의 표준 시간대를 사용해 시간을 설정하는 것이 좋습니다. 이렇게 하면 하루 종일의 기간 동안 쿼리 속도를 조절하는 데 도움이 됩니다.
  • 마케팅 API에 액세스할 수 있도록 하는 ads_api_access_tier를 확인합니다. 기본적으로 앱은 development_access 티어에 있고 standard_access는 더 낮은 사용 제한을 지원합니다. 사용 제한을 높이고 표준 계층으로 올라가려면 광고 관리 표준 액세스 기능에 대한 '고급 액세스 권한'을 신청할 수 있습니다.

인사이트 API 비동기 작업

여러 개체에 대한 통계를 가져오고 필터링 및 정렬을 적용하세요. 더욱 단순해진 워크플로로 비동기 작업을 수행할 수 있습니다.

  1. <AD_OBJECT>/insights 엔드포인트에 POST 요청을 보냅니다. 이것은 광고 보고서 실행의 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

비동기 작업 상태

상태설명

Job Not Started

아직 작업이 시작되지 않았습니다.

Job Started

작업이 시작되었지만 아직 실행하지 않습니다.

Job Running

작업이 실행되기 시작했습니다.

Job Completed

작업이 완료되었습니다.

Job Failed

작업이 실패했습니다. 쿼리를 검토하고 다시 시도하세요.

Job Skipped

작업이 만료되어 건너뛰었습니다. 작업을 다시 제출하고 다시 시도하세요.

보고서 내보내기

Facebook에서는 <AD_REPORT_RUN_ID>를 현지화하고 사람이 읽을 수 있는 형식으로 내보내기 위해 편리한 엔드포인트를 제공합니다.

참고: 이 엔드포인트는 Facebook에서 버전을 관리하는 그래프 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/'
이름설명

name

문자열

다운로드된 파일 이름입니다.

format

enum{csv,xls}

파일 유형입니다.

report_run_id

정수

실행할 보고서의 ID입니다.

access_token

문자열

로그인한 사용자가 부여한 권한입니다. 다른 사용자를 위해 보고서를 내보내려면 이 값을 제공하세요.