Справка по Graph API

Обзор

Graph API для Workplace позволяет обмениваться данными с Workplace программным путем. Это низкоуровневый API на базе HTTP, с помощью которого можно запрашивать данные об объектах в графе Workplace.

Название Graph API подчеркивает связь этого API с моделью данных типа "граф", в которой объекты представлены в виде вершин (узлов), соединенных ребрами (границами контекста). Приложения получают доступ к информации в Workplace через API именно в такой форме. Функции Graph API для Workplace представляют собой подмножество функций API Graph для Facebook. Они ограничиваются взаимодействием с сообществом Workplace, причем некоторые изменены для повышения производительности или удобства работы.

Объекты Graph API для Workplace

Через Graph API для Workplace доступны перечисленные ниже узлы. Используйте маркер доступа пользовательской интеграции или стороннего приложения.

Сообщество

Сообщество Workplace. Корневая группа для вызовов Graph API для Workplace.

Группы

Группа Workplace.

Публикации

Публикация в группе или профиле участника.

Участники

Аккаунт пользователя Workplace. Этот узел также позволяет просматривать и редактировать сообщения, получаемые и отправляемые пользователем.

Навыки

Навык, добавленный в профиль участника.

Мероприятие

Мероприятие сообщества или группы Workplace.

Категория

Категория в Библиотеке знаний для хранения важного контента компании.

Группа пользователей

Совокупность пользователей, определенная критериями или списками.

Материалы с жалобами

Контент на Workplace, отправленный на проверку администратором.

Смены

Данные графика смен для почасовых работников на Workplace.

Опрос

Опросы, созданные на Workplace.

Экспорт данных

Задачи экспорта данных для массового экспорта из Workplace.

Чтобы посмотреть, как вызовы Graph API используются в различных сочетаниях для решения тех или иных задач, обратитесь к примерам приложений.

Использование Graph API

Объекты Graph API

Graph API — это система представления информации в Workplace, которая состоит из следующих элементов:

• узлы — объекты (например, пользователь, фото, публикация или комментарий);
• границы контекста — элементы, отображающие связи между объектами (например, файл в публикации или комментарии к фото);
• поля — метаданные объектов (например, имя человека или уровень конфиденциальности группы).

Все элементы графа Workplace имеют уникальные ID. Они есть у групп, участников, публикаций и даже комментариев. По ID можно получать информацию об объектах из Graph API.

Управление сообществом

Каждое сообщество Workplace существует отдельно от других, поэтому с помощью Graph API можно обращаться только к контенту в своем сообществе, а также в группах для сотрудничества, в которые добавлены участники этого сообщества.

В контексте использования Graph API сообщество считается группой. Его можно представить как корневую группу, в которую все ваши группы добавлены как дочерние. Чтобы получить информацию о сообществе через Graph API, нужен ID сообщества. Его можно получить из Graph API программным путем, выполнив запрос HTTP GET к узлу graph.facebook.com/community и указав действительный маркер доступа приложения.

Версии Graph API

Graph API для Workplace построен на основе Graph API для платформы Facebook. Поэтому для него действует та же система версий.

Версии Graph API выпускаются примерно раз в три месяца, а изменения, внесенные в API как для Workplace, так и для Facebook, публикуются в журнале изменений Graph API.

При вызове Graph API версию можно указать в пути следующим образом:

      https://graph.facebook.com/v2.11/community/groups
    

Однако существует ряд ограничений на доступность версий.

• После выпуска новой версии API она становится текущей и будет гарантированно работать в течение двух лет.
• Когда вы создаете приложение, оно использует версию API, которая была текущей на момент его создания. Это минимальная версия API, доступная приложению.
• Приложения могут указывать версию API в вызовах, но не могут вызывать упраздненные версии или версии старше минимальной.
• Если версия не указана, по умолчанию вызывается минимальная версия API для этого приложения.

Когда создается пользовательская интеграция, минимальной доступной версией API для нее становится текущая версия на момент создания. Она является минимальной как для вызовов Graph API, так и для подписок Webhooks.

Проверка версии Graph API

Проверить используемую версию можно несколькими способами. Например, можно добавить параметр debug в вызов Graph 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, а если с помощью конечной точки /app/subscriptions Graph API — указанная версия API.

Проверить используемую версию Webhooks для каждого поля и темы можно с помощью конечной точки subscriptions. Для запроса к ней требуется маркер доступа приложения.

      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"
              },
      ...
    

Использование маркеров доступа

Получение маркера доступа приложения

Чтобы выполнять вызовы Graph API для сообщества, нужно создать приложение и получить маркер доступа. Для этого нужно сначала создать пользовательскую интеграцию, а затем предоставить приложению разрешения для реализации нужных функций.

Подробные сведения о создании приложений и о модели разрешений см. в руководстве по разрешениям.

Получение маркера доступа участника

Маркер доступа приложения позволяет приложению обращаться к объектам сообщества и работать с ними, а маркер доступа участника позволяет службе выполнять вызовы от имени определенного аккаунта.

Чтобы получить маркер доступа участника, выполните запрос GET к конечной точке /member_id для этого участника, используя маркер доступа администратора и запросив дополнительное поле impersonate_token.

При этом приложению, выполняющему вызов, требуется разрешение выдавать себя за другого пользователя.