Урок 7. Как получать данные через API

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

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

В этом уроке мы расскажем о структуре 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": {
              "BidPercent": 100
            }
          } 
        }
      }
    }]
  }
}
Постраничная выборка
Если вы работаете с большими массивами данных, все объекты могут не уместиться в ответе на один запрос, так как метод get возвращает не более 10 000 объектов. В этом случае метод get возвращает параметр LimitedBy — порядковый номер последнего возвращенного объекта. Наличие этого параметра указывает, что не все объекты получены.
Настроить параметры постраничной выборки можно с помощью входной структуры Page. Укажите количество нужных объектов — например, 10 — и количество объектов, которое должно быть пропущено при выборке, — например, 20, — и вы получите порцию данных: 10 объектов с 21-го по 30-й.

Задание

Мы подготовили несколько примеров и для других сервисов. Попробуйте воспроизвести эти запросы в Песочнице.

Сервис AdGroups

Получение списка групп объявлений кампании.

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
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
Запрос
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "CampaignIds": [ИДЕНТИФИКАТОР_КАМПАНИИ]
    },
    "FieldNames": ["Id", "Name", "Status", "Type"]
  }
}
Ответ
{
  "result": {
    "AdGroups": [{
      "Status": "ACCEPTED",
      "Name": "Группа №1296502",
      "Id": 1296502,
      "Type": "TEXT_AD_GROUP"
    }, {
      "Name": "Группа №1296517",
      "Status": "DRAFT",
      "Id": 1296517,
      "Type": "TEXT_AD_GROUP"
    }]
  }
}
Сервис Ads

Получение списка объявлений группы.

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
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
Запрос
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [ИДЕНТИФИКАТОР_ГРУППЫ]
    },
    "FieldNames": ["Id", "State", "Status", "Type"]
  }
}
Ответ
{
  "result": {
    "Ads": [{
      "State": "ON",
      "Id": 1381459,
      "Status": "ACCEPTED",
      "Type": "TEXT_AD"
    }, {
      "Type": "TEXT_AD",
      "Status": "DRAFT",
      "Id": 1381470,
      "State": "OFF"
    }]
  }
}

Получение параметров одного объявления.

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
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
Запрос
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "Ids": [1381459]
    },
    "FieldNames": ["Id"],
    "TextAdFieldNames": ["Text", "Title", "Href", "VCardId"]
  }
}
Ответ
{
  "result": {
    "Ads": [{
      "Id": 1381459,
      "TextAd": {
        "Title": "Test sandbox banner 5",
        "Href": "http://www.yandex.ru",
        "VCardId": 171518,
        "Text": "Test sandbox banner 5 text"
      }
    }]
  }
}
Сервис Keywords

Получение ключевых фраз группы объявлений.

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
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
Запрос
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [1296506]
    },
    "FieldNames": ["Id", "Keyword", "Bid", "State", "Status"]
  }
}
Ответ
{
  "result": {
    "Keywords": [{
      "State": "ON",
      "Keyword": "test keyword 5.1",
      "Status": "ACCEPTED",
      "Bid": 7700000,
      "Id": 3458327
    }, {
      "Keyword": "Новая фраза",
      "Id": 3458351,
      "Bid": 400000,
      "Status": "ACCEPTED",
      "State": "ON"
    }]
  }
}

Что дальше

Итак, вы научились работать с методом get. В следующем уроке мы рассмотрим принципы работы методов, изменяющих данные.

Вопросы

  1. Для чего предназначен сервис Campaigns API Директа?
    Неверно.
    Неверно.
    Неверно.
    Верно!
  2. Каким методом сервиса Campaigns можно получить данные?
    Неверно.
    Неверно.
    Верно!
    Неверно.
  3. Почему нужно использовать постраничную выборку?
    Верно!
    Неверно.
    Неверно.