개요
그래프 API는 Facebook 플랫폼에서 데이터를 가져오거나 내보내는 기본적인 수단입니다. 앱이 프로그래밍 방식으로 데이터 쿼리, 새 스토리 게시, 광고 관리, 사진 업로드를 비롯한 다양한 작업을 수행할 수 있는 HTTP 기반 API입니다.
그래프 API는 Facebook에서 정보를 표현하는 방식인 '소셜 그래프'라는 개념을 따서 이름을 붙였습니다. 이는 노드, 에지 및 필드로 구성됩니다. 일반적으로 특정 개체에 대한 데이터를 얻으려면 노드, 단일 개체에서 개체 컬렉션을 얻으려면 에지, 컬렉션의 단일 개체 또는 각 개체에 대한 데이터를 얻으려면 필드를 사용합니다. 이 문서에서는 노드와 에지를 '엔드포인트'로 지칭할 수 있습니다. 예를 들어 'GET 요청을 사용자 엔드포인트로 보내기'로 표현할 수 있습니다.
HTTP
모든 데이터 전송은 HTTP/1.1을 따르며 모든 엔드포인트에는 HTTPS가 필요합니다. 그래프 API는 HTTP 기반이므로 cURL, urllib 등 HTTP 라이브러리가 있는 모든 언어에서 사용할 수 있습니다. 즉 브라우저에서 직접 그래프 API를 사용할 수 있습니다. 예를 들어 브라우저에서 다음 URL은
https://graph.facebook.com/facebook/picture?redirect=false
아래 cURL 요청을 수행하는 것과 같습니다.
curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"
Facebook에서 facebook.com의 includeSubdomains HSTS 지시문도 활성화했지만 그래프 API 호출에 악영향을 미치지 않습니다.
호스트 URL
거의 모든 요청이 graph.facebook.com 호스트 URL에 전달됩니다. 한 가지 예외는 graph-video.facebook.com을 사용하는 동영상 업로드입니다.
액세스 토큰
액세스 토큰을 사용하면 앱에서 그래프 API에 액세스할 수 있습니다. 거의 모든 그래프 API 엔드포인트에는 일종의 액세스 토큰이 필요하므로 엔드포인트에 액세스할 때마다 요청에 액세스 토큰을 포함해야 할 수도 있습니다. 액세스 토큰은 일반적으로 두 가지 기능을 수행합니다.
- 앱에서 사용자의 비밀번호가 없어도 사용자의 정보에 액세스할 수 있습니다. 예를 들어 앱에서 기능을 수행하려면 사용자의 이메일이 필요합니다. 사용자가 앱에서 Facebook으로부터 이메일 주소를 가져오는 데 동의할 경우 사용자는 앱에 Facebook 비밀번호를 입력하지 않더라도 이메일 주소를 가져올 수 있습니다.
- Facebook에서는 앱, 앱 사용자, 사용자가 앱에 액세스할 수 있도록 허용한 데이터의 유형을 식별할 수 있습니다.
자세한 내용은 액세스 토큰 문서를 참조하세요.
노드
노드는 고유 ID를 갖는 개별 개체입니다. 예를 들어 각각 Facebook의 사용자를 나타내는 고유한 ID를 갖는 수많은 사용자 노드 개체가 있습니다. 페이지, 그룹, 게시물, 사진 및 댓글은 Facebook 소셜 그래프에서 사용하는 노드의 일부일 뿐입니다.
다음의 cURL 예시는 사용자 노드에 대한 호출을 나타냅니다.
curl -i -X GET \ "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"
이 요청은 기본적으로 JSON 형식으로 다음 데이터를 반환합니다.
{
"name": "Your Name",
"id": "YOUR-USER-ID"
}노드 메타데이터
노드 개체(예: 사용자, 페이지, 사진)의 필드 이름, 설명, 데이터 유형 등을 포함한 모든 필드의 리스트를 가져올 수 있습니다. GET 요청을 개체 ID로 보내고 metadata=1 매개변수를 포함하세요.
curl -i -X GET \
"https://graph.facebook.com/USER-ID?
metadata=1&access_token=ACCESS-TOKEN"결과 JSON 응답에는 특정 노드에 대해 지원되는 모든 에지를 나열하는 metadata 속성이 포함됩니다.
{
"name": "Jane Smith",
"metadata": {
"fields": [
{
"name": "id",
"description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
"type": "numeric string"
},
{
"name": "age_range",
"description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
"type": "agerange"
},
{
"name": "birthday",
"description": "The person's birthday. This is a fixed format string, like `MM/DD/YYYY`. However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
"type": "string"
},
.../me
/me 노드는 현재 API 호출을 보내는 데 사용하는 액세스 토큰을 보유한 사용자나 페이지의 개체 ID로 변환하는 특수한 엔드포인트입니다. 사용자 액세스 토큰이 있으면 다음을 사용하여 사용자 이름과 ID를 가져올 수 있습니다.
curl -i -X GET \ "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"
에지
에지는 두 노드 간의 연결입니다. 예를 들어 사용자 노드는 사진을 연결할 수 있고 사진 노드는 댓글을 연결할 수 있습니다. 다음의 cURL 예시는 사용자가 Facebook에 게시한 사진 리스트를 반환합니다.
curl -i -X GET \ "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"
반환된 각 ID는 사진 노드와 Facebook에 업로드된 시점을 나타냅니다.
{
"data": [
{
"created_time": "2017-06-06T18:04:10+0000",
"id": "1353272134728652"
},
{
"created_time": "2017-06-06T18:01:13+0000",
"id": "1353269908062208"
}
],
}필드
필드는 노드 속성입니다. 노드나 에지를 쿼리하면 기본적으로 위의 예에 표시된 대로 필드 세트가 반환됩니다. 하지만 fields 매개변수를 사용하고 각 필드를 나열하여 반환할 필드를 지정할 수 있습니다. 이렇게 하면 기본값이 덮어쓰이고 지정한 필드와 (항상 반환되는) 개체의 ID만 반환됩니다.
다음의 cURL 요청에는 fields 매개변수와 사용자 이름, 이메일 및 프로필 사진이 포함됩니다.
curl -i -X GET \ "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"
반환된 데이터
{
"id": "USER-ID",
"name": "EXAMPLE NAME",
"email": "EXAMPLE@EMAIL.COM",
"picture": {
"data": {
"height": 50,
"is_silhouette": false,
"url": "URL-FOR-USER-PROFILE-PICTURE",
"width": 50
}
}
}복잡한 매개변수
대부분의 매개변수 유형은 bool, string, int와 같이 간단한 기본 형식이지만 요청에서 지정할 수 있는 list 및 object 유형도 있습니다.
list 유형은 JSON 구문으로 지정됩니다. 예: ["firstitem", "seconditem", "thirditem"]
object 유형도 JSON 구문으로 지정됩니다. 예: {"firstkey": "firstvalue", "secondKey": 123}
게시, 업데이트 및 삭제
Facebook 공유 가이드에서 사용자 Facebook에 게시하는 방법을 알아보거나 페이지 API 문서에서 페이지의 Facebook 피드에 게시하는 방법을 알아보세요.
일부 노드는 POST 작업으로 필드를 업데이트할 수 있습니다. 예를 들어 email 필드를 업데이트하는 방법은 다음과 같습니다.
curl -i -X POST \ "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"
쓰기 후 읽기
엔드포인트 만들기 및 업데이트의 경우 그래프 API는 성공적으로 게시되거나 업데이트된 개체를 즉시 읽고 해당 읽기 엔드포인트에서 지원하는 모든 필드를 반환할 수 있습니다.
기본적으로 생성되거나 업데이트된 개체의 ID가 반환됩니다. 응답에 자세한 정보를 포함하려면 요청에 fields 매개변수를 포함하고 반환하려는 필드를 나열하세요. 예를 들어 페이지의 피드에 'Hello' 메시지를 게시하려면 다음과 같이 요청할 수 있습니다.
curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello& fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
이렇게 하면 지정된 필드가 다음과 같이 JSON 형식 응답으로 반환됩니다.
{
"created_time": "2017-04-06T22:04:21+0000",
"from": {
"name": "My Facebook Page",
"id": "PAGE-ID"
},
"id": "POST_ID",
"message": "Hello",
}엔드포인트가 쓰기 후 읽기를 지원하는지, 어떤 필드를 사용할 수 있는지 확인하려면 각 엔드포인트의 참조 문서를 참조하세요.
오류
어떤 이유로든 읽기에 실패하면(예: 존재하지 않는 필드 요청) 그래프 API는 표준 오류 응답을 포함하여 응답을 보냅니다. 자세한 내용은 오류 처리 가이드를 참조하세요.
일반적으로 개체 ID에 DELETE 작업을 실행하면 페이지, 사진 노드 등의 노드를 삭제할 수 있습니다.
curl -i -X DELETE \ "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"
일반적으로 내가 만든 노드만 삭제할 수 있지만 삭제 작업의 요구 사항은 각 노드의 참조 가이드를 확인하세요.
Webhooks
Webhooks를 구독하면 노드 변경 사항이나 노드와의 인터랙션에 대해 알림을 받을 수 있습니다. Webhooks를 참조하세요.
버전
그래프 API는 분기별로 릴리스되어 여러 버전이 있습니다. 요청 경로 시작 시 'v'와 버전 번호를 추가하여 호출에서 버전을 지정할 수 있습니다. 예를 들어 버전 4.0을 호출하는 방법은 다음과 같습니다.
curl -i -X GET \
"https://graph.facebook.com/v4.0/USER-ID/photos
?access_token=ACCESS-TOKEN"버전 번호를 포함하지 않으면 기본적으로 사용 가능한 가장 오래된 버전을 지정하므로 요청에 버전 번호를 포함하는 것이 좋습니다.
버전에 대한 자세한 내용은 버전 관리 가이드를 참조하고, 사용 가능한 모든 버전에 대한 자세한 내용은 그래프 API 변경 사항을 참조하세요.
Facebook API, SDK 및 플랫폼
Facebook의 다양한 API, SDK 및 플랫폼을 사용하여 모든 플랫폼에서 인터페이스를 연결하고 개발하세요.
다음 단계
그래프 API 시작하기 – 그래프 탐색기 도구를 사용하여 Facebook 소셜 그래프를 살펴보고 몇 가지 요청을 실행하여 데이터를 가져옵니다.