Веб-сервисы в Oracle? Легко! Александр Шишков Руководитель отдела разработки

О компании • Услуги — заказная разработка, продуктовая разработка, консалтинг, проектирование • Отрасли — ритейл, госсектор, банки, образование, казначейство, инвестиции • 23 года на рынке • 250 сотрудников 2 / 56

О себе • Выпускник МАИ по специальности «Прикладная математика и физика» • Занимаюсь разработкой в области БД более 10 лет, с 2017 года — руководитель отдела разработки в CUSTIS • Oracle Certified Professional • Хобби — саморазвитие, волейбол

План • Что такое веб-сервис • Способы реализации — SOAP и REST • Наш кейс • Oracle XML DB Native Web Services • ORDS • Вопросы, обсуждения

Что такое веб-сервис БД Клиент Веб-сервис Сервер приложений Внешняя система Внутренняя система Интернет SOAP/REST XML/JSON запрос XML/JSON ответ 5 / 56

No content

Способы реализации — SOAP и REST SOAP REST Стандартизованный протокол обмена Архитектурный стиль взаимодействия Наличие обязательной спецификации описания методов веб-сервиса (WSDL) Нет единого стандарта спецификации описания методов веб-сервиса HTTP(S) и SMTP, FTP, TCP, MQ и др. (с вер. 1.2) Только по HTTP(S) Формат данных — только XML Форматы данных — XML, JSON, HTML, text Поддержка методов HTTP — POST и GET (с вер. 1.2) Поддержка методов HTTP — POST, GET, PUT, DEL Акцент на исполнении удаленных сервисов Акцент на доступе к ресурсам. Каждый URL — представление какого-либо ресурса Поддерживает SSL и WS-security Поддерживает только SSL

Способы реализации — SOAP и REST Пример SOAP-запроса Пример SOAP-ответа 8 / 56

Способы реализации — SOAP и REST Пример REST-запроса Пример REST-ответа 9 / 56

Наш кейс Требования • Интеграция через WS SOAP • Простой мониторинг состояния WS — минимум изменений в инфраструктуре • Простое сопровождение и внедрение — легко разрабатывать и внедрять 10 / 56

Что же выбрать? Oracle XML DB Native Web Services 11 / 56

Oracle XML DB Native Web Services • Не требует установки дополнительного ПО. Все необходимое уже имеется в СУБД, включая встроенный HHTP-сервер • Для WS автоматически генерируется описание сервиса (WSDL) • Легко разрабатывать, создание нового сервиса — это реализация нового пакета, а создание нового метода сервиса — это написание новой процедуры или функции в пакете • Автоматический парсинг входящих XML-запросов и их преобразование в соответствующие структуры PL/SQL-пакетов • Доступен в редакции Oracle Standard Edition • Для всех запросов к WS обязательна аутентификация (Basic Authentication) 12 / 56

Oracle XML DB Native Web Services — настройка

Шаг 1: установка HTTP-порта 14 / 56

Шаг 2: конфигурация сервлета 15 / 56

Шаг 3: выдача привилегий 16 / 56

Шаг 4: настройка Access List 17 / 56

Oracle XML DB Native Web Services — создание WS

Шаг 1: создание тестовой таблицы для примера 19 / 56

Шаг 2: создание пакета с процедурой 20 / 56

Шаг 3: проверка WS Формат URL для доступа к WS: http://[server]:[port]/[servlet_name]/[DB_SCHEMA]/[WS_OBJ]?wsdl Где: [server] — доменное имя или IP-адрес сервера БД Oracle [port] — порт для доступа через HTTP [servlet_name] — имя сервлета [DB_SCHEMA] — имя схемы БД (в верхнем регистре) [WS_OBJ] — имя сервиса (в верхнем регистре). Равно имени объекта БД, в нашем случае — имя пакета Пример ссылки: http://my.server:8080/orawsv/WS_SOAP_TEST/PK_NATIVE_WS_TEST?wsdl Обратите внимание, что в URL важен регистр ! 21 / 56

Oracle XML DB Native Web Services — вызов WS

Для демонстрации вызова используем SoapUI 23 / 56

Для демонстрации вызова используем SoapUI 24 / 56

Подводные камни • Примитивный автогенератор WSDL, нет возможности его скорректировать. Workaround — писать WSDL вручную и публиковать его (через DBMS_XDB.createResource, но URL у него будет уже другой) • OUT-переменные в пакете надо всегда задавать, как IN OUT (баг в Oracle 12с, в 19.3 до сих пор не исправлен) • Ограничения на вход/выход по аргументам типа CLOB. Workaround — передавать/принимать CLOB через массив строк • Может вести себя непредсказуемо на больших запросах (порядка 50 Мб). В лучшем случае падает с ошибкой нехватки памяти на сервере, в худшем — отдает ответ, в котором потеряна часть сообщения • Не подходит для больших нагрузок (десятки и сотни запросов к WS в секунду) 25 / 56

А что выбрать для REST API? Oracle REST Data Service 26 / 56

ORDS — общее описание

ORDS • Java EE — приложение, по сути, это HTTP-интерфейс между внешним миром и БД Oracle (через встроенный JDBC-драйвер) • Позволяет организовать доступ к ресурсам в стиле RESTfull, а также построить взаимодействие в стиле RPC • Для установки ORDS не требуется никаких дополнительных лицензий, но его нужно устанавливать отдельно, он не входит в стандартную поставку Oracle • Минимальные системные требования для инсталляции • Java JDK 8 или выше • Oracle (EE, SE) 11.1 или Oracle (XE) 11.2 и выше • IE 8.0 и выше, Firefox 3.0 и выше или Chrome 2.0 и выше 28 / 56

ORDS • Поддерживается несколько вариантов развертывания • Автономный режим со встроенным веб-сервером (Jetty) • На сервере приложений (WebLogic, Tomcat, GlassFish) • Три одноразовых действия перед созданием первого WS на ORDS • Скачать дистрибутив • Выполнить установку с соответствующими настройками • Запустить сервис 29 / 56

ORDS — установка и запуск

Установка • Выполняем команду ОС java –jar ords.war • В диалоге установки нужно указать • Путь к каталогу для сохранения конфигурации Параметры ORDS сохраняются в файлы — default.xml и standalone.properties • Пароль для создаваемой схемы ORDS_PUBLIC_USER. Под этим пользователем ORDS будет подключаться к БД • Использовать ли PL/SQL Gateway или нет (для APEX или миграции с mod_plsql — нужно) • Режим установки — standalone или нет • Протокол для веб-сервиса — HTTP или HTTPS 31 / 56

Установка ORDS даже в автономном режиме может писать access log благодаря такой возможности во встроенном веб-сервере Jetty Для этого необходимо выполнить следующие шаги • Создать папки etc и logs в директории standalone • В созданной папке etc создать файл jetty-http.xml и прописать в нем необходимую конфигурацию (пример приведен на следующем слайде) • Перезапустить ords Пример access log 32 / 56

Установка Пример содержимого файла jetty-http.xml для запуска access-logs 33 / 56

Запуск • Выполняем команду ОС java –jar ords.war standalone • Проверяем, корректно ли сервис работает Переходим в браузере по адресу: http://:/ords/ords/ — ip-адрес или имя компьютера, на котором запущен ORDS — порт, указанный в конфигурации ORDS (по дефолту – 8080) • Если все настроено правильно, мы получим следующую страницу 34 / 56

ORDS — AutoREST

AutoRest Позволяет легко и быстро сгенерировать RESTful-сервис для организации прямого доступа к таблицам/вью 4 метода GET — чтение структуры таблицы, всех строк, части строк, определенной строки POST — вставка записи PUT — обновление/вставка DELETE — удаление • Не требуется писать SQL-запросы или PL/SQL-хранимые процедуры для поддержки работы этих методов • Нельзя изменить входной/выходной формат данных, добавить дополнительную валидацию, обработку ошибок или поменять код состояния ответа • Также есть возможность получить данные о структуре таблицы и всех объектах схемы, доступных через RESTful-сервис 36 / 56

AutoRest •В SQLDeveloper можно в несколько кликов включить схему и таблицы в ней в список доступных для RESTful-сервиса •Список объектов, доступных для RESTful-сервиса, можно посмотреть через вью user_ords_enabled_objects 37 / 56

AutoRest • Вывод списка доступных через RESTful-сервис объектов схемы http://localhost:8888/ords/rest_test/metadata-catalog/ • Вывод структуры таблицы http://localhost:8888/ords/rest_test/metadata-catalog/orders/ Виды GET-запросов для чтения метаданных 38 / 56

AutoRest • Вывод всех строк таблицы http://localhost:8888/ords/rest_test/orders/ На самом деле запрос выдаст не более N строк, где N — размер пагинации • Вывод информации по строке через первичный ключ http://localhost:8888/ords/rest_test/orders/2751 • Вывод части строк (с использованием параметров offset и limit) http://localhost:8888/ords/rest_test/orders/?offset=5&limit=10 • Вывод строк, подходящих под условия запроса Например, отбираем все строки из таблицы заказов с суммой > 9000 http://localhost:8888/ords/rest_test/orders/?q={“total_summa”:{“$gte”:9000}} Виды GET-запросов для чтения метаданных 39 / 56

AutoRest Вставка осуществляется по одной записи • URL: http://localhost:8888/ords/rest_test/orders/ • Method: POST • Header: Content-Type: application/json • Raw Payload: {"id_order": 99999, "order_num": “ZK-256479", "total_summa": 98765.43} • При успешной операции возвращается HTTP_CODE = 201 (запись вставлена) POST-запрос для вставки строки 40 / 56

AutoRest Обновление осуществляется по одной записи • Если запись с таким ключом не найдена выполняется вставка строки • URL: http://localhost:8888/ords/rest_test/orders/9999 • Method: PUT • Header: Content-Type: application/json • Raw Payload: {"order_num": “ZK-256479", "total_summa": 90240} • При успешной операции возвращается HTTP_CODE = 200 (ok) PUT-запрос для обновления строки 41 / 56

AutoRest Удаляются строки, подходящие под условие запроса • Например, удаляем все строки из таблицы заказов с суммой > 9000 • URL: http://localhost:8888/ords/rest_test/orders/?q={“total_summa”:{“$gte”:9000}} • Method: DELETE • При успешной операции возвращается HTTP_CODE = 200 (ok) c телом ответа {"rowsDeleted": 1} DELETE-запрос для удаления строк 42 / 56

ORDS — Manual Rest API

Manual Rest • Для разработки RESTful-сервиса с реализацией дополнительной бизнес- логики, управлением формата запроса и ответа и кодом состояния • Для реализации сервиса в стиле RPC, обработчиком которого будет хранимая процедура Основные термины ORDS_SCHEMA — alias схемы БД, доступной для REST-сервисов ORDS_MODULE — структурная единица (контейнер), который объединяет несколько отдельных REST-сервисов в одну группу ORDS_TEMPLATE — отдельный REST-сервис, обслуживающий определенный набор методов для ресурса ORDS_HANDLER — обработчик запроса для конкретного REST-сервиса (для каждого HTTP-метода он свой) Основные вью для просмотра ORDS-объектов user_ords_schemas user_ords_modules user_ords_templates user_ords_handlers 44 / 56

Manual Rest URL формируется по следующему принципу • BASE ORDS URL : http://localhost:/ords/ • SCHEMA : http://localhost:/ords/schema_alias/ • MODULE : http://localhost:/ords/schema_alias/module/ • TEMPLATE : http://localhost:/ords/schema_alias/module/template/ 45 / 56

Manual Rest Пример реализации GET-запроса: вывод всех сессий на сервере 46 / 56

Manual Rest Пример реализации GET-запроса: вывод информации по указанной сессии 47 / 56

Manual Rest Пример реализации GET-запроса: вывод информации по указанной сессии 48 / 56

Manual Rest Пример реализации GET-запроса: вывод информации по объектам схемы в формате xml 49 / 56

Manual Rest Пример реализации GET-запроса: вывод информации по объектам схемы в формате xml 50 / 56

Manual Rest Пример реализации GET-запроса: вывод информации по объектам схемы в формате xml 51 / 56

Manual Rest Пример реализации POST-запроса: обработка входного запроса для пакетной вставки строк 52 / 56

Manual Rest Пример реализации POST-запроса: обработка входного запроса для пакетной вставки строк 53 / 56

Manual Rest Пример реализации POST-запроса: обработка входного запроса для пакетной вставки строк 54 / 56

TO BE CONTINUED… • ORDS SSL Configuration • Authentication • Open API 2.0 (Swagger) 55 / 56

Спасибо за внимание! Вопросы? Александр Шишков Руководитель отдела разработки