Урок 8. Как вносить изменения через API

В этом уроке вы узнаете:

  1. Как редактировать параметры объектов
  2. Тренировка в Песочнице
  3. Задание
  4. Что дальше
  5. Полезные ссылки
  6. Вопросы

Все методы, изменяющие данные, — например, методы 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

Добавление группы объявлений.

cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"add","params":{"AdGroups":[{"Name":"Новая группа","CampaignId":ИДЕНТИФИКАТОР_КАМПАНИИ,"RegionIds":[213]}]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups
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
Запрос
{
  "method": "add",
  "params": {
    "AdGroups": [{
      "Name": "Новая группа",
      "CampaignId": ИДЕНТИФИКАТОР_КАМПАНИИ,
      "RegionIds": [213]
    }]
  }
}
Ответ
{
  "result": {
    "AddResults": [{
      "Id": ИДЕНТИФИКАТОР_ГРУППЫ
    }]
  }
}
Сервис Ads

Добавление объявления в группу.

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
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
Запрос
{
  "method": "add",
  "params": {
    "Ads": [{
      "AdGroupId": "ИДЕНТИФИКАТОР_ГРУППЫ",
      "TextAd": {
        "Title": "Заголовок объявления",
        "Text": "Текст объявления",
        "Mobile": "NO",
        "Href": "http://example.com"
      }
    }]
  }
}
Ответ
{
  "result": {
    "AddResults": [{
      "Id": ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ
    }]
  }
}
Сервис Keywords

Добавление ключевой фразы.

cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"add","params":{"Keywords":[{"Keyword":"Новая фраза","AdGroupId":ИДЕНТИФИКАТОР_ГРУППЫ,"Bid":300000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords
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
Запрос
{
  "method": "add",
  "params": {
    "Keywords": [{
      "Keyword": "Новая фраза",
      "AdGroupId": ИДЕНТИФИКАТОР_ГРУППЫ,
      "Bid": 300000
    }]
  }
}
Ответ
{
  "result": {
    "AddResults": [{
      "Id": ИДЕНТИФИКАТОР_ФРАЗЫ
    }]
  }
}
Сервис KeywordBids

Изменение ставки для одной ключевой фразы.

cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"set","params":{"KeywordBids":[{"KeywordId":ИДЕНТИФИКАТОР_ФРАЗЫ,"SearchBid":400000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywordbids
cURL для Windows
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"set\",\"params\":{\"KeywordBids\":[{\"KeywordId\":ИДЕНТИФИКАТОР_ФРАЗЫ,\"SearchBid\":400000}]}}" https://api-sandbox.direct.yandex.com/json/v5/keywordbids
Запрос
{
  "method": "set",
  "params": {
    "KeywordBids": [{
      "KeywordId": ИДЕНТИФИКАТОР_ФРАЗЫ,
      "SearchBid": 400000
    }]
  }
}
Ответ
{
  "result": {
    "SetResults": [{
      "KeywordId": ИДЕНТИФИКАТОР_ФРАЗЫ
    }]
  }
}

Что дальше

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

Полезные ссылки

Документация: Как работают методы, изменяющие данные

Вопросы

  1. Что случится, если запрос на создание пяти объявлений содержит ошибку в одном из них?
    Неверно.
    Верно!
    Неверно.
    Неверно.
  2. Какой состав параметров нужно передавать при запросах методом update?
    Неверно.
    Верно!
    Неверно.
  3. Какой метод сервиса Campaigns предназначен для создания кампаний?
    Неверно.
    Неверно.
    Верно!