Урок 7. Как получать данные через API
В этом уроке мы расскажем о структуре API и рассмотрим несколько примеров получения данных.
Напомним схему взаимосвязи объектов в API Директа, которую мы показывали в первом уроке:
Для каждого класса объектов в API предусмотрен соответствующий сервис: Campaigns — для управления кампаниями, AdGroups — для управления группами объявлений, Ads — для управления объявлениями и т. д. Полный список сервисов приведен в документации.
Логика работы с объектами в API унифицирована, и методы всех сервисов имеют стандартные названия. Как правило, сервис включает следующие методы:
add— добавление объектов;update— изменение параметров объектов;delete— удаление объектов;get— получение объектов.
В сервисе могут быть и другие методы. Например, в сервисе Campaigns доступны следующие методы:
Как получать объекты
Давайте рассмотрим, как получить параметры рекламной кампании, используя метод get.
Метод get разработан так, чтобы можно было запрашивать только нужные данные. Например, можно получить только идентификаторы и названия кампаний, а не все их параметры. Имена нужных вам параметров необходимо перечислить во входном параметре FieldNames.
Критерии отбора объектов нужно указать во входной структуре SelectionCriteria. Если критериев отбора несколько, то сервер будет искать объекты, подходящие сразу под все критерии. Некоторые сервисы позволяют указывать пустую структуру SelectionCriteria — в этом случае возвращаются все объекты.
Тренировка в Песочнице
Напомним пример запроса из предыдущего урока. В этом примере мы получили весь список кампаний, указав пустую структуру SelectionCriteria, и для каждой кампании получили только идентификатор и название, указав соответствующие параметры в FieldNames.
Внимание
Не забудьте изменить токен и идентификаторы в примерах на ваши данные.
cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
cURL для Windows
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{},\"FieldNames\":[\"Id\",\"Name\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
Запрос
{
"method": "get",
"params": {
"SelectionCriteria": {},
"FieldNames": ["Id", "Name"]
}
}
Ответ
{
"result": {
"Campaigns": [{
"Name": "Test API Sandbox campaign 1",
"Id": 1234567
}, {
"Name": "Test API Sandbox campaign 2",
"Id": 1234578
}, {
"Name": "Test API Sandbox campaign 3",
"Id": 1234589
}]
}
}
Некоторые параметры кампании (такие как название и идентификатор) являются общими для всех типов кампаний, а некоторые (например, стратегии показа) зависят от типа кампании. В следующем примере мы получим только кампании с типом “Текстово-графические объявления”. Чтобы получить для таких кампаний стратегии показа, укажем имя соответствующего параметра во входном параметре TextCampaignFieldNames.
cURL
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{ "Types": ["TEXT_CAMPAIGN"]},"FieldNames":["Id","Name"],"TextCampaignFieldNames":["BiddingStrategy"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
cURL для Windows
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{ \"Types\": [\"TEXT_CAMPAIGN\"]},\"FieldNames\":[\"Id\",\"Name\"],\"TextCampaignFieldNames\":[\"BiddingStrategy\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
Запрос
{
"method": "get",
"params": {
"SelectionCriteria": {
"Types": ["TEXT_CAMPAIGN"]
},
"FieldNames": ["Id", "Name"],
"TextCampaignFieldNames": ["BiddingStrategy"]
}
}
Ответ
{
"result": {
"Campaigns": [{
"Id": 1234567,
"Name": "Test API Sandbox campaign 1",
"TextCampaign": {
"BiddingStrategy": {
"Search": {
"BiddingStrategyType": "HIGHEST_POSITION"
},
"Network": {
"BiddingStrategyType":"NETWORK_DEFAULT",
"NetworkDefault": {
"LimitPercent": 100
}
}
}
}
}]
}
}
Постраничная выборка
Если вы работаете с большими массивами данных, все объекты могут не уместиться в ответе на один запрос, так как метод get возвращает не более 10 000 объектов. В этом случае метод get возвращает параметр LimitedBy — порядковый номер последнего возвращенного объекта. Наличие этого параметра указывает, что не все объекты получены.
Настроить параметры постраничной выборки можно с помощью входной структуры Page. Укажите количество нужных объектов — например, 10 — и количество объектов, которое должно быть пропущено при выборке, — например, 20, — и вы получите порцию данных: 10 объектов с 21-го по 30-й.
Задание
Мы подготовили несколько примеров и для других сервисов. Попробуйте воспроизвести эти запросы в Песочнице.
Сервис AdGroups
Получение списка групп объявлений кампании.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"CampaignIds":[ИДЕНТИФИКАТОР_КАМПАНИИ]},"FieldNames":["Id","Name","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"CampaignIds\":[ИДЕНТИФИКАТОР_КАМПАНИИ]},\"FieldNames\":[\"Id\",\"Name\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups
{% endcut %}
{% cut "Запрос" %}
{
"method": "get",
"params": {
"SelectionCriteria": {
"CampaignIds": [ИДЕНТИФИКАТОР_КАМПАНИИ]
},
"FieldNames": ["Id", "Name", "Status", "Type"]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"AdGroups": [{
"Status": "ACCEPTED",
"Name": "Группа №1296502",
"Id": 1296502,
"Type": "TEXT_AD_GROUP"
}, {
"Name": "Группа №1296517",
"Status": "DRAFT",
"Id": 1296517,
"Type": "TEXT_AD_GROUP"
}]
}
}
{% endcut %}
Сервис Ads
Получение списка объявлений группы.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","State","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"State\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "Запрос" %}
{
"method": "get",
"params": {
"SelectionCriteria": {
"AdGroupIds": [ИДЕНТИФИКАТОР_ГРУППЫ]
},
"FieldNames": ["Id", "State", "Status", "Type"]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"Ads": [{
"State": "ON",
"Id": 1381459,
"Status": "ACCEPTED",
"Type": "TEXT_AD"
}, {
"Type": "TEXT_AD",
"Status": "DRAFT",
"Id": 1381470,
"State": "OFF"
}]
}
}
{% endcut %}
Получение параметров одного объявления.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"Ids":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},"FieldNames":["Id"],"TextAdFieldNames":["Text","Title","Href","VCardId"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"Ids\":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},\"FieldNames\":[\"Id\"],\"TextAdFieldNames\":[\"Text\",\"Title\",\"Href\",\"VCardId\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
{% endcut %}
{% cut "Запрос" %}
{
"method": "get",
"params": {
"SelectionCriteria": {
"Ids": [1381459]
},
"FieldNames": ["Id"],
"TextAdFieldNames": ["Text", "Title", "Href", "VCardId"]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"Ads": [{
"Id": 1381459,
"TextAd": {
"Title": "Test sandbox banner 5",
"Href": "http://www.yandex.ru",
"VCardId": 171518,
"Text": "Test sandbox banner 5 text"
}
}]
}
}
{% endcut %}
Сервис Keywords
Получение ключевых фраз группы объявлений.
{% cut "cURL" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","Keyword","Bid","State","Status"]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords
{% endcut %}
{% cut "cURL для Windows" %}
curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"Keyword\",\"Bid\",\"State\",\"Status\"]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords
{% endcut %}
{% cut "Запрос" %}
{
"method": "get",
"params": {
"SelectionCriteria": {
"AdGroupIds": [1296506]
},
"FieldNames": ["Id", "Keyword", "Bid", "State", "Status"]
}
}
{% endcut %}
{% cut "Ответ" %}
{
"result": {
"Keywords": [{
"State": "ON",
"Keyword": "test keyword 5.1",
"Status": "ACCEPTED",
"Bid": 7700000,
"Id": 3458327
}, {
"Keyword": "Новая фраза",
"Id": 3458351,
"Bid": 400000,
"Status": "ACCEPTED",
"State": "ON"
}]
}
}
{% endcut %}
Что дальше
Итак, вы научились работать с методом get. В следующем уроке мы рассмотрим принципы работы методов, изменяющих данные.