--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.ru/dev/direct/doc/en/format.md - https://yandex.ru/dev/direct/doc/ru/format.md - href: ru/format.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt sourcePath: ru/start/format.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/ru/llms.txt # Урок 5. Как выполнить запрос к API В этом уроке мы расскажем о форматах взаимодействия с API Директа и покажем, как выполнить первый запрос. ## Что нужно для выполнения запроса {#format_how_req} Пройдя предыдущие уроки, вы уже выполнили все условия, необходимые для успешного выполнения запросов: 1. У вас есть аккаунт в Директе, и вы приняли пользовательское соглашение в разделе **API** веб-интерфейса Директа. 1. Вы зарегистрировали приложение на Яндекс OAuth. 1. Вы подали заявку на доступ к API и получили одобрение заявки. 1. Вы получили OAuth-токен. ## Какие есть форматы взаимодействия с API Директа {#format_formats} Приложение обращается к серверу API Директа по сетевому протоколу HTTPS, выполняя POST-запросы. Каждый POST-запрос должен быть сформирован в определенном формате. В этом же формате сервер API вернет ответ. API Директа поддерживает два формата: - _JSON (англ. JavaScript Object Notation)_ — текстовый формат обмена данными; - _SOAP (англ. Simple Object Access Protocol)_ — протокол обмена структурированными сообщениями в формате XML. ![](_assets/format_formats.png) ## Куда отправлять запросы {#format_destination_req} Адрес для отправки запросов зависит от выбранного формата: - Для JSON-запросов — `https://api.direct.yandex.com/json/v501/{сервис}` - Для SOAP-запросов — `https://api.direct.yandex.com/v501/{сервис}` - WSDL-описание находится по адресу `https://api.direct.yandex.com/v501/{сервис}?wsdl` Здесь `{сервис}` — имя сервиса, с которым вы хотите работать. Каждый сервис предназначен для работы с определенным классом объектов. Например, для управления кампаниями используется сервис `Campaigns`, и запросы к этому сервису нужно отправлять на следующие адреса: - `https://api.direct.yandex.com/json/v501/campaigns` — JSON-запросы; - `https://api.direct.yandex.com/v501/campaigns` — SOAP-запросы. Адрес для запросов является регистрозависимым — необходимо указывать все символы в нижнем регистре, в том числе и название сервиса, иначе возникнет ошибка. ## Какие HTTP-заголовки используются {#format_http_headers} Запрос к API должен содержать HTTP-заголовок `Authorization` с OAuth-токеном пользователя, от имени которого выполняется запрос: ```text translate=no Authorization: Bearer ТОКЕН ``` - `Authorization` — это имя HTTP-заголовка. - `Bearer` — служебная константа протокола OAuth (обязательный параметр). - `ТОКЕН` — сам токен. Как получить токен, мы рассказывали в одном из предыдущих уроков. {% note info %} В Директе существует несколько типов аккаунтов: аккаунты прямых рекламодателей и их представителей, рекламных агентств и их представителей, а также клиентов агентств. Разные типы аккаунтов имеют разные полномочия. При работе с API Директа ваше приложение будет иметь только те возможности и права, которые имеет аккаунт пользователя, для которого был получен OAuth-токен. {% endnote %} Запрос также может содержать другие HTTP-заголовки: - `Client-Login` — логин клиента рекламного агентства. Заголовок обязателен при запросе от имени агентства. - `Accept-Language` — язык ответных сообщений. Ваше приложение должно уметь обрабатывать **заголовки ответа**: - `RequestId` — уникальный идентификатор вашего запроса. - `Units` — сведения об ограничениях. Об ограничениях мы расскажем в одном из следующих уроков. ## Чем выполнять запросы {#format_req_app} Для выполнения запросов к API вы можете разработать свое приложение на любом языке программирования. Пока вы учитесь, запросы можно выполнять любой программой для отправки POST-запросов — например, с помощью плагина для браузера или из командной строки с помощью утилиты cURL. ## Выполняем первый запрос {#format_first_req} Приведенные здесь и далее примеры пригодны для использования с помощью утилиты cURL. Вы можете скорректировать предложенный код под ваше приложение на любом языке программирования. Формат примеров для ОС Windows отличается: JSON-код заключен в двойные кавычки, а в самом коде экранированы все двойные кавычки. Например: ```text translate=no -d "{\"method\":\"get\",\"params\"... ``` {% note alert %} Не забудьте изменить токен и идентификаторы объектов в примерах на ваши данные. {% endnote %} Посмотрим, какие кампании создались. Обратите внимание на ключевые параметры запроса: - Запрос отправляется к сервису `Campaigns`: `https://api.direct.yandex.com/json/v501/**campaigns**` - В заголовке `Authorization` передан OAuth-токен. - Вызван метод `get` для получения кампаний. **cURL**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name"]}}' https://api.direct.yandex.com/json/v501/campaigns ``` **cURL для Windows**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{},\"FieldNames\":[\"Id\",\"Name\"]}}" https://api.direct.yandex.com/json/v501/campaigns ``` **Запрос**   ```text translate=no POST /json/v501/campaigns/ HTTP/1.1 Host: api.direct.yandex.com Authorization: Bearer ТОКЕН Accept-Language: ru Client-Login: ЛОГИН_КЛИЕНТА Content-Type: application/json; charset=utf-8 { "method": "get", "params": { "SelectionCriteria": {}, "FieldNames": ["Id", "Name"] } } ``` **Ответ**   ```text translate=no 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 campaign 1", "Id": 1234567 }, { "Name": "Test API campaign 2", "Id": 1234578 }, { "Name": "Test API campaign 3", "Id": 1234589 }] } } ``` ## Что дальше {#format_whats_now} Итак, вы выполнили первый запрос к API Директа. В следующих уроках мы подробно расскажем о принципах работы с данными в API и рассмотрим более сложные примеры.