Урок 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

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

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. В следующем уроке мы рассмотрим принципы работы методов, изменяющих данные.

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

Документация: Как работает метод get

Вопросы

1. Для чего предназначен сервис Campaigns API Директа?

   Для управления рекламными объявлениями.Для управления ключевыми фразами.Для получения статистики по группам объявлений.Для управления рекламными кампаниями.

   Неверно.

   Неверно.

   Неверно.

   Верно!
2. Каким методом сервиса Campaigns можно получить данные?

   updateCreateOrUpdateCampaigngetGetCampaignsParams

   Неверно.

   Неверно.

   Верно!

   Неверно.
3. Почему нужно использовать постраничную выборку?

   Она позволяет получить объекты поэтапно с помощью нескольких запросов.Такая выборка позволяет отправлять к API меньше запросов.Постраничная выборка обязательна при работе с Песочницей.

   Верно!

   Неверно.

   Неверно.