Share via

Создание статического веб-приложения с помощью бессерверного API

  • Статья

Узнайте, как локально запустить статическое веб-приложение с бессерверным API в Azure. В этом руководстве используется предварительная версия последней модели программирования Функции Azure Node.js. Так как в этой статье используется предварительная версия Функции Azure, она развертывается как отдельное приложение от статического веб-приложения.

Вы узнаете, как выполнять следующие задачи:

  • Локальное выполнение статического веб-приложения (SWA) с приложением-функцией Azure
  • Локально прокси-серверные запросы к локальному внутреннему API с помощью интерфейса командной строки SWA.
  • Развертывание и удаленное выполнение одного и того же кода.

Прокси-сервер между интерфейсом и серверной частью, предоставляемым интерфейсом командной строки статических веб-приложений, предоставляет:

  • URL-адрес в React /api/todoне указывает номер сервера или порта для API. Запросы, использующие этот URL-адрес, выполняются локально, потому что интерфейс командной строки SWA управляет прокси-сервером за вас.
  • Эмулятор локальной аутентификации при доступе к /.auth/login/<provider>
  • Управление маршрутом и авторизация

Проверка подлинности в этом примере

Проверка подлинности в этом примере предоставляется для внешних пользователей из службы Статические веб-приложения Azure:

  • вход и выход;
  • Общедоступное и частное содержимое

Исходный код в этом примере

Исходный код в этом примере предназначен для того, чтобы узнать, как создавать и развертывать статическое веб-приложение с бессерверным API. Код не предназначен для рабочей среды.

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

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

1. Подготовка среды разработки

Создайте следующие учетные записи.

Установите следующее на локальном компьютере разработки:

2. Вилку примера репозитория на GitHub

Чтобы завершить развертывание из GitHub, необходимо иметь собственный вилку примера репозитория. Во время процесса вилки необходимо скопировать только ветвь main .

Вилку примера репозитория: https://github.com/Azure-Samples/azure-typescript-e2e-apps

3. Клонирование вилированного примера репозитория

  1. В терминале Bash клонируйте вилированный репозиторий на локальный компьютер. Не клонируйте исходный репозиторий примеров. Пример URL-адреса https://github.com/YOUR-ACCOUNT-NAME/azure-typescript-e2e-apps

    git clone YOUR-FORKED-REPO-URL

  2. Установите зависимости для локального интерфейсного приложения:

    cd app-react-vite && npm install

  3. Установите зависимости для локального серверного приложения:

    cd ../api-inmemory && npm install && cd ..

4. Необязательно, сборка и запуск локального приложения

В примере репозитория есть несколько версий интерфейсных и внутренних приложений. В следующих шагах используется версия интерфейса React 18 (Vite) и функция Azure версии 4 с версией Node.js серверной части с /status маршрутами API./todo

  1. В корневом каталоге примера приложения используйте интерфейс командной строки SWA с ./swa-cli.config.json файлом для создания интерфейсных и внутренних приложений:

    swa build

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

  2. В корневом каталоге примера приложения используйте интерфейс командной строки SWA для запуска приложений с прокси-сервером.

    swa start

  3. Когда в терминале Bash отображаются следующие строки, проект успешно запущен.

    [swa] Serving static content:
[swa]   /workspaces/azure-typescript-e2e-apps/app-react-vite/dist
[swa] 
[swa] Serving API:
[swa]   /workspaces/azure-typescript-e2e-apps/api-inmemory
[swa] 
[swa] Azure Static Web Apps emulator started at http://0.0.0.0:4280. Press CTRL+C to exit.

  4. Откройте веб-браузер в url-адресе прокси-адреса http://localhost:4280. Должна появиться следующая страница:

    Screenshot of local React app prior to authentication.

  5. Вы можете войти с помощью проверки подлинности, предоставленной интерфейсом командной строки SWA. Процесс макетирует проверку подлинности в облачных статических веб-приложениях Azure. Интерфейсный код использует /.auth/me конечную точку для получения удостоверения пользователя. Введите любое поддельные имя пользователя и не изменяйте остальные поля.

    Screenshot of local React app's mock authentication form.

  6. После проверки подлинности пользователя интерфейс отображает частные сведения, такие как переменные среды API.

    Screenshot of local React app with authentication complete.

    Исходный код приложения функции Azure версии 4 для этого API:

    import { app, HttpRequest, HttpResponseInit, InvocationContext } from "@azure/functions";

import { name, version } from '../../package.json';
function isObject(v) {
    return '[object Object]' === Object.prototype.toString.call(v);
};
function sortJson(o){
    if (Array.isArray(o)) {
        return o.sort().map(sortJson);
    } else if (isObject(o)) {
        return Object
            .keys(o)
        .sort()
            .reduce(function(a, k) {
                a[k] = sortJson(o[k]);

                return a;
            }, {});
    }
    return o;
}

export async function status(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const sortedEnv = sortJson(process.env);

    return { jsonBody: {
        name,
        version,
        env: sortedEnv,
        requestHeaders: request.headers 
    }};
};

app.http('status', {
    route: "status",
    methods: ['GET'],
    authLevel: 'anonymous',
    handler: status
});

  7. Разверните общедоступные и частные разделы, чтобы просмотреть содержимое из API.

5. Создание нового приложения Функции Azure

Предыдущий раздел запуска статического веб-приложения с API был необязательным. Остальные разделы статьи необходимы для развертывания приложения и API в облаке Azure.

Чтобы использовать предварительную версию среды выполнения Функции Azure версии 4, необходимо создать новое приложение Функции Azure. Статическое веб-приложение также необходимо перестроить и повторно развернуть для использования URI приложения Функции Azure в запросах на получение api вместо использования прокси-интерфейса и управляемого API.

  1. В веб-браузере откройте портал Azure для создания нового приложения Функции Azure: создание нового приложения

  2. Чтобы создать приложение-функцию, используйте следующие сведения:

    Tab:Setting Значение
    Основы: подписка Выберите подписку, которую нужно использовать.
    Основы: группа ресурсов Создайте новую группу ресурсов, например first-static-web-app-with-api. Имя не используется в общедоступном URL-адресе приложения. Группы ресурсов помогают группировать и управлять связанными ресурсами Azure.
    Основы: сведения об экземпляре: имя приложения-функции Введите глобально уникальное имя, например swa-api с 3 случайными символами, добавленными в конце, например swa-api-123.
    Основы: сведения об экземпляре: код или контейнер Выберите Code.
    Основы: сведения об экземпляре: стек среды выполнения Выберите Node.js.
    Основы: сведения об экземпляре: стек среды выполнения Выберите 18LTS.
    Основы: операционная система Выберите Linux.
    Основы: размещение Выберите Consumption.
    служба хранилища: учетная запись служба хранилища Не меняйте это. Создается новая учетная запись служба хранилища Azure для поддержки событий функций.
    Сеть Не изменяйте ничего.
    Мониторинг: Аналитика приложения: включение Аналитика приложений Выберите Yes. Не изменяйте предоставленное по умолчанию имя.
    Развертывание: GitHub Actions Параметры: непрерывное развертывание Выберите Enable.
    Развертывание: учетная запись GitHub Выберите учетную запись GitHub.
    Развертывание: организация Выберите учетную запись GitHub, которая использовалась при создании примера репозитория.
    Развертывание: репозиторий Выберите имя вилированного репозитория, azure-typescript-e2e-apps.
    Развертывание: Ветвь Выберите main.
    Теги Не изменяйте ничего.
    Проверить и создать Выберите Create.

    Этот шаг добавляет файл рабочего процесса yaml GitHub в вилку репозитория.

  3. При создании ресурса нажмите кнопку Go to resource .

  4. Выберите Параметры —> Конфигурация и добавьте параметр конфигурации для среды выполнения Функции Azure Node.js версии 4 с именем AzureWebJobsFeatureFlags и значениемEnableWorkerIndexing.

  5. Нажмите кнопку Сохранить, чтобы сохранить параметры.

  6. В терминале bash используйте git , чтобы извлечь новый файл рабочего процесса yaml из репозитория GitHub вилку на локальный компьютер.

    git pull origin main

  7. В Visual Studio Code откройте новый файл рабочего процесса yaml, расположенный по адресу ./.github/workflows/.

  8. Файл рабочего процесса по умолчанию предполагает, что исходный код функции находится в корне репозитория и является единственным приложением в репозитории, но это не так. Чтобы исправить это, измените файл. Строки для редактирования выделены в следующем блоке yaml и описаны ниже.

    # Docs for the Azure Web Apps Deploy action: https://github.com/azure/functions-action
# More GitHub Actions for Azure: https://github.com/Azure/actions

# Deploy Azure Functions Node.js v4 runtime
# with api-inmemory subdir

name: Azure Function App - api-inmemory

on:
  push:
    branches:
      - main
    paths:
      - 'api-inmemory/**'
  workflow_dispatch:

env:
  AZURE_FUNCTIONAPP_PACKAGE_PATH: 'api-inmemory' # set this to the path to your web app project, defaults to the repository root
  NODE_VERSION: '18.x' # Azure Functions v4 runtime requires 18
  VERBOSE: true # For debugging

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 'Checkout GitHub Action'
        uses: actions/checkout@v2

      - name: Setup Node ${{ env.NODE_VERSION }} Environment
        uses: actions/setup-node@v1
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: 'Resolve Project Dependencies Using Npm'
        shell: bash
        run: |
          pushd './${{ env.AZURE_FUNCTIONAPP_PACKAGE_PATH }}'
          npm install
          npm run build --if-present
          npm run test --if-present
          popd
      - name: 'Upload artifact for deployment job' # For debugging
        uses: actions/upload-artifact@v3
        with:
          name: azure-function-v4-app
          path: |
            ${{env.AZURE_FUNCTIONAPP_PACKAGE_PATH}}
            !${{env.AZURE_FUNCTIONAPP_PACKAGE_PATH}}/node_modules
            !${{env.AZURE_FUNCTIONAPP_PACKAGE_PATH}}/dist          
      - name: 'Run Azure Functions Action'
        uses: Azure/functions-action@v1
        id: fa
        with:
          app-name: 'swa-api' # change this to your Azure Function app name
          slot-name: 'Production'
          package: ${{env.AZURE_FUNCTIONAPP_PACKAGE_PATH}}
          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_123 }}
          scm-do-build-during-deployment: false
          enable-oryx-build: false
    Изменение свойства Характер использования
    name Сократите имя, чтобы его можно было легко найти в списке действий GitHub вашего вилки.
    paths Добавьте раздел путей, чтобы ограничить развертывание только при изменении кода API Функции Azure. При редактировании файла рабочего процесса можно активировать развертывание вручную.
    AZURE_FUNCTIONAPP_PACKAGE_PATH При использовании подкаталога для исходного кода это должен быть путь и имя подкаталога.
    VERBOSE Этот параметр полезен для отладки процесса сборки и развертывания.
    шаг с именем Upload artifact for deployment job На этом шаге создается скачиваемый артефакт. Это полезно при отладке именно файлов, развернутых в функции Azure.

    Необязательный Upload artifact for deployment job . Он используется для понимания и отладки файлов, развернутых в Функции Azure или для использования этих файлов в отдельной среде.

  9. Сохраните файл, зафиксируйте и отправьте его обратно в GitHub с помощью git:

    git add .
git commit -m "fix the workflow for a subdir"
git push origin main

  10. В браузере повторно запустите рабочий процесс на сайте GitHub в области действий вилки.

    Screenshot of GitHub forked repository, showing how to rerun a GitHub action.

  11. Дождитесь успешного завершения действия, прежде чем продолжить.

  12. В веб-браузере используйте внешнюю конечную точку API приложения-функции, чтобы убедиться, что приложение развернуто успешно.

    https://YOUR-FUNCTION-APP-NAME.azurewebsites.net/api/todo

    Результат JSON, возвращаемый для данных в памяти:

    {
    "1": "Say hello"
}

  13. Запишите URL-адрес функции. Это необходимо в следующем разделе.

  14. Вы знаете, что приложение-функция Azure работает в облаке. Теперь необходимо создать статическое веб-приложение в облаке для использования API.

6. Создание статического веб-приложения Azure

Этот процесс создания развертывает тот же пример репозитория GitHub в Azure. Вы настраиваете развертывание, чтобы использовать только интерфейсное приложение.

  1. Откройте портал Azure и войдите с помощью учетной записи Azure: портал Azure.

  2. Чтобы выполнить действия по созданию, используйте следующие сведения:

    Prompt Параметр
    Отток подписок Выберите подписку, которую нужно использовать.
    Группа ресурсов Выберите Create new и введите новую группу ресурсов, например first-static-web-app. Имя не используется в общедоступном URL-адресе приложения. Группы ресурсов помогают группировать ресурсы, используемые для одного проекта.
    Тип плана размещения Выберите Free
    Функции Azure и сведения о промежуточном хранении Не изменяйте значение по умолчанию. Вы не развертываете API-интерфейс функции в статическом веб-приложении.
    Сведения о развертывании — источник Выберите GitHub
    Сведения о развертывании — GitHub При необходимости войдите в GitHub.
    Сведения о развертывании — организация Выберите учетную запись GitHub.
    Сведения о развертывании — репозиторий Выберите вилку репозитория с именем azure-typescript-e2e-apps.
    Сведения о развертывании — Branch main Выберите ветвь.
    Сведения о сборке — подарки сборки Выберите Custom.
    Сведения о сборке — расположение приложения Введите /app-react-vite.
    Сведения о сборке — расположение API Оставьте пустым
    Сведения о сборке — расположение вывода Введите расположение выходного каталога distвнешнего интерфейса.

  3. Выберите Проверить и создать, а затем выберите Создать.

  4. При создании ресурса нажмите кнопку Go to resource .

  5. На странице обзора запишите URL-адрес статического веб-приложения. Вам потребуется, чтобы в следующем разделе при настройке параметра CORS функции Azure.

  6. Процесс создания создает файл рабочего процесса yaml GitHub в вилку репозитория GitHub. Вытащить это изменение с помощью следующей команды:

    git pull origin main

  7. Действие GitHub, найденное на ./.github/workflows/azure-static-web-apps-*.yml сайте, отвечает за создание и развертывание интерфейсного приложения. Измените файл, чтобы добавить переменную среды для URL-адреса API на основе облака. Строки, которые нужно изменить, выделены в следующем блоке yaml и описаны ниже блока yaml.

    name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
    paths:
      - 'app-react-vite/**'
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - 'app-react-vite/**'      
  workflow_dispatch:

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ORANGE_DUNE_123 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/app-react-vite" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "dist" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######
        env: 
          VITE_BACKEND_URI: https://swa-api-123.azurewebsites.net
          VITE_CLOUD_ENV: production

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ORANGE_DUNE_123 }}
          action: "close"
    Изменение свойства Характер использования
    paths Добавьте раздел путей, чтобы ограничить развертывание только при изменении кода API Функции Azure. При редактировании файла рабочего процесса можно активировать развертывание вручную.
    workflow_dispatch Добавьте workflow_dispatchтолько при обучении процесса развертывания и отладке любых проблем в сборке Vite. Удалите эту строку, если продолжить этот исходный код за пределами этой статьи.
    if ... || github.event_name == 'workflow_dispatch' workflow_dispatch Включите событие, как разрешено создавать сборку только при обучении процесса развертывания и отладке любых проблем в сборке Vite.
    env Добавьте переменные среды, необходимые для включения URL-адреса API-функции Azure в статическую сборку с Vite. VITE_BACKEND_URL — это URL-адрес приложения-функции Azure. VITE_CLOUD_ENV — это параметр, указывающий, когда следует использовать URL-адрес VITE_BACKEND_URL. Не используйте NODE_ENV для этого примера, так как это непреднамеренное влияние на сторону.

  8. Сохраните файл, зафиксируйте и отправьте его обратно в GitHub с помощью git:

    git add .
git commit -m "fix the workflow for a subdir"
git push origin main

  9. В браузере повторно запустите рабочий процесс на сайте GitHub в области действий вилки для статического веб-приложения.

  10. Интерфейсное приложение развертывается в Azure. Теперь необходимо настроить приложение-функцию Azure, чтобы разрешить запросы CORS из статического веб-приложения.

7. Настройка CORS для приложения-функции Azure

При использовании отдельного приложения-функции Azure вместо управляемого приложения-функции необходимо настроить CORS, чтобы разрешить запросы из статического веб-приложения.

  1. В портал Azure откройте приложение-функцию Azure.
  2. В разделе API —> CORS добавьте URL-адрес статического веб-приложения в список разрешенных источников.

8. Тестирование статического веб-приложения

  1. В браузере откройте статическое веб-приложение.
  2. Взаимодействуйте с приложением для входа, просмотра общедоступной и частной информации и повторного выхода.

9. Очистка всех ресурсов, используемых в этой серии статей

Очистите все ресурсы, созданные в этой серии статей.

  1. В портал Azure удалите группу ресурсов, которая удаляет статическое веб-приложение и приложение-функцию.
  2. На портале GitHub удалите вилку репозитория.

Устранение неполадок

В этом примере содержится список известных проблем и резолюций. Если проблема не указана, откройте проблему.

Общедоступные URL-адреса статических веб-приложений и приложений-функций

Вы всегда можете найти URL-адрес статического веб-приложения и URL-адрес приложения-функции в портал Azure на странице обзора каждого ресурса. По умолчанию эти URL-адреса являются общедоступными.

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