Справка по API Graph

Обзор

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

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

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

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

Сообщество

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

Группы

Группа Workplace.

Публикации

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

Участники

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

Навыки

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

Мероприятие

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

Категория

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

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

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

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

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

Смены

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

Опрос

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

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

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

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

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

Объекты API Graph

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

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

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

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

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

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

Версии API Graph

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

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

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

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

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

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

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

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

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

      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"
               }
            ]
         }
      }
    

Проверка версии Webhook

Если подписка Webhook была настроена с помощью всплывающего диалогового окна "Пользовательская интеграция", используется минимальная версия API, а если с помощью конечной точки /app/subscriptions API Graph — указанная версия API.

Проверить используемую версию Webhook для каждого поля и темы можно с помощью конечной точки 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"
              },
      ...
    

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

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

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

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

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

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

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

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