Урок 8. Как вносить изменения через API
Все методы, изменяющие данные, — например, методы add, update, delete — принимают на вход массив объектов. Каждый объект в запросе обрабатывается отдельно. Например, если приложение отправило запрос на создание 100 объявлений и в 10 из них возникла ошибка, то остальные 90 объявлений будут успешно созданы. Сервер API вернет идентификаторы для 90 созданных объявлений и ошибки для остальных 10.
Внимание
Идентификатор объекта возвращается только в случае успешного выполнения операции (при этом могут быть также выданы предупреждения).
Ошибки, исключающие возможность выполнения запроса (например, неверный формат или отсутствие обязательного параметра), приведут к полному отклонению запроса.
Ваше приложение должно учитывать это при взаимодействии с API и корректно обрабатывать возвращаемые сервером ошибки.
Как редактировать параметры объектов
При изменении объекта с помощью метода update нет необходимости передавать все параметры объекта. Достаточно указать идентификатор объекта и те параметры, которые требуется изменить. Остальные параметры изменены не будут. При этом сервер Директа все равно проверит объект целиком и, если с новыми значениями объект некорректен, вернет ошибку.
Тренировка в Песочнице
В предыдущем уроке мы получили список всех кампаний. Теперь продолжим работу с одной из них: включим раздельное управление ставками на поиске и в сетях.
cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"update","params":{"Campaigns":[{"Id":ИДЕНТИФИКАТОР_КАМПАНИИ,"TextCampaign":{"BiddingStrategy":{"Network":{"BiddingStrategyType":"MAXIMUM_COVERAGE"}}}}]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
cURL для Windows
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"update\",\"params\":{\"Campaigns\":[{\"Id\":ИДЕНТИФИКАТОР_КАМПАНИИ,\"TextCampaign\":{\"BiddingStrategy\":{\"Network\":{\"BiddingStrategyType\":\"MAXIMUM_COVERAGE\"}}}}]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
Запрос
{
"method": "update",
"params": {
"Campaigns": [{
"Id": ИДЕНТИФИКАТОР_КАМПАНИИ,
"TextCampaign": {
"BiddingStrategy": {
"Network": {
"BiddingStrategyType": "MAXIMUM_COVERAGE"
}
}
}
}]
}
}
Ответ
{
"result": {
"UpdateResults": [{
"Id": ИДЕНТИФИКАТОР_КАМПАНИИ
}]
}
}
Задание
Мы подготовили несколько примеров и для других сервисов. Попробуйте воспроизвести эти запросы в Песочнице.
Сервис AdGroups
Добавление группы объявлений.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"add","params":{"AdGroups":[{"Name":"Новая группа","CampaignId":ИДЕНТИФИКАТОР_КАМПАНИИ,"RegionIds":[213]}]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"add\",\"params\":{\"AdGroups\":[{\"Name\":\"Новая группа\",\"CampaignId\":ИДЕНТИФИКАТОР_КАМПАНИИ,\"RegionIds\":[213]}]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups
{% endcut %}
{% cut "Запрос" %}
{
"method": "add",
"params": {
"AdGroups": [{
"Name": "Новая группа",
"CampaignId": ИДЕНТИФИКАТОР_КАМПАНИИ,
"RegionIds": [213]
}]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"AddResults": [{
"Id": ИДЕНТИФИКАТОР_ГРУППЫ
}]
}
}
{% endcut %}
Сервис Ads
Добавление объявления в группу.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"add","params":{"Ads":[{"AdGroupId":ИДЕНТИФИКАТОР_ГРУППЫ,"TextAd":{"Title":"Заголовок объявления","Text":"Текст объявления","Mobile":"NO","Href":"http://example.com"}}]}}' https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"add\",\"params\":{\"Ads\":[{\"AdGroupId\":ИДЕНТИФИКАТОР_ГРУППЫ,\"TextAd\":{\"Title\":\"Заголовок объявления\",\"Text\":\"Текст объявления\",\"Mobile\":\"NO\",\"Href\":\"http://example.com\"}}]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "Запрос" %}
{
"method": "add",
"params": {
"Ads": [{
"AdGroupId": "ИДЕНТИФИКАТОР_ГРУППЫ",
"TextAd": {
"Title": "Заголовок объявления",
"Text": "Текст объявления",
"Mobile": "NO",
"Href": "http://example.com"
}
}]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"AddResults": [{
"Id": ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ
}]
}
}
{% endcut %}
Сервис Keywords
Добавление ключевой фразы.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"add","params":{"Keywords":[{"Keyword":"Новая фраза","AdGroupId":ИДЕНТИФИКАТОР_ГРУППЫ,"Bid":300000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"add\",\"params\":{\"Keywords\":[{\"Keyword\":\"Новая фраза\",\"AdGroupId\":ИДЕНТИФИКАТОР_ГРУППЫ,\"Bid\":300000}]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords
{% endcut %}
{% cut "Запрос" %}
{
"method": "add",
"params": {
"Keywords": [{
"Keyword": "Новая фраза",
"AdGroupId": ИДЕНТИФИКАТОР_ГРУППЫ,
"Bid": 300000
}]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"AddResults": [{
"Id": ИДЕНТИФИКАТОР_ФРАЗЫ
}]
}
}
{% endcut %}
Сервис KeywordBids
Изменение ставки для одной ключевой фразы.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"set","params":{"KeywordBids":[{"KeywordId":ИДЕНТИФИКАТОР_ФРАЗЫ,"SearchBid":400000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywordbids
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"set\",\"params\":{\"KeywordBids\":[{\"KeywordId\":ИДЕНТИФИКАТОР_ФРАЗЫ,\"SearchBid\":400000}]}}" https://api-sandbox.direct.yandex.com/json/v5/keywordbids
{% endcut %}
{% cut "Запрос" %}
<pre >{ "method": "set", "params": { "KeywordBids": [{ "KeywordId": ИДЕНТИФИКАТОР_ФРАЗЫ, "SearchBid": 400000 }] } }</pre>
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"SetResults": [{
"KeywordId": ИДЕНТИФИКАТОР_ФРАЗЫ
}]
}
}
{% endcut %}
Что дальше
Итак, вы научились выполнять запросы в Песочнице как для получения, так и для изменения данных. Остались последние шаги — перейти от тренировок в Песочнице к реальной работе.