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

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

Содержание

Введение

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

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

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

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

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

Например, файл appsettings.json может выглядеть так:

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

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

  1. https://dbgate/api/mssql/
  2. https://dbgate/edit/mssql/
  3. https://dbgate/home/mssql/
  4. https://dbgate/login/mssql
  5. https://dbgate/auth/mssql/

В этом примере api, edit, home, login и auth являются корневыми сегментами.

Имена корневых сегментов можно изменить в файле appsettings.

Корневые сегменты и сегменты подключений

По умолчанию, DBGate поддерживает два формата конечных точек:

  • https://dbgate/api/mssql/
  • https://dbgate/mssql/api/

Можно выбрать только один формат, установив настройку ConnectionSegment в файле appsettings.

Сегмент языка

DBGate позволяет указать желаемый язык в URL следующим образом:

  • https://dbgate/edit/mssql/en-us/
  • https://dbgate/edit/mssql/ru-ru/

Клиент JavaScript использует культуру для загрузки языковых ресурсов и форматирования чисел и дат.

Клиент JavaScript выполняет запросы к серверу, передавая указанный язык. Например:

  • https://dbgate/api/mssql/en-us/
  • https://dbgate/api/mssql/ru-ru/

DBGate использует культуру для перевода модели (имена, комментарии и т.д.), если эта возможность поддерживается базой данных.

Также DBGate передает значения языка в параметры хранимых процедур, указанные в настройке LanguageParameters, что позволяет возвращать данные на нужном языке.

См. подробности в Руководстве разработчика.

Языковые папки

В каталоге wwwroot можно создать подкаталоги для языков, например, en-us, ru-ru, zh-hans и т.д.

DBGate ищет файлы в этих папках в зависимости от культуры, указанной в 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.

Сегменты контейнера

По умолчанию, DBGate включает в модель сервиса все объекты базы данных, доступные пользователю.

DBGate создает контейнер default.

Контейнер можно указать в третьем сегменте.

Следующие URL используют одну и ту же модель:

  • https://dbgate/api/mssql/
  • https://dbgate/api/mssql/default/
  • https://dbgate/api/mssql/default/en-us/

Разработчики могут создать специальные представления (например, QueryList) для отображения только определенных объектов, таких как buyer и seller. В этом случае DBGate позволяет использовать такие представления как контейнеры:

  • https://dbgate/api/mssql/buyer/
  • https://dbgate/api/mssql/seller/

В обоих случаях модель включает все объекты, доступные пользователю, но сервисные документы содержат только объекты из представлений QueryList.

См. подробности в Руководстве разработчика.

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

Конечные точки API возвращают сервисные документы, метаданные и данные в соответствии со стандартами OData, а также расширенные настройки.

DBGate создает конечные точки для каждого подключения, указанного в файле 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>/

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

Корень по умолчанию — api. Имя корня можно изменить в свойстве ApiRoot файла appsettings.

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

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

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

Для получения данных добавьте имя объекта.

Например:

DBGate поддерживает следующие расширения (в последнем сегменте): $excel_formats, $excel_format, $table_format, $workbooks, $definition.

$definition возвращает определение объекта (если у пользователя есть разрешение VIEW DEFINITION).

Например, https://dbgate.savetodb.com/api/mssql-023/usp_cashbook/$definition.

Другие расширения требуют настройки в базе данных.

См. онлайн примеры и подробности в Руководстве разработчика.

Конечные точки страниц редактирования

Эти конечные точки возвращают страницы для просмотра и редактирования данных.

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

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

Конечные точки страниц аутентификации

Эти конечные точки возвращают страницы для ввода имени и пароля пользователя.

Страницы используют конечные точки операций аутентификации, описанные ниже.

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

DBGate создает конечные точки 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.

DBGate реализует аутентификацию JWT в соответствии с лучшими практиками.

Детали реализации можно увидеть в инструментах разработчика браузера.

Учтите, что куки видны не во всех запросах, так как они устанавливаются для конечных точек API и аутентификации с параметрами SameSite=Strict; HttpOnly=true.

Конечные точки управления приложением

Для остановки консольного приложения и отображения или скрытия его окна на платформе Windows можно использовать следующие конечные точки:

  • <domain>/<app root>/stop
  • <domain>/<app root>/show
  • <domain>/<app root>/hide

Например:

  • https://localhost:5003/app/stop
  • https://localhost:5003/app/show
  • https://localhost:5003/app/hide

Эти операции могут быть полезны для интеграции DBGate в ваше приложение.

Эти операции доступны только для консольного приложения Windows и при включенном свойстве StopEnabled.

Корень по умолчанию — app. Имя корня можно изменить в свойстве AppRoot файла appsettings.

Статические файлы

DBGate позволяет получать статические файлы из каталога wwwroot.

Например, можно получать такие файлы как /css/db.min.css или /js/db.min.js, с поддержкой сжатия gzip.

Как упоминалось ранее, DBGate поддерживает языковые папки специальным образом.

Например, для запроса /en-gb/sample01.htm возвращается файл wwwroot/en-us/sample01.htm, если файл wwwroot/en-gb/sample01.htm не существует.

DBGate поддерживает индексные страницы: default.htm, default.html, index.htm, index.html.

DBGate автоматически изменяет тег <base href="/" /> в HTML-страницах для приложений IIS.

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