что такое wsdl простыми словами
Разработка и тестирование веб сервисов на PHP/SoapUi
Веб сервисы достаточно удобный метод организовать клиент-серверное общение, особенно если обе стороны используют разные платформы. Формализация общения позволяет однозначно определить словарь сообщений и применить огромное количество уже существующих библиотек и методик. Enterprise платформы (.net, jee) включают множество утилит для дизайна, разработки и тестирования веб сервисов, и многие из этих утилит вполне применимы на небольших проектах.
Эта статья описывает создание простого веб сервиса на php и его автоматизированное тестирование.
Веб сервис будет реализовывать три операции: реверс строки, суммирование и эхо.
Наш план: сначала планируем и объявляем, потом реализовываем. Таким образом у мы последовательно пройдем три этапа:
1. WSDL first — объявим наш словарь, или создадим контракт
2. Реализуем контракт на PHP
3. Автоматизируем процесс тестирования
Требования
Все инструменты open source
PHP 5+
NUSOAP — php библиотека для работы с WS (http://sf.net/projects/nusoap)
Eclipse от eclipse.org, версия for EE developers — мы воспользуемся только WSDL редактором.
SoapUI — soapui.org. Пакет для тестирования веб сервис ориентированных приложений
WSDL first
WSDL это контракт, т.е. соглашение по которому сервер обязуется обслуживать клиента и указывает параметры этого процесса. По сути это XML документ, который описывает методы, типы данных и другие параметры.
Существует два подхода к написанию веб сервисов:
1. Разработчик пишет программный код и средства платформы реализуют WSDL автоматически
2. Дизайнер или архитектор описывает интерфейсы в WSDL и под них имплементируют логику.
Многие разработчики идут по первому пути, т.е. они пишут код (java, c# и тп) м не задумываются о веб сервисах. С точки зрения разработчика это явный плюс.
Но эта стратегия сильно проигрывает в крупных проектах, с несколькими распределенными командами. В идеале, мы бы хотели стабилизировать интерфейсы и, например, позволить команде пишущей клиента не ждать релизов от команды пишущей сервер. И QA тоже должны начать писать тесты как можно раньше.
Таким образом мы приходим к необходимости написания WSDL в первую очередь.
Создадим WSDL с помощью Eclipse:
После запуска эклипса, создайте проект New->Other->Web services->WSDL
Имя файла укажите «ws.wsdl», namespace: «sample»
(namespace не имеет отношения к WS, так как является обычной практикой работы с XML)
После создания вы получите новый WSDL с одной операцией «NewOperation».
Удалите ее и создайте новую с именем «reverse». Клики по стрелкам позволяют просмотреть все параметры, но менять их не обязательно.
Сама операция revers будет получать строку от клиента и возвращать ее в обратном порядке следования символов, т.е. нужен один IN параметр String и результат String. Добавьте их в вашу операцию.
Вы можете сами добавить операции ping и sum с необходимыми параметрами (или откройте wsdl из архива, см линк в конце)
Сохраните ваши изменения как ‘ws.wsdl’
Теперь у вас есть контракт, и вы можете отдать его разработчикам клиента, сервера, QA и тд. Все они могут начинать работу независимо друг от друга.
Реализуем WS на PHP
Создайте директорию soap в вашей public_html и скопируйте ws.wsdl (соответственно файл доступен как yourserver/soap/ws.wsdl)
Серверный код мы поместим в ws.php, и localhost/soap/ws.php будет линком вашего веб сервиса.
Дополнительно распакуйте nusoap в ‘soap’.
Перейдем к непосредственной реализации логики:
Первые строки вашего ws.php:
require(‘lib/nusoap.php’);
$server = new soap_server(‘ws.wsdl’);
Эта конструкция сообщает скрипту, что надо реализовать указанный контракт. Сам вызов будет обработан:
Это все, что необходимо для поддержки WS, остальное это ваша логика — бизнес методы.
Для каждой операции из контракта надо создать php функция с эквивалентным именем.
Вот пример всего файла:
service($HTTP_RAW_POST_DATA);
Если вы откроете в браузере: localhost/soap/ws.php — вы увидите все доступные операции.
Теперь ваш сервер готов обслуживать клиентов! Но к вас нет клиента… и мы не будем его писать, так как применим автоматизированное тестирование…
(не забудьте, что мы будем тестировать веб сервис, что является интеграционным тестированием, и не отменяет написания юнит тестов на бизнес методы)
Тестируем с SoapUI
SoapUI это великолепное средство для тестирования и разработки систем на основе веб сервисов. Эта утилита достойна отдельной статьи, поэтому мы воспользуемся лишь одной из опций — протестируем наш сервер, эмулируя клиента.
Для этого нам понадобятся несколько кликов…
Запустите soapUi и создайте новый проект, в качестве wsdl укажите наш ws.wsdl. Не меняйте другие параметры.
Результатом будет test suit в дереве и окно пакета (его можно закрыть.)
Сам тестовый пакет содержит ряд шагов, по одному на каждую операцию. Как вы уже догадались, это и есть элементы для проверки вашего сервиса. Вы можете запустить их все разом, или по одному, в зависимости от ваших целей.
Мы попробуем запускать их по одному, предварительно настроив.
Кликните на шаге reverse, вы увидете две панели, панель запроса и панель ответа. Контент запроса генерируется автоматически на основе контракта с знаками вопроса на месте данных. В нашем случае у нас есть один placeholder для строки, введем значение 123456789
Проверьте что target url наверху панели указывает на ваш сервис и вы можете запустить шаг на выполнение использую зеленый треугольник на панели.
Запрос уйдет на сервер и вторая панель отобразит ответ, который должен содержать 987654321 — входной параметр в обратном порядке.
Визуально мы можем убедится, что наша система работает корректно, но есть минус — мы видим это визуально. В идеале мы бы хотели это автоматизировать для регрессивного тестирования.
Обратите внимание на иконку сразу за ‘Run’. Здесь собраны условия для проверки ответа и вы можете добавить условие наличие строки 987654321 в ответе.
Теперь у вас есть автоматизированный тест, который может выполняться как вручную, так и сервером сборки.
Дао Вебсервиса. (Или да хватит же изобретать велосипеды!)
Недавно на Хабре была опубликована статья под провокационным заголовком и призывом к прекращению изобретений велосипедов в API-строении. Поскольку тема мне интересна, то я просто не мог пройти мимо.
Увы, реальность за хабракатом меня сильно разочаровала — я увидел очередной велосипед, да еще и с квадратными колесами. (Коллеги, ничего личного, только техническое обсуждение.) Правда, авторы честно сказали, что увидели на нескольких сайтах модное слово REST и решили сделать по нему. Только вот поняли они этот «РЭСТ» по-своему, примерно как Дед Щукарь читал и понимал толковый словарь.
В этом топике я призываю по-настоящему покончить с велосипедами в API сайтов. Ведь получается какой анекдот: АПИ разрабатывается для упрощения доступа к сайту и легкости подключения внешних систем, а получается такой, что с ним еще сложнее, чем без него 🙂
Чуть ниже под катом я подпишу смертный приговор всем велосипедам в универсальных API. Чтобы не быть голословным, я все проиллюстрирую примерами.
Но должен предупредить сразу — после прочтения статьи вы не сможете без рвотного рефлекса смотреть на очередной велосипед Васи Пупкина под гордым названием «универсальное API сайта».
Итак на сегодня наиболее распространенными способами доступа к API сайтов являются:
1. XML-RPC.
2. REST (с оговоркой, что это не протокол, а подход).
3. SOAP.
Базовые технологии и сравнение
XML-RPC
Примерно так же просто выглядят сообщения об ошибках. Такой ответ легко распарсить даже человеку, не говоря уже про машину. Такая простота сослужила ему двоякую службу: с одной стороны он не был принят заказчиком и не стал стандартом, а с другой — понравился толпе простых незамороченных программистов. Этим ребятам нужно было простое и надежное средство обмена информацией между системами, они не хотели заморачиваться на такую хрень как красивый УРЛ, схема документа и прочие академизмы. Первое, что они хотели получить — простую работающую систему. И до сих пор XML-RPC помогает им в этом.
Итак:
+ : простота, краткость сообщений, минимальная проверка формата данных,
— : недостаточная строгость, требуется отдельное описание сервиса.
POST /api/object.php?object_id=445&action=delete&user_id=255&auth_key=0Jf4tet5 HTTP/1.1
При этом, если XML-RPC использует из HTTP-протокола только транспортную часть для передачи XML-ки запроса/ответа, то REST задействует HTTP по-полной: здесь и авторизационные заголовки, content-negotiation — предпочтения по формату, языку, кодировке и виду ответа, различные служебные заголовки, безгеморная передача бинарных данных и т.п. Ошибки хорошо описываются кодами HTTP 4xx и 5xx. Можно видеть, что REST — органичная надстройка над HTTP. Это неудивительно ведь Рой — один из разработчиков протокола HTTP. Вообще, чем больше я разбираюсь с этим протоколом тем больше мне кажется, что он опередил свое время лет на 20, и чем дальше развивается веб, тем больше возможностей мы из него используем.
Само тело сообщения может передаваться в разных форматах: классическом XML либо гиковском JSON. Вообще, REST это не протокол, это подход, и как раз здесь заключена его гибкость, он как бы говорит нам: «Ребята, берите базовые принципы, а дальше делайте как вам удобно». Близость к HTTP-протоколу упрощает и ускоряет его обработку веб-серверами.
Итак:
+ : гибкость, простота, скорость обработки (особенно важно для крупных сайтов), органичность протоколу, мультиформатность, компактность.
— : отсутствие строго контроля данных, из практических соображений приходится выходить за рамки идеальной модели.
— Фак май мозг! — воскликнете вы и будете абсолютно правы — Это что же, ради передачи фитюльки на 10 байт мне надо всю эту лабуду писать?
— Да — скажет Логика, и вы, засучив рукава пойдете учить всю эту кучу технологий.
— Сюда еще и XML Schema приплели зачем-то? Какого хрена? А вы уверены, что эти ребята правильно понимают смысл слова «Simple»? — такие мысли будут вас посещать, и это хорошо — вы на верном пути.
Но и это не все: чем больше копаешься в SOAP тем больше всяких разных технологий вылазит на тебя. Когда вы дойдете до WSDL (Язык описания веб-сервисов), вы поймете почему, начиная с какой-то версии, разработчики перестали воспринимать название SOAP как аббревиатуру, а начали понимать буквально — soap («мыло»). В этот момент ваши мысли будет занимать одна идея: почему во всем этом зоопарке технологий отсутствует технология rope («веревка»).
Еще через какое-то время вы воскликните: «Ну нафиг, давайте уж без меня: сами придумали — сами и возитесь. Я вам не машина мегабайты иксэмеля в мозгу парсить!».
Поздравляю: теперь вы постигли дао вебсервисов!
Да! Дао веб-сервиса именно в этом и состоит: это язык общения машин и человеку нафиг не надо туда лезть. Надо просто его использовать. Ведь когда вам нужна какая-то программа, вы ее запускаете, а не лезете в бинарный код, чтобы исполнять его в мозгу. Точно так же вы не отправляете HTTP-запросы руками в командной строке, а используете браузер. Так зачем здесь лезть в эту гопу голыми руками, да еще хвастаться кто залез по локоть, а кто по самое плечо? Надо просто его использовать.
Просветленные API
API сайта и веб-сервисы — это не что-то милостиво спущенное на нас с небес создателями сайта! Это банальная библиотека функций, которую мы можем встроить в свою программу. Этот вывод становится совершенно естественным, когда вы начинаете мыслить глобально за пределами своего компьютера.
Если вам нужна новая уже готовая либа в проекте, что вы делаете? Скорее всего просто скачиваете, устанавливаете и используете? Пишете в начале программы use/require/import/include/… а дальше просто вызываете функции. Почему же работа с веб-библиотекой должна быть сложнее?
Вот теперь, просветлившись, мы можем начать работать с просветленным API.
Сейчас в качестве примера мы 1 минуту сделаем работу с API Аэрофлота, будем подглядывать за табло Шереметьево без отрыва задницы от стула. Я беру свой любимый язык и на нем пишу все примеры. Уверен, в вашем языке есть аналогичные модули. Ну а если их там нет, то самое время задуматься, так ли взаимна ваша любовь 😉
Вот тут аэрофлот подробно расписывает свое чудесное API. На первый взгляд, описание достаточно убогое — чисто перечисление методов и параметров. А как же это вызывать, как парсить, что вообще делать? А это уже не наши заботы — пусть об этом болит голова у машины — она же железная, а свою мне не хочется грузить фуфлом. Поэтому моя задача найти машинночитаемое описание сервиса — тот самый WSDL и скормить его компу.
Стойте-стойте, а как же вся эта лабуда с XML, REST, передачей параметров, парсингом ответов и всеми прочими атрибутами «крутого» API?
Лучше всего на это отвечает фильм «Матрица», кадр из которого мне захотелось вынести в заголовок:
Только перестав думать о ложке сайтовом API как о чем-то реальном, сложном, можно начать гнуть ее комфортно использовать.
Это и есть просветленное API — прозрачное и светлое настолько, что вы его не замечаете, когда работаете. Для вас это просто локальная библиотека. А вся остальная механика с сетевыми заморочками происходит где-то внутри и вас не напрягает.
Как отличить сайтовое API от говна.
Полагаю, внимательный читатель уже догадался?
Когда вместо простой, прозрачной и удобной работы с API сайта вам приходится морочиться с тем, как бы отправить запрос этому сайту и почему он не хочет принимать так старательно сформированный с помощью curl-а запрос, то вывод должен быть однозначным. Вам подсунули неправильный шоколад.
Выводы
В наше время наличие API для сайта претендующего на внимание программистов, всевозможные интеграции и прочее — не повод для гордости, а предмет первой необходимости. Но мало сделать API, даже если вы используете самые модные принципы — надо его сделать удобным и прозрачным. И технология передачи данных здесь имеет значение 10-й важности — это вообще не нужно прикладному программисту. Он должен просто взять и использовать вашу библиотеку.
Если вы хотите получить его внимание, чтобы он потратил свое время на интеграцию с вами — сделайте первый шаг — потратьте время на него. Дайте ему очень простую и понятную библиотеку.
Не надо кивать на то, что «мы сделали как твиттер — дали REST-подобный интерфейс». Вы забываете главное — у твиттера на каждый язык программирования по 5-10 библиотек, которые можно просто скачать и использовать не заморачиваясь на протокол rest/xmlrpc/soap.
3) WSDL
Что такое WSDL?
Язык описания веб-служб (WSDL) — это файл на основе XML, который в основном сообщает клиентскому приложению, что делает веб-служба. Файл WSDL используется для краткого описания того, что делает веб-служба, и предоставляет клиенту всю информацию, необходимую для подключения к веб-службе и использования всех функций, предоставляемых веб-службой.
В этом руководстве мы сосредоточимся на последнем пункте, который является наиболее важной частью веб-служб, а именно на WSDL или языке описания веб-служб.
Файл WSDL используется для краткого описания того, что делает веб-служба, и предоставляет клиенту всю информацию, необходимую для подключения к веб-службе и использования всех функций, предоставляемых веб-службой.
В этом уроке вы узнаете
Структура документа WSDL
Документ WSDL используется для описания веб-службы. Это описание необходимо, чтобы клиентские приложения могли понять, что на самом деле делает веб-служба.
Сам файл WSDL может выглядеть очень сложным для любого пользователя, но он содержит всю необходимую информацию, которая потребуется любому клиентскому приложению для использования соответствующего веб-сервиса.
Ниже приведена общая структура файла WSDL.
Здесь следует отметить одну ключевую вещь: определение сообщений, то есть то, что передается по протоколу SOAP, фактически определено в документе WSDL.
Документ WSDL фактически сообщает клиентскому приложению, какие типы сообщений SOAP отправляются и принимаются веб-службой.
Другими словами, WSDL похож на открытку с адресом определенного места. В адресе указываются данные лица, доставившего открытку. Следовательно, таким же образом файл WSDL представляет собой открытку с адресом веб-службы, которая может предоставить все функции, которые хочет клиент.
Ниже приведена схема структуры файла WSDL
Элементы WSDL
Файл WSDL содержит следующие основные части
Например, может существовать тип данных с именем EmployeeDataType, который может иметь 2 элемента с именем «EmployeeName» типа string и «EmployeeID» с номером типа или целым числом. Вместе они образуют структуру данных, которая затем становится сложным типом данных.
тег используются для инкапсуляции каждого входного и выходного сообщения в одну логическую операцию. Таким образом, может существовать операция под названием «GetEmployee», которая объединяет входное сообщение о принятии EmployeeID из клиентского приложения и последующей отправке EmployeeName в качестве выходного сообщения.
тег используется для привязки операции к конкретному типу порта. Это связано с тем, что когда клиентское приложение вызывает соответствующий тип порта, оно сможет получить доступ к операциям, связанным с этим типом порта. Типы портов похожи на интерфейсы. Поэтому, если клиентскому приложению необходимо использовать веб-службу, ему необходимо использовать информацию о привязке, чтобы обеспечить возможность подключения к интерфейсу, предоставляемому этой веб-службой.
Почему WSDL
Веб-сервис имеет следующие ключевые функции
Файл WSDL написан на простом старом XML. Причина, по которой он находится в XML, заключается в том, что файл может быть прочитан любым языком программирования.
Так вот, где сервис внедряется. Если у вас нет WSDL-файла и вы хотите, чтобы класс Java использовал веб-сервис, вам потребуется много усилий для написания кода.
Часть сообщения WSDL
Этот элемент в основном используется для описания данных, которыми обмениваются веб-сервис и клиентское приложение.
Каждый веб-сервис всегда будет иметь 2 типа сообщений,
Каждое сообщение, в свою очередь, будет иметь элемент
, который используется для описания параметра, используемого входным и выходным сообщением.
Ниже приведен простой пример того, как выглядит сообщение для веб-службы. Функциональность веб-службы заключается в предоставлении названия «Учебника» после того, как «Идентификатор учебника» передан в качестве параметра веб-службе.
Привязка типа порта
Порты используются в WSDL для определения одной полной операции, предлагаемой веб-службой.
В предыдущей теме мы видели, что наш веб-сервис предоставил 2 сообщения, одно для ввода с именем «TutorialNameRequest», а другое для вывода с именем «TutorialNameResponse». Вместе форма ввода и вывода сообщения известна как одна полная операция.
WSDL предоставляет элемент с именем
, который используется для определения операций, предоставляемых веб-службой.
Итак, в нашем примере выше мы можем отметить следующее:
В дополнение к элементу
есть также элемент , который используется для определения способа передачи сообщений.
Создание файла WSDL
Файл WSDL создается всякий раз, когда веб-сервис создается на любом языке программирования.
Ниже приведен пример файла WSDL, созданного в Visual Studio.
Приведенный выше файл WSDL выглядит очень пугающим для любого пользователя, мы подробно рассмотрим различные части в последующих уроках, но сейчас давайте кратко рассмотрим, что на самом деле делает каждый раздел файла WSDL.
Публикация примера веб-сервиса
Теперь давайте рассмотрим пример того, как мы можем опубликовать веб-сервис и использовать его с помощью Visual Studio.
В этом примере мы создадим веб-сервис с одним WebMethod. Этот метод будет принимать параметр Integer с именем «TutorialID». Веб-метод затем возвращает строку с именем «Веб-службы».
Затем мы создадим консольное приложение, которое будет использовать этот веб-сервис и соответственно вызовет наш веб-метод.
Давайте посмотрим на шаги, необходимые для выполнения этого примера.
Шаг 1) Первый шаг — создать свой веб-сервис. Подробное описание того, как создается веб-проект Asp.Net и веб-служба, было объяснено здесь; Пожалуйста, выполните те же шаги, чтобы создать проект и веб-сервис соответственно. Ключевой частью является ввод приведенного ниже кода в файл веб-сервисов.
Объяснение кода:
Шаг 2) После того, как мы определили файл веб-сервисов, следующим шагом будет создание клиентского проекта, который будет использовать этот веб-сервис.
Давайте создадим простое консольное приложение, которое вызовет этот веб-сервис, вызовет «Guru99WebService» и затем отобразит вывод веб-метода на экране журнала консоли. Выполните следующие шаги, чтобы создать консольное приложение.
Щелкните правой кнопкой мыши файл решения Visual Studio и выберите опцию Добавить-> Новый проект
Шаг 3) На этом этапе
После того, как вы нажмете кнопку OK на приведенном выше экране, вы сможете увидеть проект в обозревателе решений в Visual Studio.
Шаг 4) На этом этапе вы устанавливаете консольное приложение DemoApplication в качестве запускаемого проекта. Это сделано для того, чтобы приложение запускалось первым при запуске всего проекта Visual Studio. Это консольное приложение, в свою очередь, вызывает веб-сервис, который будет автоматически запущен Visual Studio.
Чтобы выполнить этот шаг, щелкните правой кнопкой мыши проект DemoApplication и выберите параметр «Сделать стартовым проектом».
Шаг 5) Следующим шагом является добавление сервисной ссылки нашего «Guru99Webservice» в наше консольное приложение. Это сделано для того, чтобы DemoApplication мог ссылаться на веб-сервис и все веб-методы в веб-сервисе.
Для этого щелкните правой кнопкой мыши файл проекта DemoApplication и выберите пункт меню Add-> Service Reference.
Шаг 6) На этом шаге мы предоставим различные значения, необходимые для добавления нашей ссылки на услугу.
Когда мы нажимаем кнопку «ОК», весь необходимый код для доступа к этой веб-службе будет добавлен в наше приложение консоли DemoApplication, как показано ниже.
На снимке экрана показано, что «Guru99Webservice» был успешно добавлен в наше консольное приложение.
Шаг 7) Следующим шагом является добавление кода в наше консольное приложение для доступа к веб-методу в нашем веб-сервисе. Откройте файл кода Program.cs, который автоматически поставляется с консольным приложением, и добавьте приведенный ниже код.
Объяснение кода: —
Вывод
Если все вышеперечисленные шаги выполнены и DemoApplication запущен, будут отображены следующие выходные данные.
Из этого вывода мы ясно видим, что DemoApplication вызывает наш веб-сервис и что строка, возвращенная веб-сервисом, отображается в нашем журнале консоли.
Резюме