Протокол 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
        <AdGroupId1234567</AdGroupId
        <TextAd
          <TextСлоны всех пород. Сертифицированный питoмник</Text
          <TitleКупи слона!</Title
          <Hrefhttp://exotic-farm.com/elefants</Href
          <MobileNO</Mobile
        </TextAd
      </Ads
      <Ads
        <AdGroupId1234567</AdGroupId
        <TextAd
          <TextНосороги с доставкой. Весенняя распродажа</Text
          <TitleКупи носорога!</Title
          <MobileNO</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
        <Id7654321</Id
      </AddResults<!-- Объявление успешно создано, возвращен его идентификатор --
      <AddResults
        <Errors
          <Code6000</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
      <faultcodeSOAP-ENV:Client</faultcode
      <faultstringНекорректный запрос</faultstring
      <detail
        <ns3:FaultResponse xmlns:ns3="http://api.direct.yandex.com/v5/general"
          <requestId1010101010101010101</requestId
          <errorCode8000</errorCode
          <errorDetailВ TextAd отсутствует обязательное поле Text</errorDetail
        </ns3:FaultResponse
      </detail
    </SOAP-ENV:Fault
  </SOAP-ENV:Body
</SOAP-ENV:Envelope

Узнайте больше

Предыдущая
Формат JSON
Следующая
Обработка ошибок