그래프 API 참고 자료
개요
Workplace용 그래프 API는 Workplace에서 프로그래밍 방식으로 데이터를 주고받는 수단입니다. Workplace 그래프에서 개체에 대한 데이터를 쿼리할 때 사용하는 낮은 수준의 HTTP 기반 API입니다.
그래프 API는 개체가 노드로 표시되고 에지와 함께 결합되는 그래프 데이터 모델에서 아이디어를 얻어 이름을 지었습니다. 앱은 API를 통해 이런 방식으로 Workplace에서 정보에 액세스합니다. Workplace용 그래프 API를 사용하면 그래프 API의 하위 기능을 지원할 수 있습니다. 이 기능은 Workplace 커뮤니티와의 상호작용으로 제한되며 경우에 따라 성능이나 사용성을 개선하기 위한 차이가 있을 수 있습니다.
Workplace용 그래프 API 사용 방법에 대한 자세한 내용은 아래에서 확인하실 수 있습니다.
앱 만들기봇 빌드하기권한샘플그래프 API 사용
그래프 API 개체
그래프 API는 다음과 같이 구성된 Workplace 정보를 나타냅니다.
- 노드 - 사용자, 사진, 게시물, 댓글과 같은 개체입니다.
- 에지 - 게시물 파일이나 사진의 댓글과 같은 '무언가' 사이의 연결입니다.
- 필드 - 사용자 이름이나 그룹의 공개 범위와 같은 개체 메타데이터입니다.
Workplace 그래프의 모든 항목은 고유한 ID로 표시됩니다. 그룹, 멤버, 게시물, 심지어 댓글도 고유한 ID가 있으며, 이는 그래프 API에서 항목에 대한 정보를 가져오는 데 사용할 수 있습니다.
커뮤니티 관리
각 Workplace 커뮤니티는 다른 커뮤니티와 분리되어 있으므로 그래프 API만 이용해 자신이 속한 커뮤니티, 그리고 자신의 커뮤니티 멤버가 추가된 기업 간 협력 그룹에 있는 콘텐츠에 접근할 수 있습니다.
그래프 API에 액세스할 때는 커뮤니티가 그룹으로 간주됩니다. 커뮤니티는 루트 그룹으로 생각할 수 있으며, 그 아래에 모든 그룹이 하위 요소로 추가됩니다. 그래프 API에서 커뮤니티에 대한 정보를 가져오려면 커뮤니티 ID가 필요합니다. 커뮤니티 ID는 그래프 API에서 유효한 앱 액세스 토큰과 함께 HTTP GET 요청을 graph.facebook.com/community로 보내서 프로그래밍 방식으로 가져옵니다.
그래프 API 버전 관리
Workplace용 그래프 API는 그래프 API를 기반으로 빌드됩니다. 즉, 동일한 API 버전 관리 동작을 상속합니다.
그래프 API 버전은 대략 3개월마다 릴리스되고 Workplace 및 그래프 API의 모든 변경 사항은 그래프 API 변경 사항에 게시됩니다.
그래프 API로 API 호출을 보낼 때 다음과 같이 API 경로에 버전을 지정할 수 있습니다.
https://graph.facebook.com/v2.11/community/groups
그러나 사용 가능한 버전에는 다소 제한이 있습니다.
- 새로운 버전이 릴리스되면 해당 버전이 최신 API 버전이 되고 릴리스 이후로 2년간 동작이 보장됩니다.
- 앱을 만드는 시점에 최신 API 버전이 기본값으로 지정되고 해당 앱에서 사용할 수 있는 최소 API 버전이 됩니다.
- 앱은 API 호출을 보낼 때 자유롭게 API 버전을 지정할 수 있으나 사용 중단된 API 버전이나 앱의 최소 API 버전 미만인 버전으로는 호출을 보낼 수 없습니다.
- 버전이 지정되지 않은 API 호출은 해당 앱의 최소 API 버전이 기본값으로 지정됩니다.
새로운 맞춤 통합을 만들 때 사용 가능한 최소 API 버전이 그 시점의 최신 API 버전이 됩니다. 이 최소 버전은 그래프 API 호출과 Webhooks 구독에 모두 영향을 미칩니다.
플랫폼 버전 관리그래프 API 변경 사항그래프 API 버전 확인
어떤 버전을 사용하고 있는지 확실하지 않을 경우 확인하는 방법이 몇 가지 있습니다. 앱에서 사용할 수 있는 그래프 API 버전을 확인하려면 debug 매개변수를 API 호출에 추가합니다.
https://graph.facebook.com/community?debug=all
그러면 사용 중인 버전을 확인하는 추가적인 디버그 정보가 반환됩니다.
{
"name": "Example Community",
"privacy": "CLOSED",
"id": "855210357923606",
"__debug__": {
"messages": [
{
"link": "https://developers.facebook.com/docs/apps/versions/",
"message": "No API version was specified. This request defaulted to version v2.8.",
"type": "warning"
}
]
}
}
앱의 최소 API 버전 미만인 버전을 사용하려고 시도하면 debug 메시지가 알려줍니다.
https://graph.facebook.com/v2.6/community?debug=all
{
"name": "Example Community",
"privacy": "CLOSED",
"id": "855210357923606",
"__debug__": {
"messages": [
{
"link": "https://developers.facebook.com/docs/apps/versions/",
"message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
"type": "warning"
}
]
}
}
Webhooks 버전 확인
Webhooks 구독은 맞춤 통합 팝업 대화 상자를 통해 구독하는 경우 최소 API 버전을 사용합니다. 그렇지 않을 경우 구독 그래프 API 엔드포인트인 /app/subscriptions를 통해 구독의 API 버전이 지정됩니다.
구독 엔드포인트를 사용하여 각 Webhooks 필드와 주제에 적용되는 Webhooks 버전을 확인할 수 있습니다. 이 엔드포인트에는 앱 액세스 토큰이 필요합니다.
https://graph.facebook.com/v2.11/app/subscriptions
{
"data": [
{
"object": "group",
"callback_url": "https://www.example.com/callback",
"active": true,
"fields": [
{
"name": "comments",
"version": "v2.8"
},
...
Webhooks 구독을 활성화하는 방법에 따라 하나의 Webhooks 개체 내에서 각 필드가 서로 다른 버전 번호를 사용하여 페이로드를 반환할 수 있습니다.
페이로드가 예상한 형식과 다를 경우 버전 번호를 다시 한번 확인하고 필요하다면 최신 버전을 사용하여 다시 구독하세요.
액세스 토큰 사용
앱 액세스 토큰 가져오기
커뮤니티에 대한 그래프 API 호출을 보내려면 앱을 만들고 액세스 토큰을 가져와야 합니다. 이를 위해서는 새 앱을 만든 다음, 빌드하려는 기능에 필요한 권한을 부여해야 합니다.
앱을 만드는 방법과 권한 모델에 대한 자세한 내용은 권한 가이드를 참조하세요.