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

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

Содержание

Введение

Конечные точки ODataDB делятся на три основные категории:

  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.

Следующие 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.

Примеры конечных точек:

Эти конечные точки возвращают сервисные документы.

Чтобы получить метаданные сервиса, добавьте сегмент $metadata.

Чтобы получить данные, добавьте имя объекта. Для функций добавьте круглые скобки.

Например:

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>/

Как указано выше, можно менять местами корень и подключение.

Примеры:

Первый URL отображает все объекты из сервисного документа. Остальные URL отображают данные заданных объектов.

Корень и страница по умолчанию — edit и edit.htm. Можно настроить другие корни с соответствующими страницами.

Страницы редактирования используют значение window.location.href для расчета URL API.

Для приведенных выше URL страницы редактирования вызывают следующие URL:

Конечные точки домашних страниц

Эти конечные точки перенаправляют на страницы сервисного документа или на страницы, заданные в настройке 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.

Этот веб-сайт использует куки. Продолжая использовать веб-сайт, Вы принимаете условия Политики защиты персональных данных.