Tworzenie statycznej aplikacji internetowej przy użyciu bezserwerowego interfejsu API

  • Artykuł

Dowiedz się, jak uruchomić lokalnie, a następnie wdrożyć statyczną aplikację internetową przy użyciu bezserwerowego interfejsu API na platformie Azure. W tym samouczku jest używana wersja zapoznawcza najnowszego modelu programowania Node.js usługi Azure Functions. Ponieważ w tym artykule jest używana wersja zapoznawcza usługi Azure Functions, jest ona wdrażana jako oddzielna aplikacja od statycznej aplikacji internetowej.

Instrukcje:

  • Lokalne uruchamianie statycznej aplikacji internetowej (SWA) przy użyciu aplikacji funkcji platformy Azure
  • Lokalne żądania frontonu serwera proxy do lokalnego interfejsu API zaplecza przy użyciu interfejsu wiersza polecenia programu SWA.
  • Zdalnie wdróż i uruchom ten sam kod.

Serwer proxy między frontonem a zapleczem udostępnianym przez interfejs wiersza polecenia statycznej aplikacji internetowej zapewnia:

  • Adres URL w rozwiązaniu React, /api/todo, nie określa serwera ani numeru portu interfejsu API. Żądania korzystające z tego adresu URL są pomyślne lokalnie, ponieważ interfejs wiersza polecenia swa zarządza serwerem proxy.
  • Emulator uwierzytelniania lokalnego podczas uzyskiwania dostępu /.auth/login/<provider>
  • Zarządzanie trasami i autoryzacja

Uwierzytelnianie w tym przykładzie

Uwierzytelnianie w tym przykładzie jest dostępne dla użytkowników frontonu z usługi Azure Static Web Apps:

  • Logowanie/wylogowywanie
  • Zawartość publiczna i prywatna

Kod źródłowy w tym przykładzie

Kod źródłowy w tym przykładzie służy dowiesz się, jak utworzyć i wdrożyć statyczną aplikację internetową przy użyciu bezserwerowego interfejsu API. Kod nie jest przeznaczony do produkcji.

W kodzie znajdziesz kilka miejsc, które nie są zgodne z najlepszymi rozwiązaniami w zakresie zabezpieczeń. Na przykład kod używa console.log polecenia do zapisu w konsoli przeglądarki.

Podczas przechodzenia do środowiska produkcyjnego należy przejrzeć i usunąć dowolny kod, który narusza najlepsze rozwiązania w zakresie zabezpieczeń organizacji.

1. Przygotowanie środowiska projektowego

Utwórz następujące konta:

Zainstaluj następujące elementy na lokalnym komputerze deweloperów:

2. Rozwidlenie przykładowego repozytorium w usłudze GitHub

Aby ukończyć wdrożenie z usługi GitHub, musisz mieć własne rozwidlenie przykładowego repozytorium. Podczas procesu rozwidlenia wystarczy skopiować main gałąź.

Rozwidlenie przykładowego repozytorium: https://github.com/Azure-Samples/azure-typescript-e2e-apps.

3. Sklonuj rozwidlenie przykładowego repozytorium

  1. W terminalu powłoki bash sklonuj rozwidlenie repozytorium na komputer lokalny. Nie klonuj oryginalnego przykładowego repozytorium. Przykładowy adres URL to https://github.com/YOUR-ACCOUNT-NAME/azure-typescript-e2e-apps

    git clone YOUR-FORKED-REPO-URL

  2. Zainstaluj zależności dla lokalnej aplikacji frontonu:

    cd app-react-vite && npm install

  3. Zainstaluj zależności dla lokalnej aplikacji zaplecza:

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

4. Opcjonalnie, skompiluj i uruchom aplikację lokalną

Przykładowe repozytorium zawiera kilka wersji aplikacji frontonu i zaplecza. W poniższych krokach są używane wersje frontonu React 18 (Vite) i funkcji platformy Azure w wersji 4 z wersją node.js zaplecza z trasami interfejsu /status API i /todo .

  1. Z poziomu katalogu głównego przykładowej aplikacji użyj interfejsu wiersza polecenia swa z plikiem ./swa-cli.config.json , aby utworzyć aplikacje frontonu i zaplecza:

    swa build

    Jeśli wystąpią błędy, które mogą wystąpić w zależności od wersji różnych pakietów i środowiska, napraw błędy przed kontynuowaniem. Ważne jest, aby wiedzieć, że projekt pomyślnie kompiluje się lokalnie przed przejściem do wdrożenia w usłudze Azure Static Web Apps.

  2. Z poziomu katalogu głównego przykładowej aplikacji użyj interfejsu wiersza polecenia swa, aby uruchomić aplikacje za pomocą serwera proxy.

    swa start

  3. Po wyświetleniu następujących wierszy w terminalu powłoki bash projekt został pomyślnie uruchomiony.

    [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. Otwórz przeglądarkę internetową pod adresem URL proxied. http://localhost:4280 Powinna zostać wyświetlona następująca strona:

    Screenshot of local React app prior to authentication.

  5. Możesz zalogować się przy użyciu uwierzytelniania dostarczonego przez interfejs wiersza polecenia swa. Proces wyśmiewa uwierzytelnianie w aplikacjach internetowych statycznych platformy Azure opartych na chmurze. Kod frontonu używa punktu końcowego /.auth/me do uzyskania tożsamości użytkownika. Wprowadź dowolną fałszywą nazwę użytkownika i nie zmieniaj pozostałych pól.

    Screenshot of local React app's mock authentication form.

  6. Po uwierzytelnieniu użytkownika fronton wyświetla informacje prywatne , takie jak zmienne środowiskowe interfejsu API.

    Screenshot of local React app with authentication complete.

    Kod źródłowy aplikacji funkcji platformy Azure w wersji 4 dla tego interfejsu API to:

    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. Rozwiń sekcje publiczne i prywatne, aby wyświetlić zawartość z interfejsu API.

5. Tworzenie nowej aplikacji usługi Azure Functions

Poprzednia sekcja uruchamiania statycznej aplikacji internetowej z interfejsem API była opcjonalna. Pozostałe sekcje artykułu są wymagane do wdrożenia aplikacji i interfejsu API w chmurze platformy Azure.

Aby użyć wersji zapoznawczej środowiska uruchomieniowego usługi Azure Functions w wersji 4, należy utworzyć nową aplikację usługi Azure Functions. Statyczna aplikacja internetowa musi również zostać ponownie skompilowana i wdrożona ponownie, aby użyć identyfikatora URI aplikacji usługi Azure Functions w żądaniach pobierania do interfejsu API zamiast używania interfejsu API proxied i zarządzanego.

  1. W przeglądarce internetowej otwórz witrynę Azure Portal, aby utworzyć nową aplikację usługi Azure Functions: Tworzenie nowej aplikacji

  2. Użyj poniższych informacji, aby utworzyć aplikację funkcji:

    Tab:Ustawienie Wartość
    Podstawowe informacje: subskrypcja Wybierz subskrypcję, której chcesz użyć.
    Podstawowe informacje: grupa zasobów Utwórz nową grupę zasobów, taką jak first-static-web-app-with-api. Nazwa nie jest używana w publicznym adresie URL aplikacji. Grupy zasobów ułatwiają grupowanie i zarządzane powiązane zasoby platformy Azure.
    Podstawowe informacje: Szczegóły wystąpienia: Nazwa aplikacji funkcji Wprowadź globalnie unikatową nazwę, taką jak swa-api z 3 losowymi znakami dodanymi na końcu, na przykład swa-api-123.
    Podstawowe informacje: szczegóły wystąpienia: kod lub kontener Wybierz opcję Code.
    Podstawowe informacje: Szczegóły wystąpienia: stos środowiska uruchomieniowego Wybierz opcję Node.js.
    Podstawowe informacje: Szczegóły wystąpienia: stos środowiska uruchomieniowego Wybierz opcję 18LTS.
    Podstawowe informacje: System operacyjny Wybierz opcję Linux.
    Podstawowe informacje: hosting Wybierz opcję Consumption.
    Magazyn: konto magazynu Nie zmieniaj tego. Zostanie utworzone nowe konto usługi Azure Storage, które pomaga w zdarzeń funkcji.
    Sieć Nie zmieniaj niczego.
    Monitorowanie: Szczegółowe informacje aplikacji: włączanie Szczegółowe informacje aplikacji Wybierz opcję Yes. Nie zmieniaj podanej nazwy domyślnej.
    Wdrażanie: Ustawienia funkcji GitHub Actions: ciągłe wdrażanie Wybierz opcję Enable.
    Wdrażanie: konto usługi GitHub Wybierz konto usługi GitHub.
    Wdrożenie: Organizacja Wybierz konto usługi GitHub, które zostało użyte podczas rozwidlenia przykładowego repozytorium.
    Wdrażanie: repozytorium Wybierz nazwę rozwidlenia repozytorium, azure-typescript-e2e-apps.
    Wdrożenie: Gałąź Wybierz opcję main.
    Tagi Nie zmieniaj niczego.
    Przeglądanie i tworzenie Wybierz opcję Create.

    Krok dodaje plik przepływu pracy yaml usługi GitHub do rozwidlenia repozytorium.

  3. Po utworzeniu zasobu wybierz Go to resource przycisk .

  4. Wybierz pozycję Ustawienia —> Konfiguracja, a następnie dodaj ustawienie konfiguracji środowiska uruchomieniowego Azure Function Node.js v4 o nazwie AzureWebJobsFeatureFlags i wartości EnableWorkerIndexing.

  5. Wybierz pozycję Zapisz, aby zapisać ustawienie.

  6. W terminalu powłoki bash użyj narzędzia git , aby ściągnąć nowy plik przepływu pracy yaml z repozytorium rozwidlenia usługi GitHub na komputer lokalny.

    git pull origin main

  7. W programie Visual Studio Code otwórz nowy plik przepływu pracy yaml znajdujący się w lokalizacji ./.github/workflows/.

  8. Domyślny plik przepływu pracy podany dla Użytkownika zakłada, że kod źródłowy funkcji znajduje się w katalogu głównym repozytorium i jest jedyną aplikacją w repozytorium, ale nie jest to przypadek w tym przykładzie. Aby rozwiązać ten problem, zmodyfikuj plik. Wiersze do edycji zostały wyróżnione w następującym bloku yaml i wyjaśniono poniżej:

    # 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
    Zmiana właściwości Przeznaczenie
    name Skróć nazwę, aby łatwo ją znaleźć na liście akcji GitHub rozwidlenia.
    paths Dodaj sekcję ścieżki, aby ograniczyć wdrożenie do uruchomienia tylko wtedy, gdy kod interfejsu API usługi Azure Functions ulegnie zmianie. Podczas edytowania pliku przepływu pracy można wyzwolić wdrożenie ręcznie.
    AZURE_FUNCTIONAPP_PACKAGE_PATH W przypadku używania podkatalogu dla kodu źródłowego musi to być ta ścieżka i nazwa podkatalogu.
    VERBOSE To ustawienie jest przydatne do debugowania procesu kompilacji i wdrażania.
    krok o nazwie Upload artifact for deployment job Ten krok powoduje utworzenie artefaktu możliwego do pobrania. Jest to przydatne podczas debugowania dokładnie plików wdrożonych w funkcji platformy Azure.

    Parametr Upload artifact for deployment job jest opcjonalny. Służy do zrozumienia i debugowania plików wdrożonych w usłudze Azure Functions lub używania tych plików w osobnym środowisku.

  9. Zapisz plik, a następnie dodaj, zatwierdź i wypchnij go z powrotem do usługi GitHub przy użyciu narzędzia git:

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

  10. W przeglądarce uruchom ponownie przepływ pracy w usłudze GitHub w obszarze akcji rozwidlenia.

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

  11. Przed kontynuowaniem poczekaj na pomyślne zakończenie akcji.

  12. W przeglądarce internetowej użyj zewnętrznego punktu końcowego interfejsu API aplikacji funkcji, aby sprawdzić, czy aplikacja została pomyślnie wdrożona.

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

    Wynik JSON zwrócony dla danych w pamięci to:

    {
    "1": "Say hello"
}

  13. Zanotuj adres URL funkcji. Będzie to potrzebne w następnej sekcji.

  14. Wiesz, że aplikacja funkcji platformy Azure działa w chmurze. Teraz musisz utworzyć statyczną aplikację internetową w chmurze, aby korzystać z interfejsu API.

6. Tworzenie nowej statycznej aplikacji internetowej platformy Azure

Ten proces tworzenia wdraża to samo rozwidlenie przykładowego repozytorium GitHub na platformie Azure. Wdrożenie należy skonfigurować tak, aby używało tylko aplikacji frontonu.

  1. Otwórz witrynę Azure Portal i zaloguj się przy użyciu konta platformy Azure: Azure Portal.

  2. Aby wykonać kroki tworzenia, wykonaj następujące informacje:

    Monit Ustawienie
    Subskrypcja Wybierz subskrypcję, której chcesz użyć.
    Grupa zasobów Wybierz Create new i wprowadź nowy dla grupy zasobów, na przykład first-static-web-app. Nazwa nie jest używana w publicznym adresie URL aplikacji. Grupy zasobów ułatwiają grupowanie zasobów używanych dla pojedynczego projektu.
    Typ planu hostingu Wybierz pozycję Free
    Azure Functions i szczegóły przejściowe Nie zmieniaj wartości domyślnej. Nie wdrażasz interfejsu API funkcji w statycznej aplikacji internetowej.
    Szczegóły wdrożenia — źródło Wybierz pozycję GitHub
    Szczegóły wdrożenia — GitHub W razie potrzeby zaloguj się do usługi GitHub.
    Szczegóły wdrożenia — organizacja Wybierz konto usługi GitHub.
    Szczegóły wdrożenia — repozytorium Wybierz rozwidlenie repozytorium o nazwie azure-typescript-e2e-apps.
    Szczegóły wdrożenia — gałąź main Wybierz gałąź.
    Szczegóły kompilacji — prezentacje kompilacji Wybierz opcję Custom.
    Szczegóły kompilacji — lokalizacja aplikacji Wprowadź /app-react-vite.
    Szczegóły kompilacji — lokalizacja interfejsu API Pozostaw pole puste
    Szczegóły kompilacji — lokalizacja wyjściowa Wprowadź lokalizację katalogu wyjściowego frontonu, dist.

  3. Wybierz pozycję Przeglądanie i tworzenie, a następnie wybierz pozycję Utwórz.

  4. Po utworzeniu zasobu wybierz Go to resource przycisk .

  5. Na stronie Przegląd zanotuj adres URL statycznej aplikacji internetowej. Potrzebujesz tego w następnej sekcji podczas ustawiania ustawienia MECHANIZMU CORS funkcji platformy Azure.

  6. Proces tworzenia tworzy plik przepływu pracy yaml usługi GitHub w rozwidlonym repozytorium GitHub. Przeciągnij zmianę za pomocą następującego polecenia:

    git pull origin main

  7. Akcja usługi GitHub znaleziona w ./.github/workflows/azure-static-web-apps-*.yml witrynie jest odpowiedzialna za kompilowanie i wdrażanie aplikacji frontonu. Edytuj plik, aby dodać zmienną środowiskową dla adresu URL interfejsu API zaplecza opartego na chmurze. Wiersze do edycji zostały wyróżnione w poniższym bloku yaml i wyjaśniono poniżej bloku 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"
    Zmiana właściwości Przeznaczenie
    paths Dodaj sekcję ścieżki, aby ograniczyć wdrożenie do uruchomienia tylko wtedy, gdy kod interfejsu API usługi Azure Functions ulegnie zmianie. Podczas edytowania pliku przepływu pracy można wyzwolić wdrożenie ręcznie.
    workflow_dispatch Dodaj workflow_dispatchtylko podczas uczenia się procesu wdrażania i debugowania wszelkich problemów w kompilacji Vite. Usuń ten wiersz po kontynuowaniu tego kodu źródłowego poza tym artykułem.
    if ... || github.event_name == 'workflow_dispatch' Uwzględnij workflow_dispatch zdarzenie jako dozwolone do wygenerowania kompilacji tylko podczas uczenia się procesu wdrażania i debugowania wszelkich problemów w kompilacji Vite.
    env Dodaj zmienne środowiskowe niezbędne do uwzględnienia adresu URL interfejsu API funkcji platformy Azure w kompilacji statycznej za pomocą narzędzia Vite. VITE_BACKEND_URL to adres URL aplikacji funkcji platformy Azure. VITE_CLOUD_ENV jest parametrem wskazującym, kiedy należy użyć adresu URL VITE_BACKEND_URL. Nie używaj NODE_ENV dla tego przykładu, ponieważ ma on niezamierzony wpływ na stronę.

  8. Zapisz plik, a następnie dodaj, zatwierdź i wypchnij go z powrotem do usługi GitHub przy użyciu narzędzia git:

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

  9. W przeglądarce uruchom ponownie przepływ pracy w usłudze GitHub w obszarze akcji rozwidlenia dla statycznej aplikacji internetowej.

  10. Aplikacja frontonu jest wdrażana na platformie Azure. Teraz musisz skonfigurować aplikację funkcji platformy Azure, aby zezwalać na żądania CORS ze statycznej aplikacji internetowej.

7. Konfigurowanie mechanizmu CORS dla aplikacji funkcji platformy Azure

W przypadku korzystania z oddzielnej aplikacji funkcji platformy Azure zamiast aplikacji funkcji zarządzanej należy skonfigurować mechanizm CORS tak, aby zezwalał na żądania ze statycznej aplikacji internetowej.

  1. W witrynie Azure Portal otwórz aplikację funkcji platformy Azure.
  2. W sekcji INTERFEJS API —> CORS dodaj adres URL statycznej aplikacji internetowej do listy dozwolonych źródeł.

8. Testowanie statycznej aplikacji internetowej

  1. W przeglądarce otwórz statyczną aplikację internetową.
  2. Wchodzenie w interakcję z aplikacją w celu logowania się, wyświetlania informacji publicznych i prywatnych i wylogowywanie się ponownie.

9. Czyszczenie wszystkich zasobów używanych w tej serii artykułów

Wyczyść wszystkie zasoby utworzone w tej serii artykułów.

  1. W witrynie Azure Portal usuń grupę zasobów, która usuwa statyczną aplikację internetową i aplikację funkcji.
  2. W portalu GitHub usuń rozwidlenie repozytorium.

Rozwiązywanie problemów

Ten przykład zawiera listę znanych problemów i rozwiązań. Jeśli problem nie znajduje się na liście, otwórz problem.

Statyczne adresy URL aplikacji internetowej i aplikacji funkcji

Adres URL statycznej aplikacji internetowej i adres URL aplikacji funkcji zawsze można znaleźć w witrynie Azure Portal na stronie Przegląd każdego zasobu. Te adresy URL są domyślnie publiczne.

Następne kroki