Конечные точки ODataDB

Содержание

• Введение
• Конечные точки API
• Конечные точки страниц редактирования
• Конечные точки домашних страниц
• Конечные точки страниц аутентификации
• Конечные точки операций аутентификации
• Конечные точки управления приложением
• Статические файлы

Введение

Конечные точки можно разделить на три большие категории:

1. Статические файлы
2. Конечные точки управления приложением
3. Конечные точки на основе подключений

Конечные точки подключений включают следующие типы:

1. Конечные точки API
2. Конечные точки страниц редактирования
3. Конечные точки домашних страниц
4. Конечные точки страниц аутентификации
5. Конечные точки операций аутентификации

ODataDB создает наборы конечных точек для каждого подключения, определенного в файле appsettings.

Например, файл appsettings.json имеет следующее содержимое:

{
  "ConnectionStrings": {
    "mssql": {
      "ProviderName": "System.Data.SqlClient",
      "ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=master;User ID=user;Pwd=pass"
    }
  }
}

ODataDB создаст следующие конечные точки:

1. https://odatadb/v4/mssql/
2. https://odatadb/edit/mssql/
3. https://odatadb/home/mssql/
4. https://odatadb/login/mssql
5. 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 используют одну и ту же модель:

• 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.