Configuratie bouwen voor Azure Static Web Apps

Artikel
11/05/2024

De buildconfiguratie van Azure Static Web Apps maakt gebruik van GitHub Actions of Azure Pipelines. Elke site heeft een YAML-configuratiebestand dat bepaalt hoe een site wordt gebouwd en geïmplementeerd. In dit artikel worden de structuur en opties van het bestand uitgelegd.

De volgende tabel bevat de beschikbare configuratie-instellingen.

Eigenschappen	Beschrijving	Vereist
`app_location`	Deze map bevat de broncode voor uw front-endtoepassing. De waarde is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub en de huidige werkmap in Azure DevOps. Wanneer deze waarde wordt gebruikt `skip_app_build: true`, is deze waarde de uitvoerlocatie van de build van de app.	Ja
`api_location`	Deze map met de broncode voor uw API-toepassing. De waarde is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub en de huidige werkmap in Azure DevOps. Wanneer deze waarde wordt gebruikt `skip_api_build: true`, is deze waarde de build-uitvoerlocatie van de API.	Nee
`output_location`	Als uw web-app een buildstap uitvoert, is de uitvoerlocatie de map waarin de openbare bestanden worden gegenereerd. Voor de meeste projecten is het `output_location` relatief ten opzichte van de `app_location`. Voor .NET-projecten is de locatie echter relatief ten opzichte van de uitvoermap.	Nee
`app_build_command`	Voor Node.js toepassingen kunt u een aangepaste opdracht definiëren om de statische inhoudstoepassing te bouwen. Als u bijvoorbeeld een productie-build wilt configureren voor een Angular-toepassing, maakt u een NPM-script dat `build-prod` moet worden uitgevoerd `ng build --prod` en voert u deze `npm run build-prod` in als de aangepaste opdracht. Als u niets opgeeft, probeert de werkstroom de `npm run build` of `npm run build:azure` opdrachten uit te voeren.	Nee
`api_build_command`	Voor Node.js toepassingen kunt u een aangepaste opdracht definiëren om de Azure Functions API-toepassing te bouwen.	Nee
`skip_app_build`	Stel de waarde in om `true` het bouwen van de front-end-app over te slaan.	Nee
`skip_api_build`	Stel de waarde in om `true` het bouwen van de API-functies over te slaan.	Nee
`cwd` (Alleen Azure Pipelines)	Absoluut pad naar de werkmap. Standaard ingesteld op `$(System.DefaultWorkingDirectory)`.	Nee
`build_timeout_in_minutes`	Stel deze waarde in om de time-out van de build aan te passen. Standaard ingesteld op `15`.	Nee

Met deze instellingen kunt u GitHub Actions of Azure Pipelines instellen voor het uitvoeren van continue integratie/continue levering (CI/CD) voor uw statische web-app.

Bestandsnaam en locatie

De GitHub-actie genereert het configuratiebestand en wordt opgeslagen in de map .github/workflows, met de naam met de volgende indeling: azure-static-web-apps-<RANDOM_NAME>.yml

Standaard wordt het configuratiebestand opgeslagen in de hoofdmap van uw opslagplaats met de naam azure-pipelines.yml.

Beveiliging

U kunt kiezen tussen twee verschillende beleidsregels voor implementatieautorisatie om uw buildconfiguratie te beveiligen. Static Web Apps ondersteunt het gebruik van een Azure-implementatietoken (aanbevolen) of een GitHub-toegangstoken.

Gebruik de volgende stappen om het autorisatiebeleid voor de implementatie in te stellen in uw app:

Nieuwe apps: Wanneer u uw statische web-app maakt, maakt u op het tabblad Implementatieconfiguratie een selectie voor het implementatieautorisatiebeleid.
Bestaande apps: Als u een bestaande app wilt bijwerken, gaat u naar de configuratieconfiguratie van instellingen>en>maakt u een selectie voor het implementatieautorisatiebeleid.

Configuratie compileren

In de volgende voorbeeldconfiguratie wordt de opslagplaats gecontroleerd op wijzigingen. Wanneer doorvoeringen naar de main vertakking worden gepusht, wordt de toepassing gebouwd vanuit de app_location map en worden bestanden in het output_location openbare web aangeboden. Daarnaast is de toepassing in de API-map beschikbaar onder het pad van api de site.

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

In deze configuratie:

De main vertakking wordt gecontroleerd op doorvoeringen.
De app_location verwijst naar de src map die de bronbestanden voor de web-app bevat. Deze waarde is relatief ten opzichte van de werkmap (cwd). Als u deze wilt instellen op de werkmap, gebruikt u /.
De api_location verwijst naar de api map die de Azure Functions-toepassing voor de API-eindpunten van de site bevat. Deze waarde is relatief ten opzichte van de werkmap (cwd). Als u deze wilt instellen op de werkmap, gebruikt u /.
De output_location map verwijst naar de public map die de definitieve versie van de bronbestanden van de app bevat. Deze waarde is relatief ten app_locationopzichte van . Voor .NET-projecten is de locatie relatief ten opzichte van de uitvoermap.
Het cwd is een absoluut pad dat verwijst naar de werkmap. Deze wordt standaard ingesteld op $(System.DefaultWorkingDirectory).
De $(deployment_token) variabele verwijst naar het gegenereerde Azure DevOps-implementatietoken.

Notitie

app_location en api_location moet relatief zijn ten opzichte van de werkmap (cwd) en moeten submappen zijn onder cwd.

Azure-implementatietoken
GitHub-toegangstoken

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    permissions:
       id-token: write
       contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Install OIDC Client from Core Package
        run: npm install @actions/core@1.6.0 @actions/http-client
      - name: Get Id Token
        uses: actions/github-script@v6
        id: idtoken
        with:
           script: |
               const coredemo = require('@actions/core')
               return await coredemo.getIDToken()
           result-encoding: string
      - 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_GENTLE_WATER }}
          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 source code path
          api_location: "" # Api source code path - optional
          output_location: "dist/angular-basic" # Built app content directory - optional
          production_branch: "dev"
          github_id_token: ${{ steps.idtoken.outputs.result }}
          ###### End of Repository/Build Configurations ######

  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_GENTLE_WATER_030D91C1E }}
          action: "close"

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (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 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations ######
          app_location: "src" # App source code path relative to repository root
          api_location: "api" # Api source code path relative to repository root - optional
          output_location: "public" # Built app content directory, relative to app_location - optional
          ###### End of Repository/Build Configurations ######

  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 }}
          action: "close"

In deze configuratie:

De main vertakking wordt gecontroleerd op doorvoeringen.
Een GitHub Actions-werkstroom wordt geactiveerd wanneer een pull-aanvraag in de main vertakking wordt geopend, gesynchroniseerd, opnieuw geopend of gesloten.
De build_and_deploy_job opdracht wordt uitgevoerd wanneer u doorvoeringen pusht of een pull-aanvraag opent voor de vertakking die in de on eigenschap wordt vermeld.
De app_location verwijst naar de src map die de bronbestanden voor de web-app bevat. Als u deze waarde wilt instellen op de hoofdmap van de opslagplaats, gebruikt u /.
De api_location verwijst naar de api map die de Azure Functions-toepassing voor de API-eindpunten van de site bevat. Als u deze waarde wilt instellen op de hoofdmap van de opslagplaats, gebruikt u /.
De output_location map verwijst naar de public map die de definitieve versie van de bronbestanden van de app bevat. Het is relatief ten opzichte van app_location. Voor .NET-projecten is de locatie relatief ten opzichte van de publicatie-uitvoermap.

Wijzig de waarden voor repo_token, actionen azure_static_web_apps_api_token zoals ze voor u zijn ingesteld door Azure Static Web Apps niet.

Met de taak Pull-aanvraag sluiten wordt automatisch de pull-aanvraag gesloten die de build en implementatie heeft geactiveerd. Deze optionele taak is niet vereist om het proces te laten werken.

Wanneer een pull-aanvraag wordt geopend, bouwt en implementeert de GitHub Action van Azure Static Web Apps de app in een faseringsomgeving. Daarna controleert de taak Pull-aanvraag sluiten of de pull-aanvraag nog steeds is geopend en wordt deze gesloten met een voltooiingsbericht.

Deze taak helpt uw werkstroom voor pull-aanvragen georganiseerd te houden en verouderde pull-aanvragen te voorkomen. Door de runtime de pull-aanvraag automatisch te sluiten, blijft uw opslagplaats up-to-date en wordt uw team op de hoogte gesteld van de status.

De pull-aanvraagtaak sluiten maakt deel uit van de GitHub Actions-werkstroom van Azure Static Web Apps en sluit de pull-aanvraag nadat deze is samengevoegd. Met Azure/static-web-apps-deploy de actie wordt de app geïmplementeerd in Azure Static Web Apps, waarvoor verificatie azure_static_web_apps_api_token is vereist.

Aangepaste buildopdrachten

Voor Node.js toepassingen kunt u gedetailleerde controle over welke opdrachten worden uitgevoerd tijdens het app- of API-buildproces. In het volgende voorbeeld ziet u hoe u build definieert met waarden voor app_build_command en api_build_command.

Notitie

Op dit moment kunt u alleen builds definiëren app_build_command en api_build_command voor Node.js. Als u de Node.js versie wilt opgeven, gebruikt u het engines veld in het package.json bestand.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: '/'
  api_location: 'api'
  output_location: 'dist'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

Front-end-app overslaan

Als u volledige controle over de build voor uw front-end-app nodig hebt, kunt u de automatische build omzeilen en de app implementeren die in een vorige stap is gebouwd.

Ga als volgende te werk om het bouwen van de front-end-app over te slaan:

Stel app_location in op de locatie waar de bestanden die u wilt implementeren.
Stel skip_app_build in op true.
Ingesteld output_location op een lege tekenreeks ('').

Notitie

Zorg ervoor dat het bestand ook in de uitvoermap is staticwebapp.config.json gekopieerd.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Het bouwen van de API overslaan

Als u het bouwen van de API wilt overslaan, kunt u de automatische build omzeilen en de API implementeren die in een vorige stap is gebouwd.

Stappen voor het overslaan van het bouwen van de API:

Stel apiRuntime in het staticwebapp.config.json bestand de juiste runtime en versie in. Raadpleeg Azure Static Web Apps configureren voor de lijst met ondersteunde runtimes en versies.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Stel skip_api_build in op true.
Stel api_location in op de map met de ingebouwde API-app die moet worden geïmplementeerd. Dit pad is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub Actions en cwd in Azure Pipelines.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: "src" # App source code path relative to repository root
  api_location: "api" # Api source code path relative to repository root - optional
  output_location: "public" # Built app content directory, relative to app_location - optional
  skip_api_build: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Time-out van build uitbreiden

De app- en API-builds zijn standaard beperkt tot 15 minuten. U kunt de time-out van de build uitbreiden door de build_timeout_in_minutes eigenschap in te stellen.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

Werkstroom uitvoeren zonder implementatiegeheimen

Soms hebt u uw werkstroom nodig om te blijven verwerken, zelfs wanneer sommige geheimen ontbreken. Als u uw werkstroom wilt configureren om door te gaan zonder gedefinieerde geheimen, stelt u de SKIP_DEPLOY_ON_MISSING_SECRETS omgevingsvariabele in op true.

Wanneer deze functie is ingeschakeld, kan de werkstroom doorgaan zonder de inhoud van de site te implementeren.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

Omgevingsvariabelen

U kunt omgevingsvariabelen voor uw build instellen via de sectie van de env configuratie van een taak.

Zie Oryx-configuratie voor meer informatie over de omgevingsvariabelen die worden gebruikt door Oryx.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Ondersteuning voor Monorepo

Een monorepo is een opslagplaats die code voor meer dan één toepassing bevat. De werkstroom houdt standaard alle bestanden in een opslagplaats bij, maar u kunt de configuratie aanpassen aan één app.

Als u een werkstroombestand wilt richten op één app, geeft u paden in de push en pull_request secties op.

Wanneer u een monorepo instelt, wordt elke configuratie van een statische app beperkt tot alleen bestanden voor één app. De verschillende werkstroombestanden bevinden zich naast elkaar in de map .github/werkstromen van de opslagplaats.

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

In het volgende voorbeeld ziet u hoe u een paths knooppunt toevoegt aan de secties pull_request van een bestand met de push naam azure-static-web-apps-purple-pond.yml.

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

In dit voorbeeld worden alleen wijzigingen aangebracht in de volgende bestanden, waardoor een nieuwe build wordt geactiveerd:

Bestanden in de app1-map
Bestanden in de API1-map
Wijzigingen in het azure-static-web-apps-purple-pond.yml werkstroombestand van de app

Als u meer dan één toepassing in één opslagplaats wilt ondersteunen, maakt u een afzonderlijk werkstroombestand en koppelt u dit aan verschillende Azure Pipelines.

Volgende stappen

Pull-aanvragen controleren in preproductieomgevingen

Delen via

Configuratie bouwen voor Azure Static Web Apps

Bestandsnaam en locatie

Beveiliging

Configuratie compileren

Aangepaste buildopdrachten

Front-end-app overslaan

Het bouwen van de API overslaan

Time-out van build uitbreiden

Werkstroom uitvoeren zonder implementatiegeheimen

Omgevingsvariabelen

Ondersteuning voor Monorepo

Volgende stappen

Feedback

Aanvullende resources