Graph API

Управление версиями на платформе

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

Управление версиями

Не во всех API и SDK используется одинаковая система управления версиями. Например, версии API Graph меняются не с той скоростью, с какой это происходит у Facebook SDK для iOS, и номера этих версий тоже разные. Все Facebook SDK поддерживают работу с разными версиями наших API. Одновременно можно использовать несколько версий API или SDK с разными функциями в каждой версии.

Какова последняя версия API Graph?

Последняя версия API Graph: v19.0

Зачем вообще нужны разные версии?

Управление версиями помогает разработчикам приложений заранее понимать, когда может измениться тот или иной API или SDK. Это полезно при веб-разработке, но в то же время очень важно при создании приложений для мобильных устройств, потому что пользователи могут не сразу обновлять свои устройства (или вообще не делать этого).

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

График выпуска новых версий

Каждая версия гарантированно сохраняет свою работоспособность в течение по крайней мере двух лет. Поддержка старой версии прекращается через два года после выпуска следующей. Например, если версия API 2.3 была выпущена 25 марта 2015 года, а версия API 2.4 — 7 августа 2015 года, то срок действия версии 2.3 завершится 7 августа 2017 года, через два года после выпуска версии 2.4.

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

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

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

Каждая новая версия всегда остается неизменной?

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

Что будет, если не указать версию API?

Вызовы, в которых версия API не указана, мы называем вызовами без версии. Предположим, текущая версия — 4.0. Вызов должен выглядеть так:

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

Тот же вызов без указания версии будет выглядеть так:

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

В вызове без версии используется версия, заданная на карточке Обновление версии API в разделе Настройки > Дополнительно В примере ниже в Панели приложений задана версия 2.10, поэтому вызов без указания версии эквивалентен следующему:

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

Мы рекомендуем по возможности всегда указывать номер версии.

Ограничения

  • Нельзя совершать вызовы API без версии к Facebook SDK для JavaScript.

Может ли приложение вызывать версии старше текущей?

Вы можете указывать в своих вызовах API более старые версии, если они доступны и ваше приложение уже вызывало их. Например, если приложение было создано после выпуска версии 2.0 и выполняет вызовы с использованием этой версии, оно сможет делать такие вызовы до тех пор, пока срок действия этой версии не истечет, даже после выпуска новых версий. Если вы создали свое приложение после выпуска версии API 2.0, но не выполняли вызовов к нему до момента выхода версии 2.2, это приложение не сможет выполнять вызовы к версиям 2.0 и 2.1. Оно сможет обращаться только к API версий 2.2 и более новых.

Управление версиями Facebook API Marketing

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

Подробнее об управлении версиями в API Marketing

Отправка запросов с указанием версии

API Graph

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

Диалоги

Версии нужно указывать не только для конечных точек API, но и для диалогов и социальных плагинов. Например, если вы хотите создать диалог входа через Facebook для веб-приложения, можно добавить в начало вызова конечной точки номер версии, которая создает этот диалог:

https://www.facebook.com/v19.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

Социальные плагины

Если вы используете версии наших социальных плагинов на базе HTML5 или xfbml, отображаемая в приложении версия будет зависеть от того, какую версию вы указали при инициализации SDK for JavaScript.

Если вы добавляете версию нашего плагина для блока iframe или по обычной ссылке, номер версии нужно добавлять в начало исходного пути к плагину:

<iframe
  src="//www.facebook.com/v19.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

Запросы с указанием версий из SDK

Если вы используете Facebook SDK для iOS, Android или JavaScript, управление версиями в вызовах в основном происходит автоматически. Обратите внимание, что между системами управления версиями в каждом SDK существуют отличия.

JavaScript

Вызывать разные версии API в SDK for JavaScript можно, только если используется путь sdk.js.

Если вы используете FB.init() в SDK for JavaScript, нужно будет указывать параметр версии, как в следующем примере:

FB.init({
  appId      : '{app-id}',
  version    : 'v19.0'
});

Если вы установили флаг версии в методе инициализации, то во все вызовы к FB.api() в начало вызываемого пути будет автоматически добавляться номер версии. То же справедливо и для всех вызываемых диалоговых окон входа через Facebook. Диалог будет создан для соответствующей версии API.

При необходимости номер версии можно переопределить, просто добавив его в начало пути конечной точки в вызов FB.api().

iOS

Каждая выпускаемая версия Facebook SDK для iOS привязывается к версии, которая доступна на день ее выхода. Это означает, что при переходе на новую версию SDK вы также переходите на актуальную версию API (хотя вы можете вручную указать любую более старую доступную версию API в параметре [FBSDKGraphRequest initWithGraphPath]). Версия API указывается при выпуске каждой очередной версии Facebook SDK для iOS.

Как и в SDK for JavaScript, номер версии указывается в начале любого вызова к API Graph через Facebook SDK для iOS. Например, если последняя текущая версия API — v2.7, то вызов /me/friends (он используется в следующем примере) фактически приведет к вызову /v2.7/me/friends:

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

Переопределить номер версии в вызове можно с помощью [FBSDKGraphRequestConnection overrideVersionPartWith].

Android

Каждая выпускаемая версия Facebook SDK для Android привязывается к версии, которая доступна на день ее выхода. Это означает, что при переходе на новую версию SDK вы также переходите на актуальную версию API (хотя вы можете вручную указать любую более старую доступную версию API в параметре GraphRequest.setVersion()). Версия API указывается при выпуске каждой очередной версии Facebook SDK для Android.

Как и в SDK for JavaScript, номер версии указывается в начале любого вызова к API Graph через Facebook SDK для Android. Например, если последняя текущая версия API — v2.7, то вызов /me (он используется в следующем примере) фактически приведет к вызову /v2.7/me:

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

Переопределить номер версии в вызове можно с помощью GraphRequest.setVersion().