Выступление Александра Шишкова, нашего руководителя отдела разработки, с докладом на CUSTIS Meetup: Russian Oracle User Group (11 февраля 2020, Москва).
• Параметры объявляются на уровне определения rest-сервиса (ORDS.define_template): http://host:<port>/ords/schema_alias/module/template/val1/val2 В URI указываются только значения параметров, порядок строго фиксирован, параметры обязательные • Через URI (в строке параметров) • Параметры объявляются через отдельный обработчик (ORDS.define_parameter): http://host:<port>/ords/...?p1=val1&p2=val2 В URI указываются в конце строки запроса URI в стандартном виде, параметры не обязательные • Параметры используются без их предварительного объявления (актуально только для GET-запросов с источником в виде SQL-запроса) http://host:<port>/ords/...?q=json_query В URI указываются в конце строки запроса в виде JSON-строки: {"p1":{"$oper":"val1"}, "p2":{"$oper":val2}}
для фильтрации ResultSet) • Используется только в GET-запросах с любым типом источника, кроме plsql/block • В качестве параметров можно использовать только атрибуты из результирующего набора (те, что перечислены в блоке SELECT указанного набора) • Большое количество операторов сравнения, например: ">" : "$gt" ">=" : "$gte" "=" : "$eq" "=" : "$ne" "<" : "$lt" "<=" : "$lte" "is null" : "$null" "is not null" : "$notnull" «like" : "$like" “between" : "$between" • JSON-строка вида {"p1":{"$eq":"val1"}, "p2":{"$qte":val2}} преобразуется в SQL-запрос:
среды можно вывести в тело запроса при помощи метода OWA_UTIL.print_cgi_env • В CGI- переменной QUERY_STRING можно достать параметры из URI, указанные после знака ? (+): не нужно отдельно объявлять каждый параметр (ORDS.define_parameter) и обращаться к нему через отдельную bind-переменную (-): подходит только для запросов, у которых в качестве обработчика используется pl/sql-блок (-): придется вручную парсить строку параметров вызова для их извлечения • Содержимое CGI-переменной CONTENT_TYPE дублирует содержимое bind-переменной :content_type
те поля в данных, которые вам нужны, не используйте лишнего • Либеральный подход отправителя: при редактировании API придерживайтесь правила обратной совместимости, чтобы потребитель смог работать с новой версией без доработок на своей стороне Было Стало Пример принципа надежности Постела на практике
имени сервиса) • В ORDS при создании новой версии REST-сервиса придется «копипастить» обвязку (template->handler->parameter) и править код pl/sql-блока (или sql-запроса), выступающего в роли обработчика • Технически данный подход противоречит архитектурному стилю RESTful, т.к. ссылка на ресурс меняется • Пользователи могут исполнять GET-запросы с поддержкой версионности в любом браузере • Легко документировать API с учетом его версионности
строке параметров) • В ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи могут исполнять GET-запросы с поддержкой версионности в любом браузере • Многие PHP-фреймворки игнорируют строку запроса, отправленную любым способом, кроме GET • Сложнее документировать API с версионностью на основе использования параметра запроса
ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи НЕ могут исполнять GET-запросы с поддержкой версионности в любом браузере • Системы кеширования могут запутаться • Разработчики системы-потребителя API могут запутаться (если они не знают про ваши заголовки) • Сложнее документировать API с версионностью на основе использования заголовка запроса
ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи НЕ могут исполнять GET-запросы с поддержкой версионности в любом браузере • Кэш-совместимый • Разработчики системы-потребителя API могут запутаться (если они не знают про ваши заголовки) • Сложнее документировать API с версионностью на основе использования заголовка запроса
это фреймворк для описания REST-сервиса и экосистема вокруг него с такими возможностями, как: • просмотр документации по веб-сервису в интерактивном режиме (с возможностью выполнять запросы) • онлайн-редактирование описания сервиса в режиме WYSIWYG • кодогенерация для серверного и клиентского кода • OpenApi specification (OAS) — это спецификация для определения REST-сервиса в формате, дружественном к пользователю и компьютеру (JSON или YAML). Текущая версия – 3.0
• Начиная с версии 17.4 ORDS выполняет автогенерацию спецификации REST-сервисов / в формате OpenApi 2.0, доступную по следующей ссылке: шаблон: http(s)://server:port/ords/<connection>/<schema-alias>/open-api-catalog/ пример: http(s)://localhost:8443/ords/test/open-api-catalog/ • Рассмотрим результат автогенерации на примере трех способов реализации REST API: • Manual Rest Service • Auto PL/SQL • AutoREST
модуля monit, который создается в тестовых целях в рамках данной презентации • После копирования ответа в swagger editor с онлайн преобразованием в YAML получаем • Рассмотрим результат автогенерации на примере 3-х способов реализации REST API: Manual Rest Service Auto PL/SQL AutoREST
вариант протокола HTTP (данные передаются в зашифрованном виде) • SSL-протокол использует ассиметричный шифр с двумя видами ключей: • Публичный (для шифрования данных, используется при передачи данных) • Приватный (для расшифровки сообщения на сервере, он всегда остается на сервере) • SSL-сертификат необходим владельцу сайта, что он успешно обрабатывал передачу данных по HTTPS Доверенные и недоверенные сертификаты • Сертификат считается доверенным, если он выдан официальным удостоверяющим центром (Certification authority, CA) • Самоподписанные сертификаты (владелец сайта выдает себе сам), сертификаты с истекшим сроком годности или сертификаты, выданные центром, который потерял доверие считаются недоверенными. При переходе на такой сайт будет выдано соответствующее предупреждение
способу проверки платформы: • DV (domain validation) – подтверждение домена, доступен для физлиц и юрлиц • OV (organization validation) – проверка подлинности компании • EV (Extended Validation) – расширенная проверка деятельности компании (налоговая отчетность) • По количеству доменных и субдоменных имен: • WildCard SSL – защищает домен и поддомены, вплоть до 3-го уровня (shop.mos.example.ru) • MD (Multidomain, SAN) – защищает до 100 доменов (example1.ru, example2.ru, …) • IDN (Internationalized Domain Name) – для корректной защиты нацдоменов (пример.рф) • SGC (Server Gated Cryptography) – помогает повысить безопасность клиентов, использующих старые браузеры • SSL-сертификат необходим владельцу сайта, что он успешно обрабатывал передачу данных по HTTPS
сертификат, если в файле standalone.properties внести следующие изменения: • Далее с помощью одной из утилит, например, openssl, переконвертировать файлы с приватным ключом и сертификатом в формат DER и в файле standalone.properties внести следующие изменения: • После выполнения этих шагов перезапустить сервис
уже устарел, используется в основном во внутрикорпоративных сетях • Логин и пароль передаются в заголовке (Authorization) в незашифрованном виде в формате base64
которая позволяет третьей стороне предоставить ограниченный доступ к защищенным ресурсам пользователя без необходимости передавать ей логин и пароль • Общая схема приложения, использующего OAuth, такова: 1) получение авторизации (token) 2) обращение к защищенным ресурсам
пользователя, может быть полностью автоматизирована Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии • На первом шаге, используя client credentials, получаем временный токен • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, получаем временный токен • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, получаем временный токен На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена • На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку • На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку • На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии • На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат
его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку На втором шаге, подставляя токен в заголовок запроса при каждом обращении к REST-сервису, получаем результат
custis
ikumatadokoro
h455h1
manfredsteyer
hinakko2
bkuhlmann
kentaroutakeda
mraible
demuyan
sakama
teamlab
mackey0225
mclloyd
eileencodes
tmm1
bkeepers
jnunemaker
productmarketing
sonatard
bryan
maltzj
geoffreycrofte
destraynor
schacon
