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

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

HTTP/1.1

Все данные передаются по протоколу HTTP/1.1, а для работы эндпойнтов необходим HTTPS. Кроме того, мы включили HSTS includeSubdomains на сайте facebook.com, но это не повлияет на ваши вызовы API Graph.

URL хоста

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

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

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

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

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

Как работают маркеры

Маркеры доступа работают по протоколу OAuth 2.0. OAuth 2.0 позволяет таким объектам, как пользователь или Страница, авторизовать маркеры. Как правило, это выполняется в рамках веб-интерфейса. После авторизации приложения могут получать доступ к информации с помощью этих маркеров.

Например, это приложение просит пользователя разрешить доступ к его фото, видео и эл. адресу:

Как мы видим, это интерфейс Facebook. Пользователь вошел в свой аккаунт с помощью интерфейса, благодаря чему мы можем авторизовать этого человека. Если человек продолжит работу в приложении, мы обменяем старый маркер (маркер приложения) на новый (маркер пользователя). Затем с помощью нового маркера пользователя приложение будет выполнять запросы API Graph, но получит доступ только к фото, видео и эл. адресу именно этого пользователя.

Это важное свойство маркеров доступа. ID приложения и пользователя (а также другие параметры) зашифрованы в самом маркере. С помощью этих ID мы отслеживаем, к каким данным пользователь предоставил доступ приложению. Например, если открыть маркер, после того как пользователь предоставит разрешение, вы увидите следующую информацию:

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

"Вход через Facebook"

В рамках OAuth 2.0 происходит много перенаправлений, запросов учетных данных и обменов маркерами. Чтобы помочь вам в работе с ними, мы разработали продукт "Вход через Facebook". "Вход через Facebook" предлагает удобные функции и методы для всех наших SDK, благодаря которым работать с маркерами доступа не составляет труда.

Подробнее о маркерах доступа и "Входе через Facebook", а также о том, как создать собственное решение, читайте в документации о "Входе через Facebook".

Чтение

Узлы

Операции чтения практически всегда начинаются с узла. Узел — это отдельный объект с уникальным ID. Есть много объектов Страницы, у каждого из которых свой ID. Так, ID Страницы Coca-Cola — 820882001277849. Чтобы прочитать тот или иной узел, необходимо запросить ID конкретного объекта. Если вам нужно прочитать узел Страницы Coca-Cola, запросите его ID:

GET https://graph.facebook.com/820882001277849

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

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

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

У узлов есть границы контекста, с помощью которых можно получить подборки других связанных с ними узлов. Чтобы прочитать границу контекста, необходимо указать в пути ID узла и название границы контекста. Например, у узлов /page есть граница контекста /feed, которая возвращает все узлы публикаций на Странице. Вот как можно посмотреть все публикации на Странице Coca-Cola с помощью границы контекста:

GET https://graph.facebook.com/820882001277849/feed

Отклик JSON будет выглядеть примерно так:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

Обратите внимание, что отклик содержит не только ID узлов публикаций в подборке, но и поля created_time и message. Так и должно быть. В большинстве границ контекста по умолчанию есть одно или несколько полей.

Поля

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

Например, в этой справочной статье указано, какие поля можно запрашивать при чтении узла страницы. Получить поля about, fan_count и website Страницы Coca-Cola можно следующим образом:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

Отклик будет выглядеть так:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

С помощью границ контекста, которые позволяют получить подборки объектов, также можно открыть поля каждого объекта в подборке. Предположим, вы воспользовались границей контекста /photos, чтобы получить все узлы фото на Странице Coca-Cola:

GET https://graph.facebook.com/820882001277849/photos

Отклик будет выглядеть примерно следующим образом:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

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

Предположим, вы хотите получить поля height, width и link (URL) каждого узла фото, возвращенного границей контекста /photos:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

Отклик будет выглядеть следующим образом:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

Обратите внимание, что если вы используете расширение полей, вы можете указать границу контекста в параметре fields.

Расширение поля

Если вы протестировали запрос GET /page/photos в Graph API Explorer, вы могли заметить, что запрос вернул более трех объектов и разбил результаты на страницы. Так происходит с большинством границ контекста. Об отображении результатов мы поговорим позже, а сейчас посмотрим, как с помощью расширения поля можно не только выполнять вложенные запросы, но и ограничивать и упорядочивать результаты.

Ограничение результатов

Эта функция позволяет ограничивать количество объектов, отображаемых в каждом наборе результатов. Чтобы ограничить результаты, добавьте аргумент .limit() в каждое поле или границу контекста.

Например, если выполнить запрос GET к границе контекста /feed Страницы Coca-Cola, в результатах могут быть сотни публикаций. Ограничить количество публикаций на каждой странице результатов можно следующим образом:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

Запрос возвращает все публикации со Страницы Coca-Cola, но на каждой странице с результатами будет не более трех объектов. Обратите внимание, что указывать границу контекста Ленты нужно не в URL пути (/page/feed), а в параметре fields (?fields=feed), что позволит вам добавить аргумент .limit(3).

Запрос дает следующие результаты:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

Как мы видим, на каждой странице результатов представлено не более трех объектов, но в отклике есть поле next и URL, с помощью которых можно открыть следующую страницу.

Упорядочивание результатов

Вы можете упорядочить результаты по времени создания объектов. Для этого добавьте аргумент .order() с одним из следующих значений в поле или границу контекста.

  • chronological — упорядочивает результаты от старых объектов к новым.
  • reverse_chronological — упорядочивает результаты от новых объектов к старым.

Например, давайте попробуем собрать все комментарии к одной из видеопубликаций на Странице Coca-Cola (1809938745705498), упорядочить результаты хронологически (от старых к новым) и при этом отобразить не более трех объектов на каждой странице с результатами:

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

Чтобы применить аргумент к границе контекста, необходимо указать границу контекста в параметре fields. Таким образом, вы можете объединить аргументы .limit() и .order() в одном поле или одной границе контекста.

Вы получите следующие результаты:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

Публикация

Большинство границ контекста позволяют публиковать объекты в подборке узла. Для этого нужно выполнить запрос POST к границе контекста узла. Например, опубликовать комментарий к фото можно с помощью границы контекста /comments узла фото:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

Если запрос будет выполнен успешно, большинство границ контекста вернут ID опубликованного объекта. Как правило, это сочетание ID опубликованного объекта и новой строки ID:

{
  "id": "1809938745705498_1810399758992730"
}

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

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

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

Обновление

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

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

Если запрос будет выполнен успешно, в результате вы получите поле success и значение true:

{
  "success": true
}

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

Удаление

Удалить узел можно с помощью операции DELETE:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

Если запрос будет выполнен успешно, в результате вы получите поле success и значение true:

{
  "success": true
}

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

Если ваши клиенты не поддерживают все методы HTTP, отправьте узлу запрос POST и включите параметр method=delete и значение, которое переопределит метод HTTP:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

Отображение результатов с разбивкой по страницам

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

Пейджинация по положению курсора

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

При чтении границы, поддерживающей пейджинацию по положению курсора, вы получите следующий отклик JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Граница с пейджинацией по положению курсора поддерживает следующие параметры.

  • before : курсор, указывающий на начало возвращенной страницы данных.
  • after : курсор, указывающий на конец возвращенной страницы данных.
  • limit : Это максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, о котором рассказано ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, что существует и десятый доступный объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ значение параметра limit совпадает с максимально допустимым значением. Это необходимо для повышения производительности. Во всех случаях API возвращает ссылки на правильную пейджинацию.
  • next : эндпойнт API Graph, который возвращает следующую страницу данных. Если не включено, это последняя страница с данными. Поскольку на пейджинацию влияют настройки видимости и конфиденциальности, страница может быть пустой и содержать только ссылку на пейджинацию next. Если ссылка next отсутствует, просмотр страниц следует прекратить.
  • previous : эндпойнт API Graph, который возвращает предыдущую страницу данных. Если этот параметр не входит в отклик, это значит, что возвращена первая страница данных.

Не храните курсоры. Курсоры могут быстро стать недействительными при добавлении или удалении элементов.

Пейджинация по времени

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

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

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

Граница с пейджинацией по времени поддерживает следующие параметры.

  • until : метка времени Unix или значение данных strtotime, указывающее на конец диапазона основанных на времени данных.
  • since : метка времени Unix или значение данных strtotime, указывающее на начало диапазона основанных на времени данных.
  • limit : Это максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, о котором рассказано ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, что существует и десятый доступный объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ значение параметра limit совпадает с максимально допустимым значением. Это необходимо для повышения производительности. Во всех случаях API возвращает ссылки на правильную пейджинацию.
  • next : эндпойнт API Graph, который возвращает следующую страницу данных.
  • previous : эндпойнт API Graph, который возвращает предыдущую страницу данных.

Для получения стабильных результатов укажите параметры since и until. Кроме того, разница во времени не должна превышать 6 месяцев.

Пейджинация по сдвигу

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

Граница с пейджинацией по сдвигу поддерживает следующие параметры.

  • offset : сдвиг начала каждой страницы на указанное количество единиц.
  • limit : Это максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, о котором рассказано ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, что существует и десятый доступный объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ значение параметра limit совпадает с максимально допустимым значением. Это необходимо для повышения производительности. Во всех случаях API возвращает ссылки на правильную пейджинацию.
  • next : эндпойнт API Graph, который возвращает следующую страницу данных. Если не включено, это последняя страница с данными. Поскольку на пейджинацию влияют настройки видимости и конфиденциальности, страница может быть пустой и содержать только ссылку на пейджинацию next. Если ссылка next отсутствует, просмотр страниц следует прекратить.
  • previous : эндпойнт API Graph, который возвращает предыдущую страницу данных. Если этот параметр не входит в отклик, это значит, что возвращена первая страница данных.

Обратите внимание, что при добавлении новых объектов в список объектов, разбитый на страницы, содержимое каждой из этих страниц изменяется.

Некоторые вызовы API не поддерживают пейджинацию на основе сдвига. Чтобы получить согласованные результаты, рекомендуем вам просматривать страницы с помощью ссылок previous и next, возвращенных в отклике на запрос.