Настройка локальной разработки для Статических веб-приложений Azure

Статья
02/05/2024

При публикации в облаке сайт Статических веб-приложений Azure объединяет множество служб, которые работают вместе, как если бы они были одним и тем же приложением. К этим службам относятся:

Статическое веб-приложение
API Функций Azure
Службы проверки подлинности и авторизации
Службы маршрутизации и настройки

Эти службы должны взаимодействовать друг с другом, а Статические веб-приложения Azure обеспечивают эту интеграцию в облаке.

Однако при локальном запуске приложения эти службы не связываются автоматически.

Для обеспечения возможностей, аналогичных возможностям Azure, интерфейс командной строки Статических веб-приложений Azure предоставляет следующие службы.

Локальный статический сервер сайта
Прокси-сервер к серверу разработки интерфейсной платформы
Прокси-сервер для конечных точек API — доступен через Azure Functions Core Tools
Имитация сервера проверки подлинности и авторизации
Принудительное применение локальных маршрутов и параметров конфигурации

Примечание.

Часто для сайтов, созданных с помощью интерфейсной платформы, требуется параметр конфигурации прокси-сервера для правильной обработки запросов в маршруте api. При использовании интерфейса командной строки для статических веб-приложений Azure значение расположения прокси-сервера равно /api, а без CLI — значение http://localhost:7071/api.

Как это работает

На следующей диаграмме показано, как запросы обрабатываются локально.

Diagram showing the Azure Static Web App CLI request and response flow.

Важно!

Перейдите к http://localhost:4280 приложению, обслуживаемого интерфейсом командной строки.

Запросы, отправленные на порт 4280, перенаправляются на соответствующий сервер в зависимости от типа запроса.
Запросы статического содержимого, такие как HTML или CSS, обрабатываются внутренним сервером статического содержимого CLI или сервером интерфейсной платформы для отладки.
Запросы проверки подлинности и авторизации обрабатываются эмулятором, который предоставляет приложению фиктивный профиль удостоверения.
Среда выполнения^{Core Tools функций 1} обрабатывает запросы к API сайта.
Ответы от всех служб возвращаются в браузер, как если бы все они были единственным приложением.

После запуска пользовательского интерфейса и приложений API Функции Azure самостоятельно запустите интерфейс командной строки Статические веб-приложения и укажите его на запущенные приложения с помощью следующей команды:

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

При необходимости при использовании swa init команды Статические веб-приложения CLI просматривает код приложения и создает файл конфигурации swa-cli.config.json для ИНТЕРФЕЙСА командной строки. При использовании файла swa-cli.config.json можно запустить swa start приложение локально.

¹ Функции Azure Core Tools автоматически устанавливаются интерфейсом командной строки, если они еще не находятся в вашей системе.

В следующей статье описаны шаги по запуску приложения на основе узлов, но процесс совпадает с любым языком или средой.

Необходимые компоненты

Существующий сайт Статических веб-приложений Azure. Если у вас его нет, начните работу с примера приложения vanilla-api.
Node.js с npm: запустите версию Node.js LTS, которая включает доступ к npm.
Visual Studio Code: используется для отладки приложения API, но не требуется для интерфейса командной строки.

Начать

Откройте терминал в корневой папке существующего сайта Статических веб-приложений Azure.

Установите CLI.
```
npm install -D @azure/static-web-apps-cli
```
Совет

Если вы хотите установить SWA CLI глобально, используйте -g вместо -Dэтого. Однако настоятельно рекомендуется установить SWA в качестве зависимости разработки.
Выполните сборку приложения, если это необходимо.

Выполните команду npm run build или эквивалентную команду для своего проекта.
Инициализация репозитория для интерфейса командной строки.
```
swa init
```
Ответьте на вопросы, задаваемые интерфейсом командной строки, чтобы проверить правильность параметров конфигурации.
Запустите CLI.
```
swa start
```
Перейдите к http://localhost:4280 просмотру приложения в браузере.

Другие способы запуска CLI

Description	Command	Комментарии
Обслуживание определенной папки	`swa start ./<OUTPUT_FOLDER_NAME>`	Замените `<OUTPUT_FOLDER_NAME>` именем выходной папки.
Использование запущенного сервера разработки платформы	`swa start http://localhost:3000`	Эта команда работает при наличии экземпляра приложения, работающего под портом `3000`. Обновите номер порта, если конфигурация отличается.
Запуск приложения Функций в папке	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	Замените `<OUTPUT_FOLDER_NAME>` именем выходной папки. Эта команда ожидает, что API приложения будет содержать файлы в папке `api` . Измените это значение, если конфигурация отличается.
Использование запущенного приложения Функций	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	Замените `<OUTPUT_FOLDER_NAME>` именем выходной папки. Эта команда ожидает, что приложение Функции Azure будет доступно через порт`7071`. Обновите номер порта, если конфигурация отличается.

Эмуляция авторизации и проверки подлинности

Интерфейс командной строки Статических веб-приложений эмулирует поток безопасности, реализованный в Azure. При входе пользователя в систему можно задать фиктивный профиль удостоверения, возвращаемый приложению.

Например, при попытке перейти /.auth/login/githubна страницу возвращается страница, которая позволяет определить профиль удостоверения.

Примечание.

Эмулятор работает с любыми поставщиками безопасности, а не только с GitHub.

Local authentication and authorization emulator

Эмулятор предоставляет страницу, позволяющую указать значения следующих параметров для субъекта-клиента.

значение	Описание
Username	Имя учетной записи, связанной с поставщиком безопасности. Это значение отображается как свойство `userDetails` в субъекте клиента и создается автоматически, если значение не было указано.
Код пользователя	Значение, формируемое интерфейсом командной строки автоматически.
Роли	Список имен ролей, в котором каждое имя находится на отдельной строке.
Утверждения	Список утверждений пользователей, где каждое имя находится в новой строке.

После входа в систему

Можно воспользоваться конечной точкой /.auth/me или конечной точкой функции, чтобы получить субъект клиента для пользователя.
Переход к /.auth/logout очистке субъекта-клиента и выход из макетного пользователя.

Отладка

В статическом веб-приложении есть два контекста отладки. Первый предназначен для сайта статического содержимого, а второй — для функций API. Локальная отладка возможна благодаря тому, что интерфейс командной строки Статических веб-приложений может использовать серверы разработки для одного или обоих этих контекстов.

Ниже показан типичный сценарий, использующий серверы разработки для обоих контекстов отладки.

Запустите сервер разработки для статического сайта. Эта команда относится к используемой интерфейсной платформе, но часто доступна в форме таких команд, как npm run build, npm start или npm run dev.
Откройте папку приложения API в Visual Studio Code и запустите сеанс отладки.
Запустите интерфейс командной строки Статические веб-приложения с помощью следующей команды.
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
Замените <DEV_SERVER_PORT_NUMBER> номер порта сервера разработки.

На следующих снимках экрана показаны терминалы для типичного сценария отладки:

Для запуска сайта статического содержимого используется команда npm run dev.

Static site development server

На рисунке ниже показан сеанс отладки приложения API Функций Azure в Visual Studio Code.

Visual Studio Code API debugging

Интерфейс командной строки для Статических веб-приложений запускается с использованием обоих серверов разработки.

Azure Static Web Apps CLI terminal

Теперь запросы, которые проходят через порт 4280, направляются на сервер статического содержимого или в сеанс отладки API.

Дополнительные сведения о различных сценариях отладки с инструкциями по настройке портов и адресов серверов см. в репозитории интерфейса командной строки для Cтатических веб-приложений Azure.

Пример конфигурации отладки

Visual Studio Code использует файл для включения сеансов отладки в редакторе. Если Visual Studio Code не создает для вас файл launch.json, можно поместить следующую конфигурацию в VScode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

Следующие шаги

Настройка приложения

Поделиться через