그래프 API 참고 자료

개요

Workplace의 그래프 API는 Workplace에서 프로그래밍 방식으로 데이터를 주고받는 수단입니다. Workplace 그래프에서 개체에 대한 데이터를 쿼리할 때 사용하는 낮은 수준의 HTTP 기반 API입니다.

그래프 API는 개체가 노드로 표시되고 에지와 함께 결합되는 그래프 데이터 모델에서 아이디어를 얻어 이름을 지었습니다. 앱은 API를 통해 이런 방식으로 Workplace에서 정보에 액세스합니다. Workplace용 그래프 API를 사용하면 Facebook용 그래프 API의 하위 기능을 지원할 수 있습니다. 이 기능은 Workplace 커뮤니티와만 상호작용하며 경우에 따라 성능이나 사용성을 개선하기 위한 차이가 있을 수 있습니다.

Workplace 그래프 API 개체

다음의 노드는 맞춤 통합 또는 타사 앱 액세스 토큰을 사용하여 Workplace 그래프 API를 통해서 액세스할 수 있습니다.

커뮤니티

Workplace 커뮤니티. Workplace 그래프 API 호출의 루트 그룹.

그룹

Workplace 그룹.

게시물

그룹 또는 멤버 프로필에 게시된 게시물.

멤버

특정 Workplace 사용자의 계정. 이 노드는 이 사용자가 보내고 받은 메시지를 확인하고 수정하는 데 사용할 수도 있습니다.

기술

멤버 프로필에 추가된 기술.

이벤트

Workplace 커뮤니티 또는 그룹 이벤트.

카테고리

중요한 회사 콘텐츠를 저장하기 위한 지식 라이브러리의 카테고리.

사람 세트

기준 또는 리스트를 사용하여 정의된 사람 모음.

신고된 콘텐츠

Workplace에서 관리자가 검토해야 할 신고된 콘텐츠.

근무조

Workplace에 있는 시간당 근로자의 근무조 일정 데이터.

설문조사

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는 Facebook 플랫폼용 그래프 API를 기반으로 빌드됩니다. 즉, Facebook에서 사용하는 것과 동일한 API 버전 관리 동작이 상속됩니다.

그래프 API 버전은 대략 3개월마다 릴리스되고 Workplace 및 Facebook 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 버전을 확인하려면 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"
              },
      ...
    

액세스 토큰 사용

앱 액세스 토큰 가져오기

커뮤니티에 대한 그래프 API 호출을 보내려면 앱을 만들고 액세스 토큰을 가져와야 합니다. 이를 위해서는 새 맞춤 통합을 만든 다음, 빌드하려는 기능에 필요한 권한을 부여해야 합니다.

앱을 만드는 방법과 권한 모델에 대한 자세한 내용은 권한 가이드를 참조하세요.

멤버 액세스 토큰 가져오기

앱 액세스 토큰을 사용하면 커뮤니티 전체의 개체에 액세스하고 상호작용할 수 있지만 멤버 액세스 토큰을 사용하면 서비스에서 특정 계정 대신 호출을 보낼 수 있습니다.

특정 멤버의 /member_id 엔드포인트로 GET 요청을 보내고, 관리자 액세스 토큰을 사용하여 추가적인 필드인 impersonate_token을 요청하면 멤버 액세스 토큰을 가져올 수 있습니다.

이 기능을 사용하려면 호출을 보내는 앱에 가장 권한이 필요합니다.