그래프 API 사용

그래프 API는 Facebook의 소셜 그래프에서 데이터를 가져오고 내보내는 기본 방법으로, 데이터를 검색하고, 새 소식을 게시하고, 사진을 업로드하고 앱에서 다양한 작업을 실행하기 위해 사용할 수 있는 낮은 수준의 HTTP 기반 API입니다. 이 가이드에서는 그래프 API를 통해 다양한 작업을 수행하는 방법을 설명합니다.

기본 사항

그래프 API 용어 및 구조의 기본 사항은 그래프 API 개요에 설명되어 있습니다. 다음 섹션에서는 API를 사용하여 수행할 수 있는 다양한 작업에 대해 자세히 설명합니다.

읽기

그래프 API의 모든 노드와 에지는 관련 엔드포인트에 HTTP GET 요청을 보내기만 하면 읽을 수 있습니다. 예를 들어, 현재 사용자에 대한 정보를 검색하려면 아래와 같이 HTTP GET 요청을 보냅니다.

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

대부분의 API 호출은 액세스 토큰을 사용하여 서명해야 합니다. 읽으려는 노드나 에지에 대한 그래프 API 참조를 보면 이 액세스 토큰에 어떤 권한이 필요한지 확인할 수 있습니다. 그래프 API 탐색기를 사용하여 신속하게 토큰을 생성하여 API를 사용해보고 작동 방식을 알아볼 수도 있습니다.

/me 노드는 액세스 토큰이 현재 API 호출에 사용되고 있는 사람의 user_id 또는 Facebook 페이지의 page_id로 변환되는 특별한 엔드포인트입니다. 사용자 액세스 토큰이 있으면 다음을 사용하여 사용자의 모든 사진을 가져올 수 있습니다.

GET graph.facebook.com
  /me/photos

읽는 노드나 에지에 따라 다른 응답을 받게 됩니다. 반응의 일반적인 형태는 다음과 같습니다.

{
   "fieldname": {field-value},
   ....
}

필드 선택

기본적으로 노드나 에지를 검색할 때 해당 노드나 에지의 모든 필드가 반환되지는 않습니다. fields 검색 매개변수를 사용할 때 반환될 필드 또는 에지를 선택할 수 있습니다. 이 기능은 API 호출을 더 효율적이고 신속하게 처리하는 데 매우 유용합니다.

예를 들어, 개발자의 자체 사용자 액세스 토큰을 사용하는 다음 그래프 API 호출(https://graph.facebook.com/me?fields=id,name,picture)은 사용자의 프로필에 있는 ID, 이름, 사진만 반환합니다.

GET graph.facebook.com/me?fields=id,name,picture

정렬

특정 데이터 집합을 시간순으로 정렬할 수 있습니다. 예를 들어, reverse_chronological 키를 사용하여 사진의 댓글을 역 시간순으로 정렬할 수 있습니다.

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order는 다음 값 중 하나여야 합니다.

  • chronological
  • reverse_chronological

URL 조회

대부분의 개체는 ID를 사용하여 검색할 수 있지만 ID를 사용하여 검색할 수 없고 URL만을 사용하여 식별해야 하는 경우도 있습니다.

v2.1에 소개된 URL 노드를 사용하여 오픈 그래프 개체 URL의 ID를 반환하거나 앱 링크 URL과 연결된 데이터를 찾을 수 있습니다.

앱 링크 문서에서 인덱스 API를 사용하여 앱 링크 데이터를 찾는 방법에 대해 자세히 알아보세요.

API 요청 수정

일부 API 엔드포인트는 요청을 수정하는 추가 매개변수와 함께 사용할 수 있습니다. 이들 '한정자'의 속성은 각각 다르므로 각 API 참조 문서에 따로 문서화되어 있습니다. 다음은 대부분의 엔드포인트와 함께 사용할 수 있는 일반적인 한정자 리스트입니다.

이름 설명 유형

return_ssl_resources

브라우저의 혼합 콘텐츠 경고를 피하기 위해 보안 연결(HTTPS)을 통해 사진을 반환하도록 요청할 때 사용됩니다.

bool

locale

앱에서 특정 로캘의 언어로 현지화된 콘텐츠를 검색해야 할 경우에 사용됩니다(사용 가능한 경우).

Locale

다음은 페이지 매김검사를 위한 한정자입니다.

중첩된 요청 만들기

그래프 API의 필드 확장 기능을 사용하면 단일 호출에서 여러 개의 그래프 검색어를 효과적으로 중첩할 수 있습니다. 대부분의 광고 API를 포함한 특정 리소스는 일부 또는 모든 연결에서 필드 확장을 이용할 수 없습니다.

예를 들어, 단일 호출에서 처음 K개 사진첩의 처음 N장의 사진을 요청할 수 있습니다. 응답에서 데이터 계층구조를 유지하므로 개발자가 클라이언트에서 데이터를 구성할 필요가 없습니다.

이 기능은 단일 요청에서 서로 관련이 없는 여러 개의 그래프 API 호출을 할 수 있는 일괄 요청 기능과 다릅니다.

다음은 필드 확장의 일반적인 형식입니다.

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

이 경우 <first-level>은 상위 노드에서 쉼표로 구분된 하나 이상의 필드 또는 에지입니다. <second-level>은 first-level 노드에서 쉼표로 구분된 하나 이상의 필드 또는 에지입니다.

여기서 일어날 수 있는 중첩 수준의 수에는 제한이 없습니다. 각 필드나 에지에서 .limit(n) 인수를 사용하여 가져올 개체 수를 제한할 수도 있습니다.

이 기능은 어떻게 사용되는지 보면 쉽게 이해할 수 있습니다. 다음 검색어는 누군가 만든 최대 다섯 개의 사진첩과 피드의 마지막 게시물 다섯 개를 검색합니다.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

그런 다음 이 검색어를 조금 더 확장하여 각 사진첩 개체에 대해 처음 두 장의 사진 및 각 사진에 태그된 사람들도 검색할 수 있습니다.

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

이제 각 사진의 이름, 사진 URL 및 태그된 사람을 검색하여 다시 확장할 수 있습니다.

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

커서 기반 페이지 매김을 사용하는 예를 살펴보겠습니다.

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

필드 확장이 여러 노드, 에지, 필드에서 어떻게 작동하여 단일 요청에서 매우 복잡한 데이터를 반환하는지 확인할 수 있습니다.

페이지를 매긴 결과의 트래버스

노드 또는 에지에 API 요청을 할 때, 일반적으로 해당 요청의 모든 결과를 단일 응답으로 받지는 않습니다. 이는 일부 응답에 수천 개의 개체가 포함될 수 있으므로 기본적으로 대부분의 응답에 페이지가 매겨지기 때문입니다.

커서 기반 페이지 매김

커서 기반 페이지 매김은 가장 효율적인 페이지 매김 방법이며 가능한 경우 항상 사용해야 합니다. 커서는 데이터 리스트에서 특정 항목을 표시하는 임의의 문자열을 가리킵니다. 이 항목이 삭제되지 않는 한 커서는 항상 리스트의 같은 부분을 가리키지만, 항목이 삭제되면 무효화됩니다. 따라서, 앱에서 커서를 저장하거나 커서가 앞으로도 유효할 것이라고 가정하지 말아야 합니다.

커서 페이지 매김을 지원하는 에지를 읽는 경우 다음과 같은 JSON 응답이 표시됩니다.

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

커서 페이지 매김이 적용된 에지는 다음 매개변수를 지원합니다.

  • before: 반환된 데이터 페이지의 처음을 가리키는 커서입니다.
  • after: 반환된 데이터 페이지의 끝을 가리키는 커서입니다.
  • limit: 반환될 수 있는 최대 개체 수입니다. 필터링으로 인해 검색어가 limit의 값보다 적은 수를 반환할 수 있습니다. 검색어가 데이터 리스트의 끝에 도달했다는 것을 나타내기 위해 limit 값보다 적은 수의 결과에 의존하지 마세요. next가 없는 경우에는 아래에 설명된 대로 사용하세요. 예를 들어limit를 10으로 설정하고 9개의 결과가 반환되면 더 많은 데이터를 사용할 수 있을 수도 있지만 비공개 필터링으로 인해 항목 하나가 삭제된 것입니다. 일부 에지에는 성능상의 이유로 limit 값에 최대값이 설정되어 있을 수도 있습니다. 모든 경우 API는 올바른 페이지 매김 링크를 반환합니다.
  • next: 데이터의 다음 페이지를 반환하는 그래프 API 엔드포인트입니다. 이 매개변수가 포함되지 않으면 데이터의 마지막 페이지가 반환됩니다. 페이지 매김이 공개 범위 설정에 따라 작동하기 때문에 페이지가 비어 있어도 'next' 페이지 매김 링크가 포함되어 있을 수도 있습니다. 더 이상 'next' 링크가 표시되지 않으면 페이지 매김을 중단해야 합니다.
  • previous: 데이터의 이전 페이지를 반환하는 그래프 API 엔드포인트입니다. 이 매개변수가 포함되지 않으면 데이터의 첫 번째 페이지가 반환됩니다.

커서를 저장하지 마세요. 항목이 추가되거나 삭제되면 커서는 신속하게 무효화됩니다.

시간 기반 페이지 매김

시간 페이지 매김은 데이터 리스트에서 특정 시간을 가리키는 Unix 타임스탬프를 사용하여 결과 데이터를 탐색하는 데 사용됩니다.

시간 기반 페이지 매김을 사용하는 엔드포인트를 사용하는 경우 다음과 같은 JSON 응답이 표시됩니다.

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

시간 페이지 매김이 적용된 에지는 다음 매개변수를 지원합니다.

  • until: 시간 기반 데이터 범위의 끝을 가리키는 Unix 타임스탬프 또는 strtotime 데이터값입니다.
  • since: 시간 기반 데이터 범위의 처음을 가리키는 Unix 타임스탬프 또는 strtotime 데이터값입니다.
  • limit: 반환될 수 있는 최대 개체 수입니다. 필터링으로 인해 검색어가 limit의 값보다 적은 수를 반환할 수 있습니다. 검색어가 데이터 리스트의 끝에 도달했다는 것을 나타내기 위해 limit 값보다 적은 수의 결과에 의존하지 마세요. next가 없는 경우에는 아래에 설명된 대로 사용하세요. 예를 들어limit를 10으로 설정하고 9개의 결과가 반환되면 더 많은 데이터를 사용할 수 있을 수도 있지만 비공개 필터링으로 인해 항목 하나가 삭제된 것입니다. 일부 에지에는 성능상의 이유로 limit 값에 최대값이 설정되어 있을 수도 있습니다. 모든 경우 API는 올바른 페이지 매김 링크를 반환합니다.
  • next: 데이터의 다음 페이지를 반환하는 그래프 API 엔드포인트입니다.
  • previous: 데이터의 이전 페이지를 반환하는 그래프 API 엔드포인트입니다.

일관된 결과를 얻으려면 sinceuntil 매개변수를 모두 지정하세요. 또한 권장되는 시간 차이는 최대 6개월입니다.

오프셋 기반 페이지 매김

오프셋 기반 페이지 매김은 시간 순서와 관계없이 특정 개수의 개체를 반환하고자 할 때 사용할 수 있습니다. 에지가 커서 또는 시간 기반 페이지 매김을 지원하지 않는 경우에만 사용해야 합니다.

오프셋 페이지 매김이 적용된 에지는 다음 매개변수를 지원합니다.

  • offset: 각 페이지의 처음에 지정된 숫자만큼 오프셋을 설정합니다.
  • limit: 반환될 수 있는 최대 개체 수입니다. 필터링으로 인해 검색어가 limit의 값보다 적은 수를 반환할 수 있습니다. 검색어가 데이터 리스트의 끝에 도달했다는 것을 나타내기 위해 limit 값보다 적은 수의 결과에 의존하지 마세요. next가 없는 경우에는 아래에 설명된 대로 사용하세요. 예를 들어limit를 10으로 설정하고 9개의 결과가 반환되면 더 많은 데이터를 사용할 수 있을 수도 있지만 비공개 필터링으로 인해 항목 하나가 삭제된 것입니다. 일부 에지에는 성능상의 이유로 limit 값에 최대값이 설정되어 있을 수도 있습니다. 모든 경우 API는 올바른 페이지 매김 링크를 반환합니다.
  • next: 데이터의 다음 페이지를 반환하는 그래프 API 엔드포인트입니다. 이 매개변수가 포함되지 않으면 데이터의 마지막 페이지가 반환됩니다. 페이지 매김이 공개 범위 설정에 따라 작동하기 때문에 페이지가 비어 있어도 'next' 페이지 매김 링크가 포함되어 있을 수도 있습니다. 더 이상 'next' 링크가 표시되지 않으면 페이지 매김을 중단해야 합니다.
  • previous: 데이터의 이전 페이지를 반환하는 그래프 API 엔드포인트입니다. 이 매개변수가 포함되지 않으면 데이터의 첫 번째 페이지가 반환됩니다.

페이지 매김 중인 항목의 리스트에 새 개체가 추가되면 각 오프셋 기반 페이지의 콘텐츠가 변경됩니다.

일부 API 호출에는 오프셋 기반 페이지 매김이 지원되지 않습니다. 일관된 결과를 얻으려면 응답에 반환되는 이전/다음 링크를 사용하여 페이지 매김을 하는 것이 좋습니다.

큰 요청 만들기

일부 그래프 API 엔드포인트는 매우 큰 매개변수를 취할 수 있습니다. 요청이 2,000자 이상이면, 서버에서 너무 큰 GET 요청을 거부하기 때문에 서버 오류가 표시될 수도 있습니다.

큰 요청인 경우에는 GET 요청 대신 POST 요청을 사용하고 method=GET 매개변수를 추가하는 것이 좋습니다. 이렇게 하면 POSTGET인 것처럼 해석됩니다.

여러 개의 요청 만들기

그래프 API의 표준 버전은 개별 개체에 대한 데이터를 쉽게 가져오고 개체 간의 연결을 찾을 수 있도록 설계되었습니다. 여기에는 동시에 몇몇 개체에 대한 데이터를 검색할 수 있는 제한적인 기능이 포함됩니다.

앱에서 한 번에 많은 양의 데이터에 액세스해야 하거나 여러 개의 개체를 한 번에 변경해야 하는 경우, 보통 여러 개의 개별 HTTP 요청을 하는 대신 일괄 검색을 사용하는 것이 더 효율적입니다.

이를 위해 그래프 API는 다중 ID 조회, 일괄 처리 등 다양한 기능을 지원합니다. 일괄 요청은 별도의 가이드에 설명되어 있습니다. 다중 ID 조회에 대해 자세한 내용은 아래를 참조하세요.

다중 ID 읽기 요청

단일 GET 요청에서 여러 노드를 검색할 수 있습니다. 이 요청에서는 노드의 개체 ID와 함께 ?ids 엔드포인트를 사용합니다. 예를 들어, 단일 요청에서 Facebook 개발자 페이지와 현재 세션 사용자를 조회하려면 다음과 같은 그래프 API 호출을 사용할 수 있습니다.

GET graph.facebook.com
  /?ids=platform,me

이 호출은 다음 개별 API 요청과 동일합니다.

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

다음과 같은 데이터가 반환됩니다.

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

요청된 모든 ID에 요청된 에지가 있는 한 이 호출은 에지에도 사용할 수 있습니다. 예시:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

이는 다음 개별 API 요청과 동일합니다.

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

다음과 같은 데이터가 반환됩니다.

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

다중 ID 조회에도 필드 필터링, 필드 확장 및 제한 기능을 사용할 수 있지만, 개체 중 하나에 요청된 필드 중 하나라도 없으면 오류가 발생합니다. 예를 들어, 이 메서드를 사용하여 페이지와 사용자를 조회하고 fields=id,picture,gender로 필터링하면 페이지에gender 필드가 없기 때문에 요청이 실패합니다.

검사

그래프 API는 노드의 검사를 지원합니다. 따라서 노드의 유형을 미리 알지 못하더라도 노드에 포함된 모든 에지를 볼 수 있습니다. 이 정보를 얻으려면 metadata=1을 그래프 API 요청에 추가하세요.

GET graph.facebook.com
  /{node-id}?
    metadata=1

결과 JSON에는 지정된 노드에 대해 지원되는 모든 에지를 나열하는 metadata 속성이 포함됩니다.

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

게시하기

그래프 API의 대부분의 노드에는 게시 타겟이 될 수 있는 에지가 있습니다(예: /{user-id}/feed 또는 /{album-id}/photos). 모든 그래프 API 게시는 모든 필수 매개변수가 포함된 관련 에지에 대한 HTTP POST 요청을 사용하여 이루어집니다. 예를 들어, 누군가를 대신하여 게시물을 게시하려면 아래와 같이 HTTP POST 요청을 보냅니다.

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

모든 게시 호출은 액세스 토큰을 사용하여 서명해야 합니다. 게시하려는 노드에 대한 그래프 API 참조를 보면 이 액세스 토큰에 어떤 권한이 필요한지 확인할 수 있습니다.

게시할 수 있는 에지가 많이 있습니다. 자세한 내용은 각 노드에 대한 참조 문서를 참조하세요.

그래프 API에 대한 일반 시나리오 가이드에 몇 가지 일반적인 게시 시나리오에 대한 추가 정보가 포함되어 있습니다.

여러 개의 요청 만들기

일괄 요청을 사용하여 게시 호출을 읽기 호출과 연결할 수 있습니다. 자세한 내용은 여러 개의 API 요청 만들기를 참조하세요.

쓰기-후-읽기

많은 에지에서 쓰기-후-읽기를 지원합니다. 엔드포인트가 쓰기-후-읽기를 지원하는지, 어떤 필드를 사용할 수 있는지 확인하려면 각 엔드포인트의 참조 문서를 참조하세요.

업데이트

모든 그래프 API 업데이트는 업데이트된 모든 매개변수가 포함된 관련 노드에 대한 HTTP POST 요청을 사용하여 이루어집니다.

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

모든 업데이트 호출은 업데이트하려는 노드에 대한 그래프 API 참조에 따라, 해당 엔드포인트에 게시하는 데 필요한 것과 동일한 권한이 있는 액세스 토큰을 사용하여 서명해야 합니다.

쓰기-후-읽기

많은 에지에서 쓰기-후-읽기를 지원합니다. 엔드포인트가 쓰기-후-읽기를 지원하는지, 어떤 필드를 사용할 수 있는지 확인하려면 각 엔드포인트의 참조 문서를 참조하세요.

삭제

HTTP DELETE 요청을 보내 그래프에서 노드를 삭제합니다.

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

일반적으로 앱에서는 원래 해당 앱에서 만든 콘텐츠만 삭제할 수 있습니다. 자세한 내용은 해당 노드 또는 에지에 대한 참조 가이드를 확인하세요.

모든 HTTP 메서드를 지원하지 않는 클라이언트를 지원하기 위해 추가 인수 method=delete를 사용하여 엔드포인트에 POST 요청을 발행함으로써 HTTP 메서드를 재정의할 수 있습니다. 예를 들어, 다음 요청을 발행하여 댓글을 삭제할 수 있습니다.

POST graph.facebook.com
  /{comment-id}?
    method=delete

쓰기-후-읽기

엔드포인트 만들기 및 업데이트의 경우 그래프 API는 성공적으로 게시되거나 업데이트된 개체를 즉시 읽고 해당하는 읽기 엔드포인트에서 지원하는 모든 필드를 반환할 수 있습니다.

이 기능을 사용하려면 fields 매개변수를 요청에 포함하고 반환되기를 원하는 필드를 나열하세요. 예를 들어, 사용자의 피드에 "Hello" 메시지를 게시하려면 다음과 같이 요청하세요.

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

이렇게 하면 지정된 필드가 다음과 같이 JSON 형식 응답으로 반환됩니다.

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

엔드포인트가 쓰기-후-읽기를 지원하는지, 어떤 필드를 사용할 수 있는지 확인하려면 각 엔드포인트의 참조 문서를 참조하세요.

오류

어떤 이유에서(예를 들어, 존재하지 않는 필드를 요청하여) 읽기에 실패하면 그래프 API가 표준 오류 응답으로 응답합니다. 또한, 응답에는 값이 성공 시 엔드포인트가 일반적으로 반환하는 값인 original_response 속성이 포함됩니다.

예를 들어, 이 요청에는 잘못된 필드가 포함되어 있습니다.

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

이 경우 다음과 같은 응답을 얻게 됩니다.

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

/search 엔드포인트를 사용하여 소셜 그래프의 많은 공개 개체를 검색할 수 있습니다. 검색을 위한 구문은 다음과 같습니다.

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

모든 그래프 API 검색어에는 액세스 토큰을 요청에 포함해야 합니다. 검색을 실행하려면 사용자 액세스 토큰이 필요합니다.

사용 가능한 검색 유형

지원되는 검색 유형은 다음과 같습니다.

유형 설명 `q` 값

user

사람을 검색합니다(해당 사용자가 이름 검색을 허용한 경우).

이름

page

페이지를 검색합니다.

이름

event

이벤트를 검색합니다.

이름

group

그룹을 검색합니다.

이름

place

장소를 검색합니다. center 매개변수(위도와 경도 사용) 및 선택적으로 distance 매개변수를 추가하여 특정 위치 및 거리로 검색 범위를 좁힐 수 있습니다.

이름

placetopic

가능한 장소 페이지 항목 및 ID의 리스트를 반환합니다. 전체 리스트를 얻으려면 topic_filter=all 매개변수와 함께 사용하세요.

없음

ad_*

타게팅 옵션을 찾기 위해 사용할 수 있는 여러 가지 검색 옵션의 집합입니다.

타게팅 옵션을 참조하세요.

예시:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

오류 처리

API에 요청을 보내면 다양한 오류 응답이 발생할 수 있습니다. 다음 항목에서는 복구 방법을 설명하고 가장 일반적으로 사용되는 복구 방법에 대한 맵과 함께 오류 값의 리스트를 제공합니다.

오류 코드 수신

다음은 실패한 API 요청에서 발생하는 일반적인 오류 응답을 나타냅니다.

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: 읽을 수 있는 오류 설명입니다.
  • code: 오류 코드입니다. 일반적인 값이 일반적인 복구 방법과 함께 아래에 나열되어 있습니다.
  • error_subcode: 오류에 대한 추가 정보입니다. 일반적인 값이 아래에 나열되어 있습니다.
  • error_user_msg: 사용자에게 표시되는 메시지입니다. 메시지의 언어는 API 요청의 로캘을 기반으로 합니다.
  • error_user_title: 대화 상자의 제목입니다(표시되는 경우). 메시지의 언어는 API 요청의 로캘을 기반으로 합니다.
  • fbtrace_id: 내부 지원 식별자입니다. 그래프 API 호출과 관련된 버그를 보고할 때 fbtrace_id를 포함하면 디버그를 위한 로그 데이터를 찾는 데 도움이 됩니다.

오류 코드

코드 또는 유형 이름 취해야 할 조치

OAuthException

하위 코드가 없으면 로그인 상태나 액세스 토큰이 만료되었거나 취소되었거나 잘못된 것입니다. 새 액세스 토큰을 가져옵니다.

하위 코드가 있으면 하위 코드를 확인하세요.

102

API 세션

하위 코드가 없으면 로그인 상태나 액세스 토큰이 만료되었거나 취소되었거나 잘못된 것입니다. 새 액세스 토큰을 가져옵니다.

하위 코드가 있으면 하위 코드를 확인하세요.

1

API 알 수 없음

가동 중단으로 인한 일시적인 문제일 가능성이 있습니다. 잠시 기다렸다가 다시 시도해보세요. 문제가 다시 발생하면 기존 API를 요청하고 있는지 확인하세요.

2

API 서비스

가동 중단으로 인한 일시적인 문제입니다. 잠시 기다렸다가 다시 시도해보세요.

4

API 호출이 너무 많음

제한으로 인한 일시적인 문제입니다. 잠시 기다렸다가 다시 시도해보고 API 요청 볼륨을 확인하세요.

17

API 사용자 호출이 너무 많음

제한으로 인한 일시적인 문제입니다. 잠시 기다렸다가 다시 시도해보고 API 요청 볼륨을 확인하세요.

10

API 권한 거부됨

권한이 부여되지 않았거나 삭제되었습니다. 누락된 권한을 처리하세요.

190

액세스 토큰이 만료됨

새 액세스 토큰을 가져옵니다.

200-299

API 권한(권한에 따라 여러 개의 값)

권한이 부여되지 않았거나 삭제되었습니다. 누락된 권한을 처리하세요.

341

앱 한도 도달

가동 중단 또는 제한으로 인한 일시적인 문제입니다. 잠시 기다렸다가 다시 시도해보고 API 요청 볼륨을 확인하세요.

368

정책 위반으로 일시적으로 차단됨

잠시 기다렸다가 다시 시도해보세요.

506

중복 게시물

중복 게시물은 연속해서 게시할 수 없습니다. 게시물의 콘텐츠를 변경하고 다시 시도해보세요.

1609005

링크 게시 중 오류

제공된 링크에서 데이터를 스크랩하는 중 문제가 발생했습니다. URL을 확인하고 다시 시도해보세요.

인증 오류 하위 코드

코드 이름 취해야 할 조치

458

앱 설치되지 않음

사용자가 앱에 로그인하지 않았습니다. 사용자를 다시 인증하세요.

459

사용자 체크포인트

문제를 수정하려면 사용자가 https://www.facebook.com 또는 https://m.facebook.com에서 로그인해야 합니다.

460

비밀번호 변경됨

iOS 6 이상에서 사용자가 OS 통합 플로를 사용하여 로그인한 경우 비밀번호를 업데이트하려면 기기의 Facebook OS 설정으로 이동해야 합니다. 그렇지 않으면 앱에 다시 로그인해야 합니다.

463

만료됨

로그인 상태 또는 액세스 토큰이 만료되었거나 취소되었거나 잘못되었습니다. 만료된 액세스 토큰을 처리하세요.

464

확인되지 않은 사용자

문제를 수정하려면 사용자가 https://www.facebook.com 또는 https://m.facebook.com에서 로그인해야 합니다.

467

유효하지 않은 액세스 토큰

액세스 토큰이 만료되었거나 취소되었거나 잘못되었습니다. 만료된 액세스 토큰을 처리하세요.

복잡한 매개변수

대부분의 매개변수 유형은 stringint와 같이 간단한 기본 형식이지만 요청에서 지정할 수 있는 listobject 유형도 있습니다.

list 유형은 JSON 구문으로 지정됩니다. 예: ["firstitem", "seconditem", "thirditem"]

object 유형도 JSON 구문으로 지정됩니다. 예: {"firstkey": "firstvalue", "secondKey": 123}

API 요청 디버깅

그래프 API 디버그 모드

디버그 모드가 활성화된 경우 그래프 API 응답에 요청의 잠재적인 문제를 설명하는 추가 필드를 포함할 수 있습니다.

디버그 모드를 활성화하려면 debug 검색 문자열 매개변수를 사용하세요. 예시:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

user_friends 권한이 부여되지 않은 경우 다음과 같은 응답이 생성됩니다.

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

debug 매개변수 값은 'all' 또는 메시지의 type에 해당하는, 요청된 최소 심각도 수준으로 설정할 수 있습니다.

디버그 매개변수값 반환되는 값

all

사용 가능한 모든 디버그 메시지

info

infowarning 유형의 디버그 메시지

warning

warning 유형의 디버그 메시지만

디버그 정보(해당하는 경우)는 messages 배열 내 __debug__ 키 아래 JSON 개체로 반환됩니다. 이 배열의 각 요소는 다음 필드가 포함된 JSON 개체입니다.

필드 데이터 유형 설명

message

문자열

메시지

type

문자열

메시지 심각도

link

문자열

[선택 사항] 관련 정보를 가리키는 URL

디버그 모드를 그래프 API 탐색기에서 사용할 수도 있습니다.

API 요청에서 사용하는 버전 확인

앱을 만들고 그래프 API 요청을 할 때 응답을 보내는 API 버전을 알 수 있으면 도움이 될 수도 있습니다. 예를 들어, 버전을 지정하지 않고 호출할 경우 응답하는 API 버전을 알 수 없을 수도 있습니다.

그래프 API는 모든 응답에 응답을 생성한 API의 정확한 버전을 나타내는 facebook-api-version이라는 요청 헤더를 제공합니다. 예를 들어, v2.0을 사용하여 요청을 생성하는 그래프 API 호출의 HTTP 헤더는 다음과 같습니다.

facebook-api-version:v2.0

facebook-api-version 헤더를 사용하면 API 호출이 예상한 버전에서 반환되는지 확인할 수 있습니다.

버그 보고를 위한 디버그 정보

그래프 API의 버그를 보고해야 하는 경우 버그 보고서와 함께 보내야 하는 몇 가지 요청 헤더가 있습니다. 이 추가 요청 헤더를 통해 문제를 정확히 찾아내고 재현할 수 있습니다. 이러한 요청 헤더는 X-FB-Debug, x-fb-revX-FB-Trace-ID입니다.