Урок 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 и рассмотрим более сложные примеры.