Протокол SOAP
Во многих языках программирования существуют библиотеки для работы с SOAP. Ниже перечислены рекомендуемые библиотеки для популярных языков.
- Perl: SOAP::Lite и XML::Compile;
- PHP: SOAPClient;
- Python: suds;
WSDL
Для каждого сервиса в API Директа разработано описание на языке WSDL (Web Services Description Language), в котором представлены методы, входные и выходные структуры данных, типы данных, адрес для запросов к сервису и другое.
Адрес WSDL указан в документации каждого сервиса.
Наиболее функциональные библиотеки SOAP используют WSDL-описания для формирования запросов к сервисам и проверки передаваемых данных. Библиотеки скачивают WSDL-описание, анализируют его и формируют структуры данных, необходимые для вызова методов. Приложению остается заполнить эти структуры данными и выполнить запрос. Информация из ответного сообщения также выдается в виде структуры, свойственной языку программирования. Все это избавляет приложение от необходимости обрабатывать XML.
Приложение может самостоятельно формировать SOAP-запросы в формате XML, однако это трудоемкая задача и при наличии полнофункциональной SOAP-библиотеки выполнять ее вручную нецелесообразно.
Запросы к API в формате SOAP
Способ отправки запросов зависит от SOAP-библиотеки. Если библиотека поддерживает WSDL, достаточно указать адрес WSDL-описания. Из него библиотека получает адрес сервиса и выполняет необходимые действия для отправки запроса. Если библиотека не поддерживает WSDL, необходимо явно указывать адрес сервиса.
Адрес WSDL и адрес для запросов указаны в документации каждого сервиса.
Пример запроса
Вызов метода Ads.add
для добавления объявлений рекламодателю agrom
, выполняемый от имени рекламного агентства.
POST /v5/ads/ HTTP/1.1
Host: api.direct.yandex.com
Authorization: Bearer 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f
Accept-Language: en
Client-Login: agrom
Content-Type: text/xml; charset=utf-8
SOAPAction: "https://api.direct.yandex.com/v5/ads/add"
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://api.direct.yandex.com/v5/ads">
<SOAP-ENV:Body>
<ns1:AddRequest>
<Ads>
<AdGroupId>1234567</AdGroupId>
<TextAd>
<Text>Слоны всех пород. Сертифицированный питoмник</Text>
<Title>Купи слона!</Title>
<Href>http://exotic-farm.com/elefants</Href>
<Mobile>NO</Mobile>
</TextAd>
</Ads>
<Ads>
<AdGroupId>1234567</AdGroupId>
<TextAd>
<Text>Носороги с доставкой. Весенняя распродажа</Text>
<Title>Купи носорога!</Title>
<Mobile>NO</Mobile>
</TextAd>
</Ads>
</ns1:AddRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Пример ответа
HTTP/1.1 200 OK
Connection:close
Content-Type:text/xml; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<ns3:AddResponse xmlns:ns3="http://api.direct.yandex.com/v5/ads">
<AddResults>
<Id>7654321</Id>
</AddResults> <!-- Объявление успешно создано, возвращен его идентификатор -->
<AddResults>
<Errors>
<Code>6000</Code>
<Message>Неконсистентное состояние объекта</Message>
<Details>В объявлении должна быть указана или визитка или основная ссылка</Details>
</Errors>
</AddResults> <!-- Ошибка создания объявления -->
</ns3:AddResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Пример ошибки
Если выполнение запроса невозможно, возвращается сообщение об ошибке.
HTTP/1.1 200 OK
Connection:close
Content-Type:text/xml; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Некорректный запрос</faultstring>
<detail>
<ns3:FaultResponse xmlns:ns3="http://api.direct.yandex.com/v5/general">
<requestId>1010101010101010101</requestId>
<errorCode>8000</errorCode>
<errorDetail>В TextAd отсутствует обязательное поле Text</errorDetail>
</ns3:FaultResponse>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>