Graph API

Пакетные запросы

Позволяют отправить несколько вызовов API Graph в одном запросе HTTP. Зависимые операции обрабатываются последовательно, а независимые — параллельно. После выполнения всех операций вы получаете сводный ответ и HTTP-подключение закрывается.

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

Ограничения

  • В одном пакете можно отправить до 50 запросов. Обратите внимание: механизм ограничения ресурсов и количества вызовов API засчитывает каждый из этих запросов отдельно. Например, пакет из 10 вызовов API считается за 10 вызовов. Аналогичным образом определяется количество ресурсов ЦП, использованных на выполнение этих вызовов. Дополнительные сведения см. в статье об ограничении числа обращений.
  • Пакетный запрос не может содержать несколько групп объявлений, относящихся к одной кампании. Узнать больше о пакетных запросах API Marketing можно в этой статье.

Пакетный запрос

Пакетный запрос содержит объект JSON, состоящий из массива отдельных запросов. Он возвращает массив логических ответов HTTP, представленный в виде массивов JSON. Каждый ответ содержит код статуса, а также может включать в себя массив заголовков и текст (строку в кодировке JSON).

Чтобы сделать пакетный запрос, отправьте на конечную точку объект JSON в параметре batch запроса POST.

POST /ENDPOINT?batch=[JSON-OBJECT]

Пример пакетного запроса

В этом примере мы запрашиваем информацию о двух Страницах, которыми управляет наше приложение.

Для удобства чтения применено форматирование.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

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

Пример ответа

Поле body содержит строку объекта в кодировке JSON.

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Сложные пакетные запросы

Операции, в которых используются разные методы HTTP, также можно добавить в один пакетный запрос. Операции GET и DELETE могут включать в себя только поля relative_url и method, а в операциях POST и PUT может содержаться необязательное поле body. Тело запроса должно иметь вид неформатированной строки HTTP-запроса POST (аналогично строке запроса URL).

Пример запроса

Этот запрос за раз создает публикацию на управляемой нами Странице и в ее ленте. Для этого у нас должно быть разрешение на публикацию на этой Странице.

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

Результат может быть следующим:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

Запрос из следующего примера создает новое объявление для некой рекламной кампании, а затем получает сведения об этом объекте. Обратите внимание: для параметра body используется URL-кодирование.

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

Код в примере ниже добавляет несколько страниц в Business Manager:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Здесь:

  • <ACCESS_TOKEN> — маркер доступа с разрешением business_management;
  • <BUSINESS_ID> — идентификатор Business Manager, с которым должны быть связаны страницы;
  • <PAGE_ID_n> — идентификаторы связываемых страниц.

Ошибки

Иногда операции в запросе могут выдавать ошибки (например, если у вас нет разрешения на их выполнение). В этом случае возвращается ответ, похожий на стандартный ответ API Graph, но с синтаксисом ответа на пакетный запрос:

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

При этом прочие запросы, добавленные в пакет, будут выполнены успешно и вернут стандартный ответ с кодом статуса 200.

Тайм-ауты

Если пакетный запрос слишком велик или содержит слишком много компонентов и выполнение всех входящих в него операций занимает слишком много времени, может произойти тайм-аут. В этом случае пакетный запрос будет выполнен частично. Ответы на успешно выполненные запросы будут выглядеть обычным образом с кодом состояния 200, а на невыполненные запросы придет ответ null. Запросы, которые не удалось выполнить, можно повторить.

Пакетные вызовы с использованием формата JSONP

Как и все остальные компоненты API Graph, API Batch поддерживает формат JSONP. Чтобы задать функцию обратного вызова JSONP, используйте параметр строки запроса или формы POST callback.

Использование нескольких маркеров доступа

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

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

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

Загрузка двоичных данных

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

В этом примере показано, как загрузить две фотографии в одном пакетном вызове:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->