Конечные точки ODataDB
Содержание
- Введение
- Конечные точки API
- Конечные точки страниц редактирования
- Конечные точки домашних страниц
- Конечные точки страниц аутентификации
- Конечные точки операций аутентификации
- Конечные точки управления приложением
- Статические файлы
Введение
Конечные точки ODataDB делятся на три основные категории:
- Статические файлы
- Конечные точки управления приложением
- Конечные точки на основе подключений
Конечные точки подключений включают следующие типы:
- Конечные точки API
- Конечные точки страниц редактирования
- Конечные точки домашних страниц
- Конечные точки страниц аутентификации
- Конечные точки операций аутентификации
ODataDB создает наборы конечных точек для каждого подключения, определенного в файле appsettings.
Например, файл appsettings.json
может выглядеть так:
{ "ConnectionStrings": { "mssql": { "ProviderName": "System.Data.SqlClient", "ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=master;User ID=user;Pwd=pass" } } }
В этом случае ODataDB создаст следующие конечные точки:
- https://odatadb/v4/mssql/
- https://odatadb/edit/mssql/
- https://odatadb/home/mssql/
- https://odatadb/login/mssql
- https://odatadb/auth/mssql/
Здесь v4
, edit
, home
, login
и auth
— это корневые сегменты.
Имена корневых сегментов можно изменить в файле appsettings.
Корневые сегменты и сегменты подключений
По умолчанию ODataDB поддерживает два формата конечных точек:
- https://odatadb/v4/mssql/
- https://odatadb/mssql/v4/
Вы можете выбрать один из вариантов, настроив ConnectionSegment
в файле appsettings.
Сегмент языка
ODataDB позволяет указать желаемый язык в URL следующим образом:
- https://odatadb/edit/mssql/en-us/
- https://odatadb/edit/mssql/ru-ru/
Клиент JavaScript использует указанный язык для загрузки языковых ресурсов и форматирования чисел и дат.
Клиент JavaScript отправляет запросы к серверу с указанным языком. Например:
- https://odatadb/v4/mssql/en-us/
- https://odatadb/v4/mssql/ru-ru/
ODataDB использует язык для перевода модели (имена, комментарии и т.д.), если это поддерживается базой данных.
Также ODataDB передает значения языка в параметры хранимых процедур, указанные в настройке LanguageParameters
, что позволяет возвращать данные на нужном языке.
См. подробности в Руководстве разработчика.
Языковые папки
В каталоге wwwroot
можно создать подкаталоги для языков, например, en-us
, ru-ru
, zh-hans
и т.д.
ODataDB ищет файлы в этих папках в зависимости от культуры, указанной в URL.
Например, для запроса /edit/mssql/ru-ru/
будет загружен edit.htm
из wwwroot
, если его нет в ru-ru
. Для /edit/mssql/zh-cn/
будет загружен существующий файл wwwroot/zh-hans/edit.htm
(для стандартного пакета поставки).
Для статического файла, например, /zh-cn/sample01.htm
, будет загружен wwwroot/en-us/sample01.htm
, а для /ru-ru/sample01.htm
— существующий wwwroot/ru-ru/sample01.htm
.
Папку языка по умолчанию можно задать в настройке DefaultLanguageFolder
.
Сегменты контейнера
По умолчанию ODataDB включает в модель сервиса все объекты базы данных, доступные пользователю.
ODataDB создает контейнер default
в схеме default
.
Контейнер можно указать в третьем сегменте URL.
Следующие URL используют одну и ту же модель:
- https://odatadb/v4/mssql/
- https://odatadb/v4/mssql/default/
- https://odatadb/v4/mssql/default/en-us/
Разработчики могут создать специальные представления (например, QueryList) для отображения только определенных объектов, таких как buyer
и seller
. В этом случае ODataDB позволяет использовать такие представления как контейнеры:
- https://odatadb/v4/mssql/buyer/
- https://odatadb/v4/mssql/seller/
В обоих случаях модель включает все объекты, доступные пользователю, но сервисные документы содержат только объекты из представлений QueryList.
См. подробности в Руководстве разработчика.
Конечные точки API
Конечные точки API возвращают сервисные документы, метаданные и данные в соответствии со стандартами OData, а также расширенные настройки.
ODataDB создает конечные точки для каждого подключения, заданного в файле appsettings.
Формат конечных точек (корень в первом сегменте):
<domain>
/<API root>
/<connection name>
/<domain>
/<API root>
/<connection name>
/<container name>
/<domain>
/<API root>
/<connection name>
/<container name>
/<language>
/<domain>
/<API root>
/<connection name>
/<language>
/
Как указано выше, можно менять местами корень и подключение.
Корень по умолчанию — v4
. Имя корня можно изменить в свойстве ApiRoot
файла appsettings.
Примеры конечных точек:
- https://odatadb.savetodb.com/v4/mssql-023/
- https://odatadb.savetodb.com/v4/mssql-023/default/
- https://odatadb.savetodb.com/v4/mssql-023/default/ru-ru/
- https://odatadb.savetodb.com/v4/mssql-023/ru-ru/
Эти конечные точки возвращают сервисные документы.
Чтобы получить метаданные сервиса, добавьте сегмент $metadata
.
Чтобы получить данные, добавьте имя объекта. Для функций добавьте круглые скобки.
Например:
- https://odatadb.savetodb.com/v4/mssql-023/cashbook
- https://odatadb.savetodb.com/v4/mssql-023/usp_cashbook()
ODataDB поддерживает следующие расширения (в последнем сегменте): $excel_formats
, $excel_format
, $table_format
, $workbooks
, $definition
.
Сегмент $definition
возвращает определение объекта (если у пользователя есть разрешение VIEW DEFINITION
).
Например: https://odatadb.savetodb.com/v4/mssql-023/usp_cashbook/$definition.
Другие расширения требуют настройки в базе данных.
См. онлайн примеры и подробности в Руководстве разработчика.
Конечные точки страниц редактирования
Эти конечные точки возвращают страницы для просмотра и редактирования данных.
ODataDB создает конечные точки для каждого корня, заданного в секции EditRoots
файла appsettings, по следующим шаблонам:
<domain>
/<edit root>
/<connection name>
/<domain>
/<edit root>
/<connection name>
/<container name>
/<domain>
/<edit root>
/<connection name>
/<container name>/<language>
/<domain>
/<edit root>
/<connection name>
/<language>
/
Как указано выше, можно менять местами корень и подключение.
Примеры:
- https://odatadb.savetodb.com/edit/mssql-023/
- https://odatadb.savetodb.com/edit/mssql-023/cashbook
- https://odatadb.savetodb.com/edit/mssql-023/usp_cashbook()
Первый URL отображает все объекты из сервисного документа. Остальные URL отображают данные заданных объектов.
Корень и страница по умолчанию — edit
и edit.htm
. Можно настроить другие корни с соответствующими страницами.
Страницы редактирования используют значение window.location.href для расчета URL API.
Для приведенных выше URL страницы редактирования вызывают следующие URL:
- https://odatadb.savetodb.com/v4/mssql-023/
- https://odatadb.savetodb.com/v4/mssql-023/cashbook
- https://odatadb.savetodb.com/v4/mssql-023/usp_cashbook()
Конечные точки домашних страниц
Эти конечные точки перенаправляют на страницы сервисного документа или на страницы, заданные в настройке Home
подключения.
Клиент JavaScript вызывает эти конечные точки по нажатию кнопки Домашняя страница
.
ODataDB создает конечные точки для каждого подключения, заданного в файле appsettings, по следующим шаблонам:
<domain>
/<home root>
/<connection name>
/<domain>
/<home root>
/<connection name>
/<container name>
/<domain>
/<home root>
/<connection name>
/<container name>/<language>
/<domain>
/<home root>
/<connection name>
/<language>
/
Как указано выше, можно менять местами корень и подключение.
Имя корня можно настроить в свойстве HomeRoot
файла appsettings.
Конечные точки страниц аутентификации
Эти конечные точки возвращают страницы для ввода имени пользователя и пароля.
Страницы используют конечные точки операций аутентификации, описанные ниже.
ODataDB создает конечные точки для каждого корня, заданного в секции LoginRoots
файла appsettings, по следующим шаблонам:
<domain>
/<login root>
/<connection name>
/<domain>
/<login root>
/<connection name>
/<container name>
/<domain>
/<login root>
/<connection name>
/<container name>/<language>
/<domain>
/<login root>
/<connection name>
/<language>
/
Как указано выше, можно менять местами корень и подключение.
Эти страницы не требуют начальной аутентификации, чтобы пользователь мог ввести имя и пароль.
Корень и страница по умолчанию — login
и login.htm
. Можно настроить другие корни с соответствующими страницами, например для регистрации новых пользователей.
Конечные точки операций аутентификации
Эти конечные точки выполняют операции аутентификации JWT.
ODataDB создает конечные точки POST для каждого подключения, заданного в файле appsettings, по следующим шаблонам:
<domain>
/<auth root>
/<connection name>
/login
<domain>
/<auth root>
/<connection name>
/logout
<domain>
/<auth root>
/<connection name>
/refresh
<domain>
/<auth root>
/<connection name>
/getToken
Как указано выше, можно менять местами корень и подключение.
Корень по умолчанию — auth
. Имя корня можно изменить в свойстве AuthRoot
файла appsettings.
Конечная точка login
возвращает токены доступа и обновления, куки и время действия токена доступа.
Токены доступа и куки необходимы для доступа к защищенным ресурсам. Токен обновления и куки требуются для обновления токена доступа.
Срок действия токенов можно настроить в свойствах AccessTokenExpirationInMinutes
и RefreshTokenExpirationInMinutes
.
Конечная точка logout
удаляет токены доступа и обновления на стороне сервера.
Конечная точка refresh
возвращает новый токен доступа и его время действия, а также может вернуть новый токен обновления и куки.
Конечная точка getToken
возвращает одноразовый токен доступа, позволяя получать доступ к защищенным ресурсам, которые не поддерживают JavaScript.
ODataDB реализует аутентификацию JWT в соответствии с лучшими практиками.
Детали реализации можно увидеть в инструментах разработчика браузера.
Обратите внимание, что куки видны не во всех запросах, так как они устанавливаются для конечных точек API и аутентификации с параметрами SameSite=Strict; HttpOnly=true
.
Конечные точки управления приложением
Для остановки консольного приложения и отображения или скрытия его окна на платформе Windows можно использовать следующие конечные точки:
<domain>
/<app root>
/stop
<domain>
/<app root>
/show
<domain>
/<app root>
/hide
Например:
- https://localhost:5002/app/stop
- https://localhost:5002/app/show
- https://localhost:5002/app/hide
Эти операции могут быть полезны для интеграции ODataDB в ваше приложение.
Эти операции доступны только для консольного приложения Windows и при включенном свойстве StopEnabled
.
Корень по умолчанию — app
. Имя корня можно изменить в свойстве AppRoot
файла appsettings.
Статические файлы
ODataDB позволяет получать статические файлы из каталога wwwroot
.
Например, можно получать такие файлы, как /css/db.min.css
или /js/db.min.js
, с поддержкой сжатия gzip.
Как упоминалось ранее, ODataDB поддерживает языковые папки специальным образом.
Например, для запроса /en-gb/sample01.htm
будет возвращен файл wwwroot/en-us/sample01.htm
, если файл wwwroot/en-gb/sample01.htm
отсутствует.
ODataDB поддерживает индексные страницы: default.htm
, default.html
, index.htm
, index.html
.
ODataDB автоматически изменяет тег <base href="/" />
в HTML-страницах для приложений IIS.