Что такое soap api
Рельсы веб-интеграции. REST и SOAP
В каждой отрасли бизнеса, каждой компании, как правило, используется целый зоопарк ПО. Одни системы «из коробки» умеют взаимодействовать с «соседними» продуктами, другие же приходится дорабатывать. За десятилетия существования веба как отрасли сформировались следующие практики межсетевого взаимодействия:
Обмен файлами по FTP.
Неструктурированные HTTP-запросы, договорённости между разработчиками.
Экзотика: сокеты, порты, бинарные объекты.
В данной статье мы поговорим о веб-сервисах. Чем они отличаются от прочих способов и какие они бывают.
Что такое веб-сервисы?
Веб-сервисы (или веб-службы) — это технология, позволяющая системам обмениваться данными друг с другом через сетевое подключение. Обычно веб-сервисы работают поверх протокола HTTP или протокола более высокого уровня. Веб-сервис — просто адрес, ссылка, обращение к которому позволяет получить данные или выполнить действие.
Главное отличие веб-сервиса от других способов передачи данных: стандартизированность. Приняв решение использовать веб-сервисы, можно сразу переходить к структуре данных и доступным функциям. Например, в SOAP (как более строгом протоколе), уже решён вопрос уведомления об ошибках.
Самые известные способы реализации веб-сервисов:
XML-RPC (XML Remote Procedure Call) — протокол удаленного вызова процедур с использованием XML. Прародитель SOAP. Предельно прост в реализации.
SOAP (Simple Object Access Protocol) — стандартный протокол по версии W3C. Четко структурирован и задокументирован.
JSON-RPC (JSON Remote Procedure Call) — более современный аналог XML-RPC. Основное отличие — данные передаются в формате JSON.
REST (Representational State Transfer) — архитектурный стиль взаимодействия компьютерных систем в сети основанный на методах протокола HTTP.
Специализированные протоколы для конкретного вида задач, такие как GraphQL.
Менее распространенный, но более эффективный gRPC, передающий данные в бинарном виде и использующий HTTP/2 в качестве транспорта.
Остальные протоколы не так широко распространены. Подробно рассмотрены в статье будут SOAP и REST.
SOAP (Simple Object Access Protocol) — данные передаются в формате XML.
отраслевой стандарт по версии W3C;
наличие строгой спецификации;
широкая поддержка в продуктах Microsoft,
сложность/ресурсоемкость парсинга XML-данных.
Любое сообщение в протоколе SOAP — это XML документ, состоящий из следующих элементов (тегов):
Envelope. Корневой обязательный элемент. Определяет начало и окончание сообщения.
Header. Необязательный элемент — заголовок. Содержит элементы, необходимые для обработки самого сообщения. Например, идентификатор сессии.
Body. Основной элемент, содержит основную информацию сообщения. Обязательный.
Fault. Элемент, содержащий информацию об ошибках, возникающих в процессе обработки сообщения. Необязательный.
Пример SOAP запроса:
Пример SOAP ответа:
REST (Representational State Transfer) — на самом деле архитектурный стиль, а не протокол. В отличие от SOAP, REST не подкреплен официальным стандартом. Фактически, он основывается на соглашениях. Веб-сервис, построенный с учетом всех требований и ограничений архитектурного стиля, можно назвать RESTful веб-сервисом.
REST не использует конвертацию данных при передаче, данные передаются в исходном виде — это снижает нагрузку на клиент веб-сервиса, но увеличивает нагрузку на сеть. Управление данными происходит с помощью методов HTTP:
GET — получить данные;
POST — добавить данные;
PUT — изменить данные;
DELETE — удалить данные.
Использование этих методов позволяет реализовать типичный CRUD (Create/Read/Update/Delete) для любой информации. Но это лишь соглашение: часто используются только 2 метода: GET для получения и POST для всего остального. Разобраться поможет такое понятие, как REST-Patterns. Паттерны связывают HTTP методы с тем, что они делают.
экономичность в плане ресурсов;
не требует программных надстроек (json_decode есть почти в каждом языке).
неоднозначность методов управления данными.
Пример REST запроса:
Пример REST ответа:
Что же использовать?
Вопрос «Какой способ реализации использовать?» необходимо рассматривать в контексте реализуемой системы и ее ограничений. Обычно, SOAP используется в крупных корпоративных системах со сложной логикой, когда требуются четкие стандарты, подкрепленные временем. XML-RPC, пожалуй, устарел и не имеет смысла ввиду наличия собрата JSON-RPC. RPC-протоколы подойдут для совсем простых систем с малым количеством единиц информации и API-методов.
Если же вы разрабатываете публичное API и логика взаимодействия во многом покрывается четверкой методов CRUD — смело выбирайте REST. Он наиболее популярен в WEB. Яндекс, Google и другие используют именно его для своего API.
Веб-сервисы в живом производстве
Разработка веб-сервисов — типичная задача интеграции. ИНТЕРВОЛГА, как веб-интегратор, регулярно сталкивается с задачами разработки веб-сервисов и успешно с ними справляется. Наши сайты были и SOAP/REST серверами, и SOAP/REST клиентами.
Успешным примером внедрения веб-сервисов является проект Enterprise-уровня — Личный кабинет клиентов компании Евраз Металл Инпром. Все функции личного кабинета основываются на взаимодействии с удаленным SOAP веб-сервисом. Сайт выступает клиентом. В процессе эволюции в угоду безопасности сайт переквалифицировался в SOAP-сервер, а учетная система в SOAP-клиента.
Еще один личный кабинет для клиентов компании Евраз — еще один пример сайта в качестве клиента удаленного SOAP веб-сервиса.
Если у вас есть потребность организовать взаимодействие с веб-сервисом, сделать из сайта REST/SOAP/RPC клиент или сервер, пишите нам.
Подведем итог, выделив, два важных тезиса в пользу выбора веб-сервисов в качестве «рельс» для веб-интеграции.
Наш опыт неоднократно демонстрировал, что создание веб-сервисов, в реальном времени передающих необходимые данные между сайтом и другим ПО — лучшее решение, чем классические обмены по расписанию. Такой подход проще сопровождать, вести его отладку, это более эффективная трата времени программиста, чем проектирование и разработка сложного двунаправленного обмена с кучей сущностей.
Можно провести аналогию с эволюцией разработки сайтов. Когда-то, на заре сайтостроения, каждый разработчик делал сайт с нуля на той технологии, которую мог знать лишь он один. Это порождало проблемы в развитии таких сайтов. Как работали такие сайты — знал только автор кода. Со временем появлялись фреймворки и CMS. Разработку начинали не с нуля, а с известных широкой массе разработчиков «заготовок» — стандартных решений стандартных проблем с возможность расширения и углубления.
Также и с обменом данными. Не нужно тратить месяцы на объяснение новому сотруднику и самому себе, как работает обмен. Есть стандарт, обмен работает по нему.
Сравнение архитектурных стилей API: SOAP vs REST vs GraphQL vs RPC
Feb 4 · 12 min read
Два отдельных приложения нуждаются в посреднике, чтобы общаться друг с другом. Поэтому разработчики часто строят мосты — программные интерфейсы приложений, они же API, — чтобы предоставить одной системе доступ к информации или функциональности из другой.
Чтобы способствовать быстрой и масштабной интеграции приложений, API реализуются с использованием протоколов и/или спецификаций, определяющих семантику и синтаксис передаваемых сообщений. Эти спецификации составляют архитектуру API.
Со временем появились различные архитектурные стили API. Каждый из них содержит собственные схемы стандартизации обмена данными. Наличие выбора вызывает бесконечные споры о том, какой архитектурный стиль лучше.
Сегодня многи е пользователи API называют REST “Rest in peace” (“Покойся с миром”) и болеют за успех GraphQL, в то время как десять лет назад ситуация была обратной: REST как победитель, пришедший на замену SOAP. Проблема с этими мнениями в том, что они однобоко поднимают на щит какую-то технологию вместо того, чтобы рассматривать ее фактические свойства и характеристики относительно конкретной ситуации.
В этой статье мы останемся объективными и обсудим четыре основных стиля API в порядке их появления, сравним их сильные и слабые стороны и выделим сценарии, для которых каждый из них подходит лучше всего.
Удаленный вызов процедуры (RPC): вызов функции в другой системе
Удаленный вызов процедуры ( Remote Procedure Call) — это спецификация, которая позволяет удаленно выполнять функцию в другом контексте. RPC расширяет понятие локального вызова процедуры, но помещает его в контекст HTTP API.
Проблематичность первоначального XML-RPC связана со сложностями в обеспечении типов данных для полезных нагрузок XML. Позже API RPC задействовал более конкретную спецификацию JSON-RPC, которая считается более простой альтернативой SOAP. gRPC — последняя версия RPC, разработанная компанией Google в 2015 году. Благодаря подключаемым поддержке балансировки нагрузки, трассировки, проверки работоспособности и аутентификации gRPC хорошо подходит для микросервисов.
Как работает RPC
Клиент вызывает удаленную процедуру, сериализует параметры и дополнительную информацию в сообщении и отправляет это сообщение на сервер. Получив сообщение, сервер десериализует его содержимое, выполняет запрошенную операцию и отправляет результат обратно клиенту. Стаб сервера и стаб клиента берут на себя сериализацию и десериализацию параметров.
Преимущества RPC
Простота и понятность взаимодействий. RPC использует GET для получения информации и POST для всего остального. Механика взаимодействия между сервером и клиентом сводится к вызову конечной точки и получению ответа.
Легкость добавления функций. Получив новое требование для API, мы можем легко добавить другую конечную точку, выполняющую это требование: 1) написать новую функцию и перебросить ее на конечную точку, и 2) теперь клиент может попасть в эту конечную точку и получить информацию, соответствующую заданному требованию.
Высокая производительность. Легкие полезные нагрузки легко распределяются по сети, обеспечивая высокую производительность, что важно для общих серверов и параллельных вычислений, выполняемых в сетях рабочих станций. RPC способен оптимизировать сетевой уровень и сделать его очень эффективным в ситуации, когда различные сервисы каждый день обмениваются тоннами сообщений.
Недостатки RPC
Плотная связь с базовой системой. Уровень абстракции API способствует его повторному использованию. Чем теснее связанность с базовой системой, тем хуже API подходит для других систем. Тесная связь RPC с базовой системой не позволяет создать уровень абстракции между функциями в системе и внешним API. Отсюда вытекают вопросы относительно безопасности, поскольку детали реализации базовой системы довольно легко просачиваются в API. Плотная связанность RPC создает трудности для требований к масштабируемости и слабо связанных команды. Таким образом, клиент либо беспокоится о возможных побочных эффектах вызова определенной конечной точки, либо пытается выяснить, какую конечную точку следует вызвать, потому что не понимает, по какому принципу сервер именует функции.
Низкая обнаруживаемость. В RPC нет никакого способа интроспектировать API или отправить запрос и начать понимать, какую функцию вызывать на основе его запросов.
Взрыв функций. Новые функции создавать очень легко. Поэтому вместо того, чтобы редактировать существующие, мы создаем новые, в результате чего получаем огромный список перекрывающихся функций, которые трудно понять.
Примеры использования RPC
Шаблон RPC получил первое применение примерно в 80-х годах, но это само по себе не делает его устаревшим. Крупные компании, такие как Google, Facebook (Apache Thrift) и Twitch (Twirp), используют внутри себя высокопроизводительные вариации RPC для чрезвычайно высокопроизводительного обмена сообщениями с низкими накладными расходами. Их массивные системы микросервисов требуют, чтобы внутренняя коммуникация была четкой и в то же время организованной в короткие сообщения.
API для команд. RPC — подходящий выбор для отправки команд в удаленную систему. Например, Slack API очень командно-ориентирован: зайти на канал, покинуть канал, отправить сообщение. Разработчики Slack API как раз и смоделировали его в стиле RPC, сделав его маленьким, компактным и простым в использовании.
Клиентские API для внутренних микросервисов. В случае прямой интеграции между единственным поставщиком и потребителем не хочется тратить много времени на передачу большого количества метаданных, как это делает REST API. gRPC и Twirp очень подходят для микросервисов благодаря высокой скорости передачи сообщений и их производительности. gRPC, с HTTP2 под капотом, способен оптимизировать сетевой уровень и повысить его эффективность при отправке с одного сервиса на другой тонн сообщений в день. Однако, если вы стремитесь не к высокой производительности сети, а к стабильному API-контакту между командами, публикующими очень отличающиеся друг от друга микросервисы, REST позаботится об этом лучше.
Протокол доступа к простым объектам (SOAP): предоставление данных в виде сервисов
SOAP — это высоко-стандартизированный протокол веб-коммуникаций, основанный на формате XML. Выпущенный Microsoft через год после XML-RPC, SOAP многое от него унаследовал. Когда на сцену вышел REST, они сначала применялись параллельно, но вскоре REST выиграл конкурс популярности.
Как работает SOAP
Формат XML тянет за собой много формальностей. В сочетании с массивной структурой сообщений он делает SOAP самым подробным стилем API.
SOAP-сообщение состоит из:
Логика SOAP API написана на языке описания веб-служб (WSDL). Этот язык описания API определяет конечные точки и описывает все процессы, которые могут быть выполнены. Это позволяет различным языкам программирования и IDE быстро налаживать коммуникацию.
SOAP поддерживает обмен сообщениями с отслеживанием состояния и без такового. В сценарии с отслеживанием состояния сервер хранит полученную информацию, которая может весить очень много. Но это оправдано для многосторонних операций и сложных транзакций.
Плюсы SOAP
Независимость от языка и платформы. Встроенная функциональность для создания веб-сервисов позволяет SOAP обрабатывать сообщения и делать ответы независимыми от языка и платформы.
Связанность с различными транспортными протоколами. SOAP гибок с точки зрения протоколов передачи и приспосабливается к более чем одному сценарию.
Встроенная обработка ошибок. Спецификация SOAP API позволяет возвращать XML-сообщение Retry с кодом ошибки и ее объяснением.
Ряд расширений безопасности. Благодаря интеграции с протоколами WS-Security качество транзакций SOAP соответствует корпоративным стандартам. SOAP гарантирует конфиденциальность и целостность внутри транзакций, обеспечивая при этом шифрование на уровне сообщений.
Минусы SOAP
В наши дни многие разработчики содрогаются при мысли о необходимости интеграции SOAP API по нескольким причинам.
Только XML. SOAP-сообщения содержат много метаданных и поддерживают только подробные XML-структуры для запросов и ответов.
Тяжеловесность. Из-за большого размера XML-файлов SOAP-сервисы требуют большой пропускной способности.
Узкоспециализированные знания. Создание серверов SOAP API требует глубокого понимания всех задействованных протоколов и их строгих правил.
Утомительное обновление сообщений. Требуются дополнительные усилия для добавления или удаления свойств сообщения — жесткая схема SOAP замедляет принятие.
Сценарии применения SOAP
В настоящее время архитектура SOAP чаще всего применяется для интеграции внутри предприятий или с их доверенными партнерами.
Надежность передачи данных. Жесткая структура SOAP, а также возможности в плане безопасности и авторизации, делают его наиболее подходящим вариантом для обеспечения соответствия формальному программному контракту между API и клиентом при соблюдении юридического контракта между поставщиком API и потребителем API. Вот почему финансовые организации и другие корпоративные пользователи выбирают SOAP.
Передача состояния представления (REST): предоставление данных в качестве ресурсов
REST — самоописательный архитектурный стиль API, определяемый набором архитектурных ограничений и предназначенный для широкого внедрения многими потребителями API.
Наиболее распространенный сегодня стиль API был впервые описан в 2000 году Роем Филдингом в его докторской диссертации. REST делает доступными данные на стороне сервера, представляя их в простых форматах — чаще всего это JSON и XML.
Как работает REST
REST определен не так строго, как SOAP. RESTful-архитектура должна соответствовать шести архитектурным ограничениям:
На самом деле, некоторые сервисы соответствуют стандарту RESTful только в определенной степени. Они берут за основу стиль RPC, разбивают более крупные службы на ресурсы и эффективно используют инфраструктуру HTTP. Но ключевое здесь — гипермедиа, иначе HATEOAS, сокращенно от “Гипертекст как двигатель состояния приложения” (Hypertext As The Engine of Application State). По сути это означает, что с каждым ответом REST API предоставляет метаданные, связывающие всю информацию о применении API. Это то, что позволяет отделить клиента от сервера. В результате и поставщик API, и потребитель API могут развиваться независимо и это не затрудняет их коммуникацию.
“HATEOAS — ключевая особенность REST. Это действительно то, что делает REST самим собой. Поскольку большинство людей не используют HATEOAS, они пользуются HTTP RPC”, — такое радикальное мнение встретилось мне на Reddit. Действительно, HATEOAS — это самая зрелая версия REST. Однако этой цели трудно достичь. Для этого требуются гораздо более продвинутые и интеллектуальные клиенты API, чем те, которые обычно создаются и действуют в наши дни. Таким образом, даже действительно хорошие REST API сегодня не всегда соответствуют стандарту. Вот почему HATEOAS в основном служит ориентиром для долгосрочного развития дизайна RESTful API.
Между REST и RPC действительно может находиться серая зона, когда сервис реализует некоторые функции REST и некоторые RPC. REST основан на ресурсе (или существительном), а не на действии (или глаголе).
В REST все делается с помощью HTTP-методов, таких как GET, POST, PUT, DELETE, OPTIONS и, надеюсь, PATCH.
Пишем SOAP клиент-серверное приложение на PHP
Всем привет!
Так случилось, что в последнее время я стал заниматься разработкой веб-сервисов. Но сегодня топик не обо мне, а о том, как нам написать свой XML Web Service основанный на протоколе SOAP 1.2.
1 Постановка задачи
1.1 Границы
В начале предлагаю разобраться с тем результатом, которого мы достигнем в конце топика. Как было объявлено выше, мы будем писать сервис по отправке sms-сообщений, а если еще точнее, то к нам будут поступать сообщения из разных источников по протоколу SOAP. После чего, мы рассматрим в каком виде они приходят на сервер. Сам процесс постановки сообщений в очередь для их дальнейшей отправки провайдеру, к сожалению, выходит за рамки данного поста по многим причинам.
1.2 Какими данными будем меняться?
Отлично, с границами мы определились! Следующий шаг, который необходимо сделать – решить какими данными мы будем обмениваться между сервером и клиентом. На эту тему предлагаю долго не мудрить и сразу для себя ответить на главные вопросы:
И все же, я что-то забыл! Если еще немного порефлексировать, то стоит отметить, что клиент за раз может отправить на сервер как одно sms-сообщение, так и некоторое их количество. Другими словами, в одном пакете данных может быть от одного до бесконечности сообщений.
В результате мы получаем, что для отправки sms-сообщения нам необходимы следующие данные:
На первый вопрос мы ответили, теперь необходимо ответить на второй вопрос. И пожалуй, я позволю себе немного с халтурить. Поэтому, с сервера мы будем присылать только булевы данные, значение которых имеет следующий смысл:
На этом мы закончили описание постановки задачи! И наконец-то приступим к самому интересному – будем разбираться что за диковинный зверь этот SOAP!
2 С чем есть SOAP?
Вообще, изначально я не планировал ничего писать о том, что такое SOAP и хотел ограничиться ссылками на сайт w3.org с нужными спецификациями, а также ссылками на Wikipedia. Но в самом конце решил написать коротенькую справочку об этом протоколе.
И начну я свое повествование с того, что данный протокол обмена данными относится к подмножеству протоколов основанных на так называемой парадигме RPC (Remote Procedure Call, удалённый вызов процедур) антиподом которой является REST (Representational State Transfer, передача репрезентативного состояния). Более подробно об этом можно прочесть в Wikipedia, ссылки на статьи находятся в самом конце топика. Из этих статей нам надо уяснить следующее: «Подход RPC позволяет использовать небольшое количество сетевых ресурсов с большим количеством методов и сложным протоколом. При подходе REST количество методов и сложность протокола строго ограничены, из-за чего количество отдельных ресурсов может быть большим». Т.е., применительно к нам это означает, что на сайте в случае RPC подхода будет всегда один вход (ссылка) на сервис и какую процедуру вызывать для обработки поступающих данных мы передаем вместе с данными, в то время как при REST подходе на нашем сайте есть много входов (ссылок), каждая из которых принимает и обрабатывает только определенные данные. Если кто-то из читающих знает, как еще проще объяснить различие в данных подходах, то обязательно пишите в комментариях!
Следующее, что нам надо узнать про SOAP – данный протокол в качестве транспорта использует тот самый XML, что с одной стороны очень хорошо, т.к. сразу же в наш арсенал попадает вся мощь стека технологий основанных на данном языке разметки, а именно XML-Schema – язык описания структуры XML-документа (спасибо Wikipedia!), который позволяет производит автоматическую валидацию поступающих на сервер данных от клиентов.
И так, теперь мы знаем, что SOAP – протокол используемый для реализации удаленного вызова процедур и в качестве транспорта он использует XML! Если почитать статью на Wikipedia, то оттуда можно узнать еще и о том, что он может использоваться поверх любого протокола прикладного уровня, а не только в паре с HTTP (к сожалению, в данном топике мы будем рассматривать только SOAP поверх HTTP). И знаете, что мне во всем этом больше всего нравится? Если нет никаких догадок, то я дам подсказку – SOAP!… Всеравно не появилось догадок?… Вы точно прочли статью на Wikipedia?… В общем, не буду вас дальше мучить. Поэтому, сразу перейду к ответу: «SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам; вплоть до спецификации 1.2)». Самое примечательное в этой строчке выделено курсивом! Я не знаю какие выводы сделали вы из всего этого, но мне видится следующее – поскольку данный протокол ну никак нельзя назвать «простым» (и видимо с этим согласны даже в w3), то с версии 1.2 он вообще перестал как-то расшифровываться! И стал называться SOAP, просто SOAP и точка.
Ну да ладно, прошу меня извинить, занесло немного в сторону. Как я писал ранее, в качестве транспорта используется XML, а пакеты, которые курсируют между клиентом и сервером называются SOAP-конвертами. Если рассматривать обобщенную структуру конверта, то он вам покажется очень знакомым, т.к. напоминает структуру HTML-страницы. В нем есть основной раздел – Envelop, который включает разделы Header и Body, либо Fault. В Body передаются данные и он является обязательным разделом конверта, в то время как Header является опциональным. В Header может передаваться авторизация, либо какие-либо иные данные, которые на прямую не относятся к входным данным процедур веб-сервиса. Про Fault особо рассказывать нечего, кроме того, что он приходит в клиент с сервера в случае возникновения каких-либо ошибок.
На этом мой обзорный рассказ про протокол SOAP заканчивается (более детально сами конверты и их структуру мы рассмотрим когда наши клиент и сервер наконец-то научатся запускать их друг в друга) и начинается новый – про компаньона SOAP под названием WSDL (Web Services Description Language). Да-да, это та самая штука, которая отпугивает большинство из нас от самой попытки взять и реализовать свое API на данном протоколе. В результате чего, мы обычно изобретаем свой велосипед с JSON в качестве транспорта. И так, что такое WSDL? WSDL – язык описания веб-сервисов и доступа к ним, основанный на языке XML (с) Wikipedia. Если из этого определения вам не становится понятным весь сакральный смысл данной технологии, то я попытаюсь описать его своими словами!
3 Введение в XML-Schema
Теперь мы много чего знаем о то, что такое SOAP, что находится у него внутри и имеем обзорное представление о том, какой стек технологий его окружает. Поскольку, прежде всего SOAP представляет собой способ взаимодействия между клиентом и сервером, и в качестве транспорта для него используется язык разметки XML, то в данном разделе мы немного разберемся каким образом происходит автоматическая валидация данных посредством XML-схем.
Предлагаю далеко не ходить и написать XML-схему для нашего sms-сообщения! Ниже представлено xml-описание sms-сообщения:
Схема нашего комплексного типа будет выглядеть следующим образом:
Эта запись читается следующим образом: у нас есть переменная «message» типа «Message» и есть комплексный тип с именем «Message», который состоит из последовательного набора элементов «phone» типа string, «text» типа string, «date» типа dateTime, «type» типа decimal. Эти типы простые и уже определены в описании схемы. Поздравляю! Мы только что написали нашу первую XML-схему!
Думаю, что значение элементов «element» и «complexType» вам стало все более-менее понятно, поэтому не будем на них больше заострять внимание и переключимся сразу же на элемент-композитор «sequence». Когда мы используем элемент-композитор «sequence» мы сообщаем о том, что элементы включенные в него должны всегда располагаться в указанной в схеме последовательности, а также все из них являются обязательными. Но не стоит отчаиваться! В XML-схемах есть еще два элемента-композитора: «choice» и «all». Композитор «choice» сообщает о том, что должен быть какой-то один из перечисленных в нем элементов, а композитор «all» – любая комбинация перечисленных элементов.
Как вы помните, то в первом разделе топика мы договорились о том, что в пакете может передаваться от одного до бесконечности sms-сообщений. Поэтому предлагаю разобраться как такие данные декларируются в XML-схеме. Общая структура пакета может выглядеть следующим образом:
Схема для такого комплексного типа будет выглядеть так:
В первом блоке идет знакомое нам декларирование комплексного типа «Message». Если вы заметили, то в каждом простом типе, входящем в «Message», были добавлены новые уточняющие атрибуты «minOccurs» и «maxOccurs». Как не трудно догадаться из названия, первый (minOccurs) сообщает о том, что в данной последовательности должно быть минимум по одному элементу типа «phone», «text», «date» и «type», в то время как следующий (maxOccurs) атрибут нам декларирует, что таких элементов в нашей последовательности максимум по-одному. В результате, когда мы пишем свои схемы для каких-либо данных, нам предоставляется широчайший выбор по их настройке!
Второй блок схемы декларирует элемент «messageList» типа «MessageList». Видно, что «MessageList» представляет собой комплексный тип, который включает минимум один элемент «message», но максимальное число таких элементов не ограничено!
На этом будем считать, что ЛикБез по схемам завершен и далее нас ждет еще одно не менее увлекательное приключение – мы будем писать свой собственный WSDL!
4 Пишем свой WSDL
Вы помните о том, что WSDL и есть наш веб-сервис? Надеюсь, что помните! Как мы его напишем, так на нем наш маленький веб-сервис и поплывет. Поэтому, предлагаю не халтурить.
Вообще, для того, чтобы у нас все работало правильно нам надо передавать клиенту WSDL-файл с правильным MIME-типом. Для этого необходимо настроить ваш веб-сервер соответствующим образом, а именно – установить для файлов с расширением «*.wsdl» MIME-тип равный следующей строке:
Но на практике, я обычно отправлял посредством PHP HTTP-заголовок«text/xml»:
и все прекрасно работало!
Хочу сразу предупредить, наш простенький веб-сервис будет иметь довольно внушительное описание, поэтому не пугайтесь, т.к. большая часть текста является обязательной водой и написав ее один раз можно постоянно копировать от одного веб-сервиса к другому!
Поскольку WSDL – это XML, то в самой первой строке необходимо прямо об этом и написать. Корневой элемент файла всегда должен называться «definitions»:
Обычно, WSDL состоит из 4-5 основных блоков. Самый первый блок – определение веб-сервиса или другими словами – точки входа.
Здесь написано, что у нас есть сервис, который называется – «SmsService». В принципе, все имена в WSDL-файле могут быть вами изменены на какие только пожелаете, т.к. они не играют абсолютно никакой роли.
После этого мы объявляем о том, что в нашем веб-сервисе «SmsService» есть точка входа («port»), которая называется «SmsServicePort». Именно в эту точку входа и будут отправляться все запросы от клиентов к серверу. И указываем в элементе «address» ссылку на файл-обработчик, который будет принимать запросы.
После того, как мы определили веб-сервис и указали для него точку входа – необходимо привязать к нему поддерживаемые процедуры:
Для этого перечисляется какие операции и в каком виде у будут вызываться. Т.е. для порта «SmsServicePort» определена привязка под именем «SmsServiceBinding», которая имеет тип вызова «rpc» и в качестве протокола передачи (транспорта) используется HTTP. Т.о., мы здесь указали, что будем осуществлять RPC вызов поверх HTTP. После этого мы описываем какие процедуры (operation) поддерживаются в веб-сервисе. Мы будем поддерживать всего одну процедуру – «sendSms». Через эту процедуру будут отправляться на сервер наши замечательные сообщения! После того, как была объявлена процедура, необходимо указать в каком виде будут передаваться данные. В данном случае указано, что будут использоваться стандартные SOAP-конверты.
После этого нам необходимо привязать процедуру к сообщениям:
Для этого мы указываем, что наша привязка («binding») имеет тип «SmsServicePortType» и в элементе «portType» с одноименным типу именем указываем привязку процедур к сообщениям. И так, входящее сообщение (от клиента к серверу) будет называться «sendSmsRequest», а исходящее (от сервера к клиенту) «sendSmsResponse». Как и все имена в WSDL, имена входящих и исходящих сообщения – произвольные.
Теперь нам необходимо описать сами сообщения, т.е. входящие и исходящие:
Для этого мы добавляем элементы «message» с именами «sendSmsRequest» и «sendSmsResponse» соответственно. В них мы указываем, что на вход должен прийти конверт, структура которого соответствует типу данных «Request». После чего с сервера возвращается конверт содержащий тип данных – «Response».
Теперь надо сделать самую малость – добавить описание данных типов в наш WSDL-файл! И как вы думаете, как описываются в WSDL входящие и исходящие данные? Думаю, что вы уже все давно поняли и сказали сами себе, что при помощи XML-схем! И вы будете абсолютно правы!
Можно нас поздравить! Наш первый WSDL был написан! И мы еще на один шаг приблизились к достижению поставленной цели.
Далее мы разберемся с тем, что нам предоставляет PHP для разработки собственных распределенных приложений.
5 Наш первый SOAP-сервер
Ранее я писал, что для создания SOAP-сервера на PHP мы будем использовать встроенный класс SoapServer. Для того, чтобы все дальнейшие действия происходили также как и у меня, вам понадобиться немного подкрутить свой PHP. Если быть еще точнее, то необходимо убедиться, что у вас установлено расширение «php-soap». Как его поставить на ваш веб-сервере лучше всего прочитать на официальном сайте PHP (см. список литературы).
После того, как все было установлено и настроено нам необходимо будет создать в корневой папке вашего хостинга файл «smsservice.php» со следующим содержанием:
То, что находится выше строчки с функцией «ini_set», надеюсь, что объяснять не надо. Т.к. там определяется какие HTTP-заголовки мы будем отправлять с сервера клиенту и настраивается окружение. В строчке с «ini_set» мы отключаем кеширование WSDL-файла для того, чтобы наши изменения в нем сразу же вступали в действие на клиенте.
Теперь мы подошли к серверу! Как видим, весь SOAP-сервер занимает всего лишь три строки! В первой строке мы создаем новый экземпляр объекта SoapServer и передаем ему в конструктор адрес нашего WSDL-описания веб-сервиса. Теперь мы знаем, что он будет располагаться в корне хостинга в файле с говорящим именем «smsservice.wsdl.php». Во второй строке мы сообщаем SOAP-серверу какой класс необходимо дергать для того, чтобы обработать поступивший с клиента конверт и вернуть конверт с ответом. Как вы могли догадаться, именно в этом классе будет описан наш единственный метод sendSms. В третьей строке мы запускаем сервер! Все, наш сервер готов! С чем я нас всех и поздравляю!
Теперь нам необходимо создать WSDL-файл. Для этого можно либо просто скопировать его содержимое из предыдущего раздела, либо позволить себе вольности и немного его «шаблонизировать»:
На этом этапе получившийся сервер нас должен устроить полностью, т.к. поступающие к нему конверты мы можем логировать и потом спокойно анализировать приходящие данные. Для того, чтобы мы могли что-либо получать на сервер, нам необходим клиент. Поэтому давайте им и займемся!
6 SOAP-клиент на подходе
Прежде всего нам надо создать файл, в котором будем писать клиент. Как обычно, мы его создадим в корне хоста и назовем «client.php», а внутри напишем следующее:
Опишем наши объекты. Когда мы писали WSDL в нем для входящего на сервер конверта описывались три сущности: Request, MessageList и Message. Соответственно классы Request, MessageList и Message являются отражениями этих сущностей в нашем PHP-скрипте.
После того, как мы определили объекты, нам необходимо создать объект ($req), который будем отправлять на сервер. После чего идут две самые заветные для нас строки! Наш SOAP-клиент! Верите или нет, но этого достаточно для того, чтобы на наш сервер начали сыпаться сообщения от клиента, а также для того, чтобы наш сервер успешно их принимал и обрабатывал! В первой из них мы создаем экземпляр класса SoapClient и передаем в его конструктор адрес расположения WSDL-файла, а в параметрах явно указываем, что работать мы будем по протоколу SOAP версии 1.2. В следующей строке мы вызываем метод sendSms объекта $client и сразу же выводим в браузере результат.
Давайте запусти и посмотрим что-же у нас наконец-то получилось!
Мне с сервера вернулся следующий объект:
И это замечательно, т.к. теперь мы точно знаем о том, что наш сервер работает и не просто работает, но еще и может возвращать на клиент какие-то значения!
Теперь посмотрим на лог, который мы предусмотрительно ведем на серверной стороне! В первой его части мы видим необработанные данные, которые поступили на сервер:
Это и есть конверт. Теперь вы знаете как он выглядит! Но постоянно на него любоваться нам вряд ли будет интересно, поэтому давайте десереализуем объект из лог-файла и посмотрим все ли у нас хорошо:
Как видим, объект десериализовался правильно, с чем я нас всех хочу поздравить! Далее нас ждет что-то более интересно! А именно – мы будем отправлять клиентом на сервер не одно sms-сообщение, а целую пачку (если быть точнее, то целых три)!
7 Отправляем сложные объекты
Давайте подумаем над тем, как же нам передать целую пачку сообщений на сервер в одном пакете? Наверно, самым простым способом будет организация массива внутри элемента messageList! Давайте это сделаем:
В наших логах числится, что пришел следующий пакет от клиента:
Что за ерунда, скажете вы? И будете правы в некотором смысле, т.к. только что мы узнали о том, что какой объект ушел от клиента, то абсолютно в том же виде он пришел к нам на сервер в виде конверта. Правда, sms-сообщения сериализовались в XML не так, как нам было необходимо – они должны были быть обернуты в элементы message, а не в Struct. Теперь посмотрим в каком виде приходит такой объект в метод sendSms:
Что нам дает это знание? Только то, что выбранный нами путь не является верным и мы не получили ответа на вопрос – «Как нам на сервере получить правильную структуру данных?». Но я предлагаю не отчаиваться и попробовать привести наш массив к типу объект:
В этом случае, нам придет уже другой конверт:
Пришедший в метод sendSms объект имеет следующую структуру:
Как по мне, то «от перемены мест слагаемых – сумма не меняется» (с). Что BOGUS, что Struct – цель нами до сих пор не достигнута! А для ее достижения нам необходимо сделать так, чтобы вместо этих непонятных названий отображалось наше родное message. Но как этого добиться, автору пока не известно. Поэтому единственное, что мы можем сделать – избавить от лишнего контейнера. Другими словами, мы сейчас сделаем так, чтобы вместо message стал BOGUS! Для этого изменим объект следующим образом:
Вдруг нам повезет и из схемы подтянется правильное название? Для этого посмотрим на пришедший конверт:
Да, чуда не произошло! BOGUS – не победим! Пришедший в sendSms объект в этом случае будет выглядеть следующим образом:
Как говорится – «Почти»! На этой (немного печальной) ноте предлагаю потихонечку закругляться и сделать некоторые для себя выводы.