Урок 6. Как выполнить запрос к API

Что нужно для выполнения запроса

В этом уроке мы расскажем о форматах взаимодействия с API Директа и покажем, как выполнить первый запрос.

Пройдя предыдущие уроки, вы уже выполнили все условия, необходимые для успешного выполнения запросов:

1. У вас есть аккаунт в Директе, и вы приняли пользовательское соглашение в разделе API веб-интерфейса Директа.
2. Вы зарегистрировали приложение на Яндекс.OAuth.
3. Вы подали заявку на доступ к API и получили одобрение заявки.
4. Вы получили OAuth-токен.
5. Вы включили Песочницу.

   Внимание. Поскольку вы подавали заявку на тестовый доступ, то работать сможете только с Песочницей и тестовыми данными.

Какие есть форматы взаимодействия с API Директа

Приложение обращается к серверу API Директа по сетевому протоколу HTTPS, выполняя POST-запросы. Каждый POST-запрос должен быть сформирован в определенном формате. В этом же формате сервер API вернет ответ.

API Директа поддерживает два формата:

• JSON (англ. JavaScript Object Notation) — текстовый формат обмена данными;
• SOAP (англ. Simple Object Access Protocol) — протокол обмена структурированными сообщениями в формате XML.

  
  

  

  
  

Куда отправлять запросы

Адрес для отправки запросов в Песочницу зависит от выбранного формата:

• Для JSON-запросов — https://api-sandbox.direct.yandex.com/json/v5/{сервис}
• Для SOAP-запросов — https://api-sandbox.direct.yandex.com/v5/{сервис}
• WSDL-описание находится по адресу https://api-sandbox.direct.yandex.com/v5/{сервис}?wsdl

Здесь {сервис} — имя сервиса, с которым вы хотите работать. Каждый сервис предназначен для работы с определенным классом объектов. Например, для управления рекламными кампаниями используется сервис Campaigns, и запросы к этому сервису нужно отправлять на следующие адреса:

• https://api-sandbox.direct.yandex.com/json/v5/campaigns — JSON-запросы;
• https://api-sandbox.direct.yandex.com/v5/campaigns — SOAP-запросы.

Адрес для запросов является регистрозависимым — необходимо указывать все символы в нижнем регистре, в том числе и название сервиса, иначе возникнет ошибка.

Какие HTTP-заголовки используются

Запрос к API должен содержать HTTP-заголовок Authorization с OAuth-токеном пользователя, от имени которого выполняется запрос:

Authorization: Bearer ТОКЕН

• Authorization — это имя HTTP-заголовка.
• Bearer — служебная константа протокола OAuth (обязательный параметр).
• ТОКЕН — сам токен.

Как получить токен, мы рассказывали в одном из предыдущих уроков.

Запрос также может содержать другие HTTP-заголовки:

• Client-Login — логин клиента рекламного агентства. Заголовок обязателен при запросе от имени агентства.
• Accept-Language — язык ответных сообщений.

Ваше приложение должно уметь обрабатывать заголовки ответа:

• RequestId — уникальный идентификатор вашего запроса.
• Units — сведения об ограничениях. Об ограничениях мы расскажем в одном из следующих уроков.

Чем выполнять запросы

Для выполнения запросов к API вы можете разработать свое приложение на любом языке программирования. Пока вы учитесь, запросы можно выполнять любой программой для отправки POST-запросов — например, с помощью плагина для браузера или из командной строки с помощью утилиты cURL.

Выполняем первый запрос

Приведенные здесь и далее примеры пригодны для использования с помощью утилиты cURL. Вы можете скорректировать предложенный код под ваше приложение на любом языке программирования.

Формат примеров для ОС Windows отличается: JSON-код заключен в двойные кавычки, а в самом коде экранированы все двойные кавычки. Например:

-d "{\"method\":\"get\",\"params\"...

Посмотрим, какие тестовые кампании создались в Песочнице. Обратите внимание на ключевые параметры запроса:

• Запрос отправляется к сервису Campaigns на адрес Песочницы:

  https://api-sandbox.direct.yandex.com/json/v5/campaigns

• В заголовке Authorization передан OAuth-токен.
• Вызван метод get для получения кампаний.

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

Запрос

POST /json/v5/campaigns/ HTTP/1.1
Host: api-sandbox.direct.yandex.com
Authorization: Bearer ТОКЕН
Accept-Language: ru 
Client-Login: ЛОГИН_КЛИЕНТА
Content-Type: application/json; charset=utf-8

{
  "method": "get",
  "params": {
    "SelectionCriteria": {},
    "FieldNames": ["Id", "Name"]
  }
}

Ответ

HTTP/1.1 200 OK
Connection:close
Content-Type:application/json
Date:Fri, 28 Jun 2016 17:07:02 GMT
RequestId: 1111111111111111112
Units: 10/20828/64000
Server:nginx
Transfer-Encoding:chunked

{
  "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
    }]
  }
}

Что дальше

Итак, вы выполнили первый запрос к API Директа. В следующих уроках мы подробно расскажем о принципах работы с данными в API и рассмотрим более сложные примеры.

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

Вопросы

1. Как приложение может взаимодействовать с API Директа?

   По сетевому протоколу HTTPS путем выполнения POST-запросов.С помощью передачи XLS/XLSX-файлов.Через обмен пакетами посредством FTP и SFTP.

   Верно!

   Неверно.

   Неверно.
2. Какой HTTP-заголовок обязательно должен быть указан в запросе к серверу API Директа?

   Client-Login.Client-IDBearer.Authorization.

   Неверно.

   Неверно.

   Неверно.

   Верно!
3. Как сервер API Директа отличает запросы к тестовым данным от запросов к реальным данным?

   По адресу, на который отправлен запрос.Сервер API автоматически определяет тип данных по типу заявки на доступ приложения к API Директа.Тип данных определяется сервером API по наличию в запросе HTTP-заголовков X-Data-Production и X-Data-Sandbox.

   Верно!

   Неверно.

   Неверно.