Выступление Александра Шишкова, нашего руководителя отдела разработки, с докладом на CUSTIS Meetup: Russian Oracle User Group (19 декабря 2019, Москва).
физика» • Занимаюсь разработкой в области БД более 10 лет, с 2017 года — руководитель отдела разработки в CUSTIS • Oracle Certified Professional • Хобби — саморазвитие, волейбол
обмена Архитектурный стиль взаимодействия Наличие обязательной спецификации описания методов веб-сервиса (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
дополнительного ПО. Все необходимое уже имеется в СУБД, включая встроенный HHTP-сервер • Для WS автоматически генерируется описание сервиса (WSDL) • Легко разрабатывать, создание нового сервиса — это реализация нового пакета, а создание нового метода сервиса — это написание новой процедуры или функции в пакете • Автоматический парсинг входящих XML-запросов и их преобразование в соответствующие структуры PL/SQL-пакетов • Доступен в редакции Oracle Standard Edition • Для всех запросов к WS обязательна аутентификация (Basic Authentication) 12 / 56
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
Workaround — писать WSDL вручную и публиковать его (через DBMS_XDB.createResource, но URL у него будет уже другой) • OUT-переменные в пакете надо всегда задавать, как IN OUT (баг в Oracle 12с, в 19.3 до сих пор не исправлен) • Ограничения на вход/выход по аргументам типа CLOB. Workaround — передавать/принимать CLOB через массив строк • Может вести себя непредсказуемо на больших запросах (порядка 50 Мб). В лучшем случае падает с ошибкой нехватки памяти на сервере, в худшем — отдает ответ, в котором потеряна часть сообщения • Не подходит для больших нагрузок (десятки и сотни запросов к WS в секунду) 25 / 56
между внешним миром и БД 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
встроенным веб-сервером (Jetty) • На сервере приложений (WebLogic, Tomcat, GlassFish) • Три одноразовых действия перед созданием первого WS на ORDS • Скачать дистрибутив • Выполнить установку с соответствующими настройками • Запустить сервис 29 / 56
диалоге установки нужно указать • Путь к каталогу для сохранения конфигурации Параметры ORDS сохраняются в файлы — default.xml и standalone.properties • Пароль для создаваемой схемы ORDS_PUBLIC_USER. Под этим пользователем ORDS будет подключаться к БД • Использовать ли PL/SQL Gateway или нет (для APEX или миграции с mod_plsql — нужно) • Режим установки — standalone или нет • Протокол для веб-сервиса — HTTP или HTTPS 31 / 56
благодаря такой возможности во встроенном веб-сервере Jetty Для этого необходимо выполнить следующие шаги • Создать папки etc и logs в директории standalone • В созданной папке etc создать файл jetty-http.xml и прописать в нем необходимую конфигурацию (пример приведен на следующем слайде) • Перезапустить ords Пример access log 32 / 56
Проверяем, корректно ли сервис работает Переходим в браузере по адресу: http://<ip_or_host_configured>:<port>/ords/ords/ <ip_or_host_configured> — ip-адрес или имя компьютера, на котором запущен ORDS <port> — порт, указанный в конфигурации ORDS (по дефолту – 8080) • Если все настроено правильно, мы получим следующую страницу 34 / 56
доступа к таблицам/вью 4 метода GET — чтение структуры таблицы, всех строк, части строк, определенной строки POST — вставка записи PUT — обновление/вставка DELETE — удаление • Не требуется писать SQL-запросы или PL/SQL-хранимые процедуры для поддержки работы этих методов • Нельзя изменить входной/выходной формат данных, добавить дополнительную валидацию, обработку ошибок или поменять код состояния ответа • Также есть возможность получить данные о структуре таблицы и всех объектах схемы, доступных через RESTful-сервис 36 / 56
таблицы в ней в список доступных для RESTful-сервиса •Список объектов, доступных для RESTful-сервиса, можно посмотреть через вью user_ords_enabled_objects 37 / 56
запрос выдаст не более 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
таким ключом не найдена выполняется вставка строки • 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
все строки из таблицы заказов с суммой > 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
логики, управлением формата запроса и ответа и кодом состояния • Для реализации сервиса в стиле 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