Справка по Graph API

Обзор

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

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

Дополнительную информацию об использовании Graph API для Workplace можно найти ниже:

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

Следующие узлы доступны через Graph API для Workplace. Для доступа ко всем узлам следует использовать маркер доступа для пользовательской интеграции.

Сообщество

Сообщество Workplace. Корневая группа для вызовов Graph API для 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. Поэтому для него действует та же система версий.

Версии Graph API выпускаются примерно раз в три месяца, а изменения, внесенные в API для Workplace и в целом публикуются в журнале изменений 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 для сообщества, нужно создать приложение и получить маркер доступа. Для этого нужно сначала создать новое приложение, а затем предоставить приложению необходимые разрешения для реализации нужных функций.

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