Обзор API Graph

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

Основы

Название API Graph подчеркивает связь этого API с Social Graph, системой представления данных на Facebook, которая состоит из следующих элементов:

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

API Graph основан на протоколе HTTP и работает с любым языком, в котором есть библиотека HTTP (например, cURL, urllib). О том, как это можно использовать, вы узнаете из раздела ниже. Для начала следует сказать, что API Graph можно открывать в браузере. Например, запрос API Graph полностью соответствует следующему:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

В большинство запросов API Graph необходимо добавлять маркеры доступа, генерируемые приложением. Для этого необходимо интегрировать «Вход через Facebook».

В этой главе рассказывается, как API Graph считывает и публикует данные в системе Social Graph.

Структура API Graph

Подробные сведения о структуре API Graph представлены в руководстве «Использование API Graph». Общий принцип: для чтения данных из API необходимо отправлять HTTP-запросы GET на узлы или границы между этими узлами.

Запросы, отправленные в API, передаются по адресу graph.facebook.com — кроме запросов на загрузку видео, для которых используется адрес graph-video.facebook.com.

ID объектов

Каждому узлу назначен уникальный ID, который используется для получения доступа к этому узлу через API Graph. Структура или формат ID узлов/объектов нигде не задокументированы, поскольку со временем они, скорее всего, изменятся. Приложениям не следует делать каких-либо предположений, исходя из нынешней структуры.

Ниже показано, как с помощью ID отправить запрос для узла:

GET graph.facebook.com
  /{node-id}

или границу:

GET graph.facebook.com
  /{node-id}/{edge-name}

Для создания публикации с помощью API, как правило, нужно отправить HTTP-запрос POST с параметрами на узел:

POST graph.facebook.com
  /{node-id}

или границу:

POST graph.facebook.com
  /{node-id}/{edge-name}

Чтобы удалить публикацию с помощью API, нужно отправить HTTP-запрос DELETE (и выполнить обновление с помощью запроса POST) на эндпойнт, с которого была создана публикация.

Версии API

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

Некоторые операции, например публикация в пределах границы или некоторые поля в узле, могут быть базовыми, в то время как вся граница или узел базовыми не являются. Базовые API помечены символом в справочных статьях по API Graph.

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

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

Это очень просто: достаточно добавить идентификатор версии в начало пути запроса. Пример вызова версии v2.2:

GET graph.facebook.com
  /v2.2/me

Общая форма запроса, которая подходит для всех версий:

GET graph.facebook.com
  /vX.Y/{request-path}

где X.Y — это нужная версия. Полный список доступных версий опубликован в нашем журнале изменений. Поскольку во всех справочных статьях по API Graph отдельно приводятся инструкции по каждой версии API, следите за тем, чтобы выбрать раздел для нужной вам версии. Некоторые узлы и границы отсутствуют в одних версиях и присутствуют в других.

А теперь попробуем создать запрос API, чтобы вы увидели, насколько это просто.

Загрузка Graph API Explorer

Чтобы обучиться работе с API Graph, проще всего использовать Graph API Explorer, низкоуровневый инструмент для создания запросов, добавления и удаления данных. Рекомендуем использовать его каждый раз при интеграции приложения с Facebook. Теперь вам нужно перейти в Graph API Explorer.

Graph API Explorer

Генерирование базового маркера доступа пользователя

Если вы захотите разработать приложение, вам понадобится информация о маркерах доступа и о том, как сгенерировать их в процессе «Входа через Facebook». Однако сейчас вы можете очень быстро получить этот маркер с помощью Graph API Explorer:

  1. Нажмите кнопку Get Token в верхнем правом углу окна Explorer.
  2. Выберите пункт Get User Access Token.
  3. В отобразившемся диалоге не нужно устанавливать никаких галочек: просто нажмите синюю кнопку Get Access Token.
  4. Отобразится диалог «Вход через Facebook». Для продолжения работы нажмите OK.

Создание первого запроса

Теперь вы готовы создать свой первый запрос API Graph. Начнем с запроса на чтение данных. В текстовом поле рядом с раскрывающимся списком GET (назовем его «полем пути») удалите существующий текст и введите «me»:

Нажмите кнопку «Отправить». Обработка запроса займет несколько минут, однако уже сейчас в панели отклика отображается целый набор данных. Отображаемые данные зависят от настроек конфиденциальности, заданных в вашем профиле; однако в любом случае там будут отображаться базовые поля:

Запрос, который вы только что задали в Graph API Explorer, полностью соответствует следующему запросу API Graph типа read:

GET graph.facebook.com
  /me

/me — это особый эндпойнт, который преобразуется в ID человека, чей маркер доступа используется для создания запроса.

Поздравляем! Ваш первый запрос API Graph успешно отправлен.

Получение разрешений на публикацию

А теперь попробуем создать публикацию на Facebook с помощью API Graph. Эта функция может вам понадобиться, только если вы планируете создать индивидуальное поле для публикаций в своем приложении и не собираетесь использовать один из диалогов «Поделиться», доступных для Веб, iOS или Android. Чтобы использовать диалоги «Поделиться», доступные на Facebook, не требуется применять функцию «Вход через Facebook» или разрабатывать собственный интерфейс для создания публикаций из приложения.

Чтобы ознакомиться с возможностями публикации с помощью API Graph, еще раз нажмите кнопку «Получить маркер доступа», но на этот раз выберите разрешение publish_actions:

Теперь нажмите синюю кнопку «Получить маркер доступа». Снова отобразится диалог «Вход». Появится сообщение, в котором вам будет предложено разрешить Graph API Explorer создавать публикации от вашего имени. При желании в этом окне можно выбрать для этой публикации уровень конфиденциальности «Только я», чтобы только вы могли ее видеть. Однако в любом случае необходимо принять условия, представленные в этом окне, и перейти на следующий этап.

Создание публикации

Если вы запросили разрешение publish_actions, нажмите кнопку GET и в раскрывающемся списке выберите пункт POST. Введите me/feed в поле пути, а затем нажмите «Добавить поле».

В отобразившихся полях введите message в качестве «имени поля» и Hello, World в качестве «значения». Вот что у вас должно получиться:

Затем нажмите синюю кнопку «Отправить». Через несколько секунд на панели отклика вы увидите примерно такой результат:

{
  "id": "{new-post-id}"
}

Это значит, что ваша первая публикация с помощью API Graph успешно создана! Перейдите в свой профиль и удостоверьтесь, что в нем отображается эта новая публикация:

Запрос, который вы только что задали в Graph API Explorer, полностью соответствует следующему запросу API Graph типа publish:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

Дальнейшие действия

Вы изучили основные принципы работы с API Graph. Хотите узнать, для чего еще можно использовать API Graph? Для начала рекомендуем вам ознакомиться с руководствами по «Входу через Facebook» (если вы еще этого не сделали). Из него вы узнаете, как генерировать маркеры доступа, необходимые для создания комплексных запросов API Graph.