Протокол SOAP

Во многих языках программирования существуют библиотеки для работы с SOAP. Ниже перечислены рекомендуемые библиотеки для популярных языков.

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>