그래프 API의 사용 제한

Facebook 그래프 API의 사용 제한은 드물게 발생합니다. 이 문서에서는 사용 제한 및 사용 제한을 처리하는 방법을 설명합니다.

앱에서 발생할 수 있는 사용 제한으로는 크게 앱 레벨 사용 제한과 페이지 레벨 사용 제한의 두 가지 유형이 있습니다.

엡 레벨 사용 제한

이 제한은 페이지 액세스 토큰이 아닌 액세스 토큰을 사용한 호출에 적용됩니다. 이 제한에 도달하면 앱에서 오류 코드 4를 받습니다.

사용 제한 대시보드

앱의 앱 대시보드에 앱의 사용 제한 활동에 대한 차트가 표시됩니다.

제한 사항

사용 제한은 각 앱에 적용됩니다. 사용 제한 도구는 앱이 제한될 가능성이 얼마나 높은지에 대한 정보를 제공합니다. 활용 유형에 대한 자세한 내용을 보려면 샘플을 클릭하세요.

앱에서는 전체적으로 사용자당 한 시간에 200번의 호출을 할 수 있습니다. 예를 들어, 앱의 사용자가 100명이면 앱에서 20,000번의 호출을 할 수 있습니다. 이 제한은 사용자당 제한이 아니므로 한 사용자가 19,000번의 호출을 하고 다른 사용자가 1,000번의 호출을 할 수 있습니다. 이 제한은 이전 1시간 동안의 호출 수를 기준으로 계산됩니다.

앱에 사용 제한이 적용되면 특정 사용자만이 아니라 앱에 대한 모든 호출이 제한됩니다.

앱의 사용자 수는 일일 평균 액티브 사용자 수에 오늘의 추산 신규 로그인 수를 더한 값입니다. 사용자 수가 많은 앱의 사용 제한이 사용자 수가 적은 앱보다 더 정확할 수 있습니다. 사용자 수가 매우 적은 앱에는 사용 제한 문제가 있을 수 있습니다.

주의 사항:

  • 모든 API 호출에 사용 제한이 적용되는 것은 아니므로 호출 수가 사용 제한 도구에 표시되는 수와 일치하지 않을 수도 있습니다.
  • 또한 Facebook은 사용된 CPU 시간과 전체 시간을 기반으로 호출을 제한합니다. 이 제한에 도달하기는 어려우므로, 극히 드물게 발생합니다. 이 정보는 각 샘플의 상세 정보 창에 표시되어 있습니다. 상세 정보를 보려면 대시보드에 표시된 사용 제한 도구의 그래프를 클릭하세요.
  • 광고 인사이트 API마케팅 API에서는 다른 사용 제한을 사용할 수도 있습니다. 마케팅 API에 대한 자세한 내용은 마케팅 API 사용 제한 문서(https://developers.facebook.com/docs/marketing-api/api-rate-limiting)를 참조하세요.

권장 사항

사용 제한은 특정 기간 내 가능한 API 호출 수에 대한 제한을 정의합니다. 사용 제한을 초과하면 앱의 모든 API 호출이 제한되고 잠시 중단됩니다. 앱이 제한되면 이후 호출에 대해 호출자에게 error code = 4, CodedException인 오류가 표시됩니다. 요청이 다시 수락될 때까지 최대 1시간이 소요될 수 있습니다.

사용 제한을 피하려면 다음과 같이 하세요.

  • 전송 트래픽이 폭주하는 현상이 발생하지 않도록 쿼리를 두 기간 사이에 고르게 분산합니다.
  • 필터를 사용하여 데이터 응답 크기를 제한하고 겹치는 데이터를 요청하는 호출을 하지 않습니다.
  • 사용 제한 헤더를 사용하여 자동으로 호출량의 균형을 맞춥니다.

사용 제한 헤더

앱에서 Facebook 시스템에서 사용 제한을 고려하기에 충분한 수를 호출하는 경우 X-App-Usage HTTP 헤더가 반환됩니다. 헤더에는 앱의 현재 사용률이 포함되며, 이 비율은 사용 제한 그래프에 표시되는 사용률과 같습니다. 자동으로 호출 로드의 균형을 맞춰 제한되지 않도록 하려면 이 수치를 사용하세요.

사용 제한 헤더는 다음과 같은 형태의 JSON 형식 문자열입니다.

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

x, y, z 값은 각 지표의 사용률 값을 나타내는 정수입니다. 이 중 한 지표가 100을 초과하면 앱이 사용 제한됩니다.

페이지 레벨 사용 제한

이 제한은 페이지 액세스 토큰을 사용한 호출에 적용됩니다. 이 제한에 도달하면 앱에서 오류 코드 32를 받습니다.

페이지 레벨 사용 제한에 대한 자세한 설명은 https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/의 블로그 게시물을 참조하세요.

사용 제한 대시보드

앱에서 호출을 하기 위해 액세스 토큰을 사용하는 각 페이지에 대해 사용 제한 차트가 표시됩니다.

제한 사항

사용 제한은 앱이 아니라 각 페이지에 적용됩니다. 사용 제한 도구는 해당 페이지의 액세스 토큰을 사용하는 앱의 수 및 페이지가 제한에 얼마나 가까운지에 대한 정보를 제공합니다. 활용 유형에 대한 자세한 내용을 보려면 샘플을 클릭하세요.

페이지를 사용하여 참여한 일일 사용자 수는 24시간 동안 페이지에 참여한 고유 사용자 수입니다. 페이지 참여도는 페이지 또는 페이지 콘텐츠의 클릭수로 구성됩니다.

이전 24시간 동안 참여한 사용자 수가 현재 24시간의 사용 제한을 계산하기 위해 사용됩니다.

24시간 동안 페이지를 대신하여 일일 참여 사용자당 총 4,800번의 호출을 할 수 있습니다. 예를 들어, 페이지의 일일 참여 사용자가 100명이면 24시간 동안 페이지를 대신하여 480,000번의 호출을 할 수 있습니다. 이 24시간은 이동식 기간으로 몇 분마다 업데이트됩니다. 호출 제한은 페이지당 제한이므로 한 앱에서 400,000번의 호출을 하고 다른 앱에서 80,000번의 호출을 할 수 있습니다. 페이지가 사용 제한되면 해당 페이지의 액세스 토큰을 사용하는 앱의 호출만 제한됩니다. 다시 말해 다른 호출에 대해서는 앱이 여전히 정상적으로 작동할 수 있습니다.

페이지 호출 수는 페이지 액세스 토큰을 사용하는 일일 추산 호출 수로 계산됩니다. 일일 호출 수가 많은 페이지의 사용 제한이 일일 호출 수가 적은 페이지보다 더 정확할 수 있습니다. 일일 호출 수가 매우 적은 페이지에는 사용 제한 문제가 있을 수 있습니다.

주의 사항:

  • 모든 API 호출에 사용 제한이 적용되는 것은 아니므로 호출 수가 사용 제한 도구에 표시되는 수와 일치하지 않을 수도 있습니다.
  • 또한 Facebook은 사용된 CPU 시간과 전체 시간을 기반으로 호출을 제한합니다. 상세 정보를 보려면 대시보드에 표시된 사용 제한 도구의 그래프를 클릭하세요.
  • 광고 인사이트 API마케팅 API에서는 다른 사용 제한을 사용할 수도 있습니다. 마케팅 API에 대한 자세한 내용은 마케팅 API 사용 제한 문서를 참조하세요.

권장 사항

페이지가 제한되면 이후 호출에 대해 호출자에게 error code = 32, CodedException인 오류가 표시됩니다. 해당 페이지에 대한 요청이 다시 수락될 때까지 최대 1시간이 소요될 수 있습니다.

사용 제한을 피하려면 다음과 같이 하세요.

  • 전송 트래픽이 폭주하는 현상이 발생하지 않도록 쿼리를 두 기간 사이에 고르게 분산합니다.
  • 필터를 사용하여 데이터 응답 크기를 제한하고 겹치는 데이터를 요청하는 호출을 하지 않습니다.
  • 사용 제한 헤더를 사용하여 자동으로 호출량의 균형을 맞춥니다.

사용 제한 헤더

페이지를 대신하여 Facebook의 시스템에서 사용 제한을 고려하기에 충분한 수를 호출하는 경우 X-Page-Usage HTTP 헤더가 반환됩니다. 헤더에는 앱의 현재 사용률이 포함되며, 한 페이지의 액세스 토큰을 사용하여 호출을 하는 경우 해당 페이지에 대한 X-Page-Usage 값만 얻게 됩니다. 이 비율은 해당 페이지의 사용 제한 그래프에 표시되는 사용률과 같습니다. 자동으로 호출 로드의 균형을 맞춰 제한되지 않도록 하려면 이 수치를 사용하세요.

사용 제한 헤더는 다음과 같은 형태의 JSON 형식 문자열입니다.

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

x, y, z 값은 각 지표의 사용률 값을 나타내는 정수입니다. 이 중 한 지표가 100을 초과하면 앱이 사용 제한됩니다.

계정 수준 사용 제한

이 제한은 사용자 액세스 토큰을 사용한 호출에 적용됩니다. 이 제한 한도에 도달하면 오류 코드 17이 반환되며, 특정 사용자 계정에서 API를 너무 많이 호출하면 제한 한도에 도달하게 됩니다.

참고:

여기에는 개발자의 앱뿐 아니라 여러 다른 앱에서 이루어진 사용자 호출이 포함됩니다.

사용자에 대한 사용 제한 한도에 도달하면 사용자의 API 호출이 제한됩니다.

사용 제한을 피하려면 다음과 같이 하세요.

개발자가 이를 예방하는 방법은 없으며, 사용이 제한되는 것은 사용자가 호출을 너무 많이 하기 때문입니다(다른 앱을 통해 호출하는 것일 수도 있음). 하지만 특정 앱에서 여러 사용자가 제한을 받을 경우 해당 앱을 통해 발생하는 API 호출 때문일 가능성이 높습니다. 이 경우 사용자의 호출을 줄이거나 호출을 더 균등하게 분배해야 합니다.

FAQ

API 호출로 간주되는 항목은?

모든 호출은 단순히 개별 HTTP API 요청이 아니라 사용 제한에 포함됩니다. 예를 들어, 단일 API 호출을 하고 여러 개의 ID를 지정할 수 있지만 각 ID는 하나의 HTTPS API 요청을 하더라도 자체 API 호출로 계산됩니다.

이 개념에 대한 설명은 아래의 예제를 참조하세요.

요청 예시 API 호출의 개수

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

여러 개의 개체를 ID별로 순회해야 하는 시나리오의 경우, API 응답의 성과는 개선되지만 사용 제한에 포함되는 호출의 수는 개선되지 않는 두 번째 방법을 사용하시기 바랍니다.

일괄 API를 사용하여 요청을 일괄 처리할 수 있지만, 각 하위 요청은 자체 API 호출 또는 여러 개의 API 호출(여러 개의 ID를 지정하는 경우)입니다.

앱이 사용 제한되는 경우 되는 API 호출도 사용 제한에 포함됩니다.

내 앱에 표시되는 오류는?
제한 유형 최소값 오류 코드

앱 수준 제한

호출 200개/사용자/시간

4

계정 수준 제한

해당 사항 없음

17

페이지 수준 제한

호출 4,800개/사용자/24시간

32

맞춤 수준 제한

해당 사항 없음

613

오류 코드 613이 발생합니다. 어떻게 해야 하나요?

앱이 맞춤 사용 제한을 초과한다는 의미입니다. 이 문제를 해결하는 데 도움이 필요한 경우 파트너 관리자에게 문의하세요.

스크래퍼를 만들고 있습니다. 어떤 사항을 고려해야 하나요?

데이터를 스크래핑하는 서비스를 만드는 경우에는 Facebook의 스크래핑 용어를 읽어보세요.