Обзор

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

Основы

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

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

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

HTTP

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

https://graph.facebook.com/facebook/picture?redirect=false

...это то же самое, что и выполнить следующий запрос cURL:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

Маркеры доступа

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

  • почти для всех запросов API Graph необходим маркер доступа; и
  • самый простой способ получить маркер доступа — интегрировать Вход через Facebook.

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

Структура

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

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

URL хоста

Почти все запросы передаются в URL хоста graph.facebook.com. Единственным исключением являются загрузки видео, которые используют для этого graph-video.facebook.com.

ID объектов

Узлы — это отдельные объекты, у каждого из которых есть уникальный ID, поэтому чтобы получить информацию о каком-то узле, необходимо запросить его ID. Например, ID официальной Страницы Facebook — 20531316728. Чтобы получить о ней информацию, запросите ее ID:

GET graph.facebook.com
  /20531316728

Если вам нужно получить конкретные данные (поля) об узле, включите параметр fields и укажите, какие поля должны быть в отклике. Согласно справочной статье об узле Страницы, при чтении объекта Страницы можно получить поле cover, которое представляет фото обложки Страницы. Запрос будет выглядеть следующим образом:

GET graph.facebook.com
  /20531316728?fields=cover

У большинства узлов есть границы контекста, с помощью которых можно получить подборки объектов, связанных с этим узлом. Чтобы запросить границу контекста следует указать как ID узла, так и его название. В справочной статье об объекте Страницы можно узнать о границе контекста photos, которая возвращает все объекты фото, принадлежащие Странице. Таким образом, чтобы получить сведения о всех фото, принадлежащих Странице Facebook, следует запросить границу контекста photos узла:

GET graph.facebook.com
  /20531316728/photos

Некоторые узлы позволяют обновлять поля с помощью операций POST. Например, администратор Страницы Facebook может обновить поле description следующим образом:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

Как правило, с помощью границ контекста можно публиковать новые объекты в подборках узла. Для этого нужно выполнить операции POST. Опубликовать фото в подборке фото, принадлежащих Странице Facebook, можно следующим образом:

POST graph.facebook.com
  /20531316728/photos

Разумеется, для публикации объекта в подборке необходимы дополнительные поля об этом объекте, например URL фото, заголовок или описание. В справочных статьях о границе контекста можно узнать, какие поля обязательны, а какие нет.

Удалить объект можно с помощью операции DELETE с ID объекта:

DELETE graph.facebook.com
  /20531316728

Версии

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

Это очень просто: достаточно добавить в начало пути запроса букву v, после которой следует указать номер версии. Вот, например, вызов версии 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

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

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

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

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