Graph API

Обзор

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

Название API Graph подчеркивает связь этого API с "социальным графом" — системой представления информации на Facebook. Он состоит из узлов, границ контекста и полей. С помощью узлов можно получать данные о конкретном объекте, границы контекста позволяют получать подборки объектов, связанные с отдельным объектом, а поля — получать данные об отдельном объекте или о каждом объекте в подборке. В документации как узел, так и граница контекста могут называться конечными точками. Например, "отправьте запрос GET к конечной точке User".

HTTP

Все данные передаются по протоколу HTTP/1.1, а для работы конечных точек необходим протокол HTTPS. В основе 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"

Кроме того, мы включили на сайте facebook.com директиву HSTS includeSubdomains, однако это не должно повлиять на ваши вызовы API Graph.

URL хоста

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

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

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

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

Дополнительную информацию см. в нашей документации по маркерам доступа.

Узлы

Узел — это отдельный объект с уникальным ID. Например, существует множество объектов узлов User, каждый из которых имеет свой уникальный ID и соответствует отдельному человеку на Facebook. Примерами узлов социального графа Facebook являются Page, Group, Post, Photo и Comment.

Следующий пример cURL представляет собой вызов к узлу User:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

По умолчанию этот запрос возвращает следующие данные в формате JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Метаданные узла

Для объекта узла, такого как User, Page или Photo, можно получить список всех полей с их именами, описаниями и типами данных. Отправьте запрос GET к ID объекта с параметром metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

Ответ JSON будет содержать свойство metadata со списком всех поддерживаемых полей выбранного узла:

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Узел /me — это специальная конечная точка, которая преобразуется в ID объекта человека или Страницы, маркер доступа которых используется в вызовах API. Если у вас есть маркер доступа, следующий запрос позволит получить имя и ID пользователя:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Границы контекста

Граница контекста — это связь между двумя узлами. Например, с узлом User могут быть связаны фотографии, а с узлом Photo — комментарии. В примере ниже cURL возвращает список фотографий, которые человек опубликовал на Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Каждый возвращенный ID представляет узел Photo со сведениями о том, когда именно снимок был загружен на Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Поля

Поля — это свойства узла. Когда вы запрашиваете узел или границу контекста, возвращается набор полей по умолчанию (см. примеры выше). Чтобы получить только некоторые поля, укажите их в параметре fields. Так вы получите только нужные поля и ID объекта, который всегда содержится в ответе.

В параметр fields следующего запроса cURL добавлены имя, адрес электронной почты и фото профиля пользователя.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Возвращаемые данные

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Комплексные параметры

Большинство параметров представляют собой простые значения (например, типа bool, string или int). Однако в запросах также можно использовать параметры типа list или object.

Тип list можно задать в синтаксисе JSON, например: ["firstitem", "seconditem", "thirditem"].

Тип object также можно задать в синтаксисе JSON, например: {"firstkey": "firstvalue", "secondKey": 123}.

Публикация, обновление и удаление

Информацию о том, как опубликовать что-то на странице Facebook пользователя, см. в нашем руководстве по публикации на Facebook. Сведения о публикации в ленте Страницы Facebook см. в документации по API Pages.

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

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Чтение после записи

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

По умолчанию возвращается ID созданного или обновленного объекта. Чтобы получить в ответе дополнительную информацию, добавьте в запрос параметр fields и список нужных вам полей. Например, чтобы опубликовать приветствие в ленте пользователя, можно выполнить следующий запрос:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
В примере кода выше для удобства чтения применено форматирование.

Запрос вернет указанные поля в формате JSON:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

Информацию о том, поддерживает ли конечная точка чтение после записи и какие имеются поля, см. в справочной документации по каждой конечной точке.

Ошибки

Если по какой-либо причине считать данные не удалось (например, в запросе указано несуществующее поле), API Graph вернет стандартное сообщение об ошибке. Дополнительные сведения см. в нашем руководстве по обработке ошибок.

Удалить узел (например, Post или Photo) обычно можно с помощью операции DELETE с указанием ID объекта:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

Как правило, вы можете удалять только узлы, созданные вами. Подробнее о требованиях к операциям удаления см. в справке по конкретному узлу.

Webhooks

Чтобы получать уведомления об изменениях в узлах и взаимодействиях с узлами, подпишитесь на Webhooks. См. раздел Webhooks.

Версии

API Graph имеет несколько версий. Они выпускаются ежеквартально. Чтобы указать версию в вызове, добавьте букву "v" и номер версии в начало пути запроса. Например, так можно вызвать API версии 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

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

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

API, SDK и платформы Facebook

Для подключения различных интерфейсов и разработки для разных платформ вы можете использовать различные API, SDK и платформы Facebook.

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

Приступайте к работе с API Graph: ознакомьтесь с социальным графом Facebook с помощью инструмента Graph Explorer и выполните пару запросов, чтобы получить данные.