Асинхронные и пакетные запросы

Используйте асинхронные запросы, чтобы создавать и отправлять сразу несколько запросов рекламы без блокировки. Задайте URL для проверки статуса запроса или для вызова, который нужно выполнить после выполнения запроса. См. справку по рекламным объявлениям.

Самый эффективный способ управления рекламой — это пакетные запросы. Используйте их для выполнения рутинных задач.

Асинхронные запросы

Вот как можно получить статус набора асинхронных запросов:

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Эта команда возвращает общий статус набора асинхронных запросов в виде объекта JSON. Некоторые поля по умолчанию не используются. Чтобы запрос включал такие поля, задайте их в параметре fields, например: fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

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

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

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

• initial — запрос ещё не обработан;
• in_progress — запрос обрабатывается;
• success — запрос успешно выполнен;
• error — запрос завершился ошибкой;
• canceled — запрос отменен пользователем.

Ответ возвращается в виде массива JSON с полями по умолчанию. Чтобы включить и другие поля, задайте их в параметре fields, например: fields=id,scope_object_id,status,result,input,async_request_set.

Получение подробной информации о запросе

Чтобы получить подробную информацию о конкретном асинхронном запросе, выполните следующий вызов:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

Ответ представляет собой объект JSON с перечисленными выше полями.

Вывод списка наборов запросов для аккаунта

Можно использовать несколько наборов асинхронных запросов на рекламу. Вот как запросить все такие наборы в рекламном аккаунте:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Ответ представляет собой массив объектов JSON, состоящий из наборов асинхронных запросов. Характеристики объектов описаны в этом разделе. Результаты можно фильтровать по параметру is_completed. Если задать значение is_completed=true, будут показаны только наборы выполненных асинхронных запросов.

Вывод списка запросов для группы объявлений

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

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_SET_ID>/asyncadrequests

Ответ представляет собой массив JSON с объектами асинхронных запросов. Статус, поля асинхронных запросов и фильтрация по полям аналогичны используемым в API https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests.

Редактирование наборов запросов

В наборах асинхронных запросов можно менять значения name, notification_uri и notification_mode.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Если обновление прошло успешно, возвращается ответ true. Значения notification_uri и notification_mode можно менять только до отправки уведомления.

Отмена запроса

Асинхронный запрос можно отменить, если он ещё не обработан.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_ID>

Если отмена прошла успешно, возвращается ответ true. Также можно отменять необработанные асинхронные запросы в составе набора:

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Если отмена прошла успешно, возвращается ответ true.

Примеры асинхронных запросов

Проверка статуса конкретного асинхронного запроса:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/"

Возвращаются следующие значения:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Получение результатов запросов:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/requests"

Ответ:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Получение списка наборов запросов в рекламном аккаунте:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_71597454/asyncadrequestsets"

Ответ:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Получение списка наборов запросов в кампании:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/6008248529789/asyncadrequests"
    

Возвращаются следующие значения:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

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

Пакетный запрос — это способ объединения нескольких вызовов Graph API в один HTTP-запрос. Marketing API затем разбивает такой запрос на составляющие. Т. е. для работы с Marketing API эффективнее всего использовать именно пакетные запросы. Чтобы ещё больше повысить эффективность, можно отправлять несколько пакетных запросов параллельно, используя отдельные потоки обработки.

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

Создание рекламы

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

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

Ответ содержит коды ответов на каждый запрос, а также стандартный ответ Graph API. Подробные сведения см. в статье о том, как отправлять по несколько запросов API.

Для ссылок на предыдущие запросы в пакетных запросах используются выражения в формате JSONPath.

Редактирование рекламы

Пакетные запросы можно использовать для редактирования рекламы. Вот как изменить ставки для трех объявлений:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Если относительный URL содержит redownload=1, выводится вся информация об объявлениях, в том числе ID. Так проще определить, какие объявления вы отредактировали.

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

Чтение объявлений

Если у вас много объявлений, разбейте свой запрос на несколько разных в составе пакетного запроса:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

Здесь 6003356308839 и 6004164369439 — ID объявлений, а 6003356307839 и 6004164259439 — ID групп объявлений.

Статистика рекламы

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

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

Здесь 6003356308839 и 6004164369439 — ID объявлений, а 6003356307839 и 6004164259439 — ID групп объявлений.

Если в рекламном аккаунте много объявлений, не рекомендуем использовать act_<account_ID>/adgroupstats, потому что в этом случае срок выполнения запроса может превысить время ожидания.

Пакетные запросы для прогнозирования охвата

Один пакетный запрос может содержать до 50 запросов на прогнозирование охвата. Вот так можно определить прогнозируемый охват для 2 разных конфигураций таргетинга:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

API Batch

Batch API обеспечивает пакетирование и асинхронную отправку запросов. При этом несколько вызовов Graph API объединяются в один HTTP-запрос, а затем выполняются асинхронно и без блокировки. Также в пакетных запросах можно задавать зависимости между связанными операциями.

Facebook обрабатывает независимые операции параллельно, а зависимые — последовательно. Каждый вызов API может содержать не более 1 000 запросов.

Выполнение вызовов Batch API

Вот как можно выполнить вызов Batch API:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Задайте массив запросов HTTP POST в виде массивов JSON. Каждый запрос должен содержать:

• name
• relative_url — часть URL, стоящую после "graph.facebook.com";
• body

API возвращает ID, с помощью которого можно проверять статус выполнения запросов.

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

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Вот как можно проверить статус набора запросов:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>"

Ответ будет содержать общий статус наборов асинхронных запросов в виде объектов JSON. Некоторые поля по умолчанию не используются. Чтобы включить их в ответ, задайте их в параметре fields, например: fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

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

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests"

Ответ представляет собой массив JSON с подробной информацией. Чтобы он включал поля, которые не используются по умолчанию, задайте их в параметре fields, например: fields=id,scope_object_id,status,result,input,async_request_set.

Вывод списка запросов к Batch API для рекламного аккаунта

Можно использовать несколько наборов запросов к Batch API. Вот как получить список всех таких наборов для рекламного аккаунта:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_requests"

Заголовки ETag

API Marketing поддерживает заголовки ETag. Они показывают, не изменились ли запрашиваемые данные с прошлого раза. Ниже описано, как работает эта функция.

1. Вы совершаете вызов. Заголовок ответа на него содержит ETag, значение которого представляет собой хэшированные данные, возвращаемые при вызове API. Это значение ETag нужно сохранить: оно понадобится в будущем.
2. При следующем выполнении того же вызова API вы включаете в него заголовок запроса If-None-Match с сохраненным значением ETag.
3. Если с прошлого раза данные не изменились, вы получаете ответ со статусом 304 – Not Modified. Никакие данные при этом не возвращаются.
4. Если с прошлого раза данные изменились, они возвращаются как обычно, а в ответе указывается новое значение ETag. Это значение тоже нужно сохранить, чтобы потом использовать в последующих вызовах.

Заголовки ETag помогают уменьшить трафик, но вызовы If-None-Match GET тоже учитываются в ограничении числа обращений для приложения.

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

Примеры заголовков ETag

Вот как можно проверить, не изменились ли рекламные аккаунты пользователя:

1. Определите значение ETag для текущих данных:

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Ответ будет таким:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

Здесь значение ETag — "7776cdb01f44354af8bfa4db0c56eebcb1378975". Обратите внимание: оно содержит кавычки (").

2. Определите, не изменились ли данные:

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Если ничего не изменилось, ответ будет таким:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Обратите внимание, что он содержит статус 304 Not Modified. Если бы данные изменились, вы получили бы обычный ответ API.

Рассмотрим пример для пакетного запроса, позволяющий проверить наличие изменений в объявлениях пользователя.

1. Определите значение ETag для текущих данных:

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

Ответ будет содержать следующие значения ETag:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

Здесь значения ETag — "21d371640127490b2ed0387e8af3f0f8c9eff012" и "410e53bb257f116e8716e4ebcc76df1c567b87f4". Обратите внимание: они содержат кавычки (").

2. Определите, не изменились ли данные:

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

Если ничего не изменилось, ответ будет таким:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Обратите внимание: он содержит статус 304 Not Modified. Если бы данные изменились, вы бы получили обычный ответ API.