Az Azure Static Web Apps buildkonfigurációja

Az Azure Static Web Apps buildkonfigurációja a GitHub Actionst vagy az Azure Pipelinest használja. Minden hely rendelkezik egy YAML-konfigurációs fájllal, amely szabályozza a helyek létrehozásának és üzembe helyezésének módját. Ez a cikk a fájl felépítését és beállításait ismerteti.

Az alábbi táblázat az elérhető konfigurációs beállításokat sorolja fel.

Tulajdonság	Leírás	Kötelező
app_location	Ez a mappa tartalmazza az előtérbeli alkalmazás forráskódját. Az érték a GitHub adattárgyökéréhez és az Azure DevOps aktuális munkamappájához képest van. A használat során skip_app_build: trueez az érték az alkalmazás buildkimeneti helye.	Igen
api_location	Ez a mappa tartalmazza az API-alkalmazás forráskódját. Az érték a GitHub adattárgyökéréhez és az Azure DevOps aktuális munkamappájához képest van. A használat során skip_api_build: trueez az érték az API buildkimeneti helye.	Nem
output_location	Ha a webalkalmazás buildelési lépést futtat, a kimeneti hely az a mappa, ahol a nyilvános fájlok létrejönnek. A legtöbb projekt esetében a output_locationapp_location. A .NET-projektek esetében azonban a hely a kimeneti mappához képest van.	Nem
app_build_command	Az Node.js alkalmazásokhoz megadhat egy egyéni parancsot a statikus tartalomalkalmazás létrehozásához. Ha például éles buildet szeretne konfigurálni egy Angular-alkalmazáshoz, hozzon létre egy npm-szkriptet, amely az egyéni parancsként való futtatásra ng build --prod és beírásra npm run build-prod szolgálbuild-prod. Ha üresen marad, a munkafolyamat megpróbálja futtatni a npm run build parancsokat.npm run build:azure	Nem
api_build_command	Node.js alkalmazásokhoz egyéni parancsot is megadhat az Azure Functions API-alkalmazás létrehozásához.	Nem
skip_app_build	Állítsa be az értéket úgy, hogy true kihagyja az előtér-alkalmazás készítését.	Nem
skip_api_build	Állítsa be az értéket úgy, hogy true hagyja ki az API-függvények készítését.	Nem
cwd (csak Azure Pipelines)	A munkamappa abszolút elérési útja. Alapértelmezett érték: $(System.DefaultWorkingDirectory).	Nem
build_timeout_in_minutes	Állítsa be ezt az értéket a build időtúllépésének testreszabásához. Alapértelmezett érték: 15.	Nem

Ezekkel a beállításokkal beállíthatja a GitHub Actionst vagy az Azure Pipelinest , hogy folyamatos integrációt/folyamatos kézbesítést (CI/CD) futtasson a statikus webalkalmazáshoz.

Fájlnév és hely

A GitHub-művelet létrehozza a konfigurációs fájlt, és a .github/workflows mappában tárolja, a következő formátummal elnevezve: azure-static-web-apps-<RANDOM_NAME>.yml.

Alapértelmezés szerint a konfigurációs fájl az adattár gyökérkönyvtárában lesz tárolva a névvel azure-pipelines.yml.

Biztonság

A buildkonfiguráció biztonságossá tételéhez két különböző üzembehelyezési engedélyezési szabályzat közül választhat. A Static Web Apps támogatja az Azure üzembehelyezési jogkivonat (ajánlott) vagy a GitHub hozzáférési jogkivonat használatát.

Az alábbi lépésekkel állíthatja be az üzembehelyezési engedélyezési szabályzatot az alkalmazásban:

• Új alkalmazások: A statikus webalkalmazás létrehozásakor a Központi telepítés konfiguráció lapján válasszon az üzembe helyezési engedélyezési szabályzathoz.

• Meglévő alkalmazások: Egy meglévő alkalmazás frissítéséhez lépjen a Beállítások>konfigurációjának>üzembehelyezési konfigurációjához, és válasszon ki egy beállítást az üzembehelyezési engedélyezési szabályzathoz.

Buildelési konfiguráció

Az alábbi mintakonfiguráció figyeli a módosítások adattárát. A véglegesítések leküldése az main ágra történik, az alkalmazás a app_location mappából jön létre, és a output_location fájlokat a nyilvános weben kézbesítik. Emellett az API-mappában lévő alkalmazás a webhely api elérési útja alatt érhető el.

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)

Ebben a konfigurációban:

• Az main ágat a véglegesítések figyelik.
• A app_location webalkalmazás forrásfájljait tartalmazó mappára mutat src . Ez az érték a munkakönyvtárhoz (cwd) képest van. A munkakönyvtárra való beállításhoz használja a következőt /: .
• A api_location hely API-végpontjaihoz tartozó Azure Functions-alkalmazást tartalmazó mappára mutat api . Ez az érték a munkakönyvtárhoz (cwd) képest van. A munkakönyvtárra való beállításhoz használja a következőt /: .
• Az output_location alkalmazás forrásfájljainak végleges verzióját tartalmazó mappára mutat public . Ez az érték a következőhöz viszonyítva app_locationvan: . A .NET-projektek esetében a hely a kimeneti mappához viszonyítva van.
• Ez cwd egy abszolút elérési út, amely a munkakönyvtárra mutat. Alapértelmezés szerint a .$(System.DefaultWorkingDirectory)
• A $(deployment_token) változó a létrehozott Azure DevOps üzembehelyezési jogkivonatra mutat.

Feljegyzés

app_locationés api_location a munkakönyvtárhoz (cwd) viszonyítva kell lenniük, és alkönyvtáraknak kell lenniük a .cwd

Identitásjogkivonat

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"

Azure hozzáférési jogkivonat

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"

Ebben a konfigurációban:

• Az main ágat a véglegesítések figyelik.
• A GitHub Actions-munkafolyamat akkor aktiválódik, ha az main ágon lekéréses kérelem van megnyitva, szinkronizálva, újra megnyitva vagy bezárva.
• A build_and_deploy_job végrehajtás akkor történik, amikor leküldéses véglegesítést hajt végre, vagy lekéréses kérelmet nyit meg a on tulajdonságban felsorolt ágon.
• A app_location webalkalmazás forrásfájljait tartalmazó mappára mutat src . Ha ezt az értéket az adattár gyökerére szeretné állítani, használja a következőt /: .
• A api_location hely API-végpontjaihoz tartozó Azure Functions-alkalmazást tartalmazó mappára mutat api . Ha ezt az értéket az adattár gyökerére szeretné állítani, használja a következőt /: .
• Az output_location alkalmazás forrásfájljainak végleges verzióját tartalmazó mappára mutat public . Ehhez képest app_location. .NET-projektek esetén a hely a közzétételi kimeneti mappához viszonyítva van.

Ne módosítsa az Azure Static Web Apps által beállított értékeketrepo_tokenactionazure_static_web_apps_api_token.

A Lekéréses kérelem bezárása feladat automatikusan bezárja a buildet és az üzembe helyezést kiváltó lekéréses kérelmet. Ez az opcionális feladat nem szükséges a folyamat működéséhez.

Egy lekéréses kérelem megnyitásakor az Azure Static Web Apps GitHub Action létrehozza és üzembe helyezi az alkalmazást egy átmeneti környezetben. Ezt követően a Lekéréses kérelem bezárása feladat ellenőrzi, hogy a lekéréses kérelem még nyitva van-e, és befejező üzenettel zárja-e be.

Ez a feladat segít a lekéréses kérelmek munkafolyamatának rendszerezésében, és megakadályozza az elavult lekéréses kérelmeket. A lekéréses kérelem automatikus bezárásával az adattár naprakész marad, és a csapat értesítést kap az állapotról.

A Lekéréses kérelem bezárása feladat az Azure Static Web Apps GitHub Actions munkafolyamatának része, amely az egyesítése után bezárja a lekéréses kérelmet. A Azure/static-web-apps-deploy művelet üzembe helyezi az alkalmazást az Azure Static Web Appsben, amelyhez hitelesítés azure_static_web_apps_api_token szükséges.

Egyéni buildelési parancsok

Node.js alkalmazások esetében részletesen szabályozhatja, hogy mely parancsok futnak az alkalmazás- vagy API-buildelési folyamat során. Az alábbi példa bemutatja, hogyan definiálhatja a buildet a következő értékekkel app_build_command : és api_build_command.

Feljegyzés

Jelenleg csak Node.js buildeket definiálhat app_build_command és api_build_command használhat. A Node.js verzió megadásához használja a engines fájlban lévő package.json mezőt.

...

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)

Előtérbeli alkalmazás létrehozásának kihagyása

Ha az előtér-alkalmazás buildjének teljes körű vezérlésére van szüksége, megkerülheti az automatikus buildelést, és üzembe helyezheti az előző lépésben létrehozott alkalmazást.

Az előtérbeli alkalmazás létrehozásának kihagyása:

• Állítsa be app_location az üzembe helyezni kívánt fájlok helyét.
• Állítsa a skip_app_build elemet true értékre.
• Állítsa be output_location üres sztringre ('').

Feljegyzés

Győződjön meg arról, hogy a staticwebapp.config.json fájlt is átmásolta a kimeneti könyvtárba.

...

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)

Az API létrehozásának kihagyása

Ha ki szeretné hagyni az API készítését, megkerülheti az automatikus buildelést, és üzembe helyezheti az előző lépésben létrehozott API-t.

Az API létrehozásának kihagyása:

• A staticwebapp.config.json fájlban állítsa be apiRuntime a megfelelő futtatókörnyezetet és verziót. Tekintse meg az Azure Static Web Apps konfigurálását a támogatott futtatókörnyezetek és verziók listájához.

  {
    "platform": {
      "apiRuntime": "node:16"
    }
  }
  

• Állítsa a skip_api_build elemet true értékre.

• Állítsa az api_location üzembe helyezendő beépített API-alkalmazást tartalmazó mappára. Ez az elérési út a GitHub Actionsben és cwd az Azure Pipelinesban található adattár gyökeréhez képest van.

...

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)

Build időtúllépésének meghosszabbítása

Alapértelmezés szerint az alkalmazás- és API-buildek 15 percre korlátozódnak. A tulajdonság beállításával meghosszabbíthatja a build időtúllépését build_timeout_in_minutes .

...

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)

Munkafolyamat futtatása üzembehelyezési titkos kulcsok nélkül

Néha szükség van arra, hogy a munkafolyamat továbbra is feldolgozható legyen, még akkor is, ha néhány titkos kulcs hiányzik. Ha úgy szeretné konfigurálni a munkafolyamatot, hogy meghatározott titkos kulcsok nélkül folytassa a műveletet, állítsa a környezeti változót a SKIP_DEPLOY_ON_MISSING_SECRETS következőre true: .

Ha engedélyezve van, ez a funkció lehetővé teszi a munkafolyamat folytatását a webhely tartalmának üzembe helyezése nélkül.

...

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

Környezeti változók

A build környezeti változóit a env feladat konfigurációjának szakaszán keresztül állíthatja be.

Az Oryx által használt környezeti változókkal kapcsolatos további információkért lásd az Oryx konfigurációját.

...

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

Monorepo-támogatás

A monorepó egy olyan adattár, amely egynél több alkalmazás kódját tartalmazza. Alapértelmezés szerint a munkafolyamat nyomon követi az adattár összes fájlját, de a konfigurációt egyetlen alkalmazás megcélzásához módosíthatja.

Ha egy munkafolyamat-fájlt egyetlen alkalmazásra szeretne célozni, meg kell adnia az útvonalakat a szakaszokban és pull_request a push szakaszokban.

Monorepó beállításakor minden statikus alkalmazáskonfiguráció csak egyetlen alkalmazás fájljaira terjed ki. A különböző munkafolyamat-fájlok egymás mellett élnek az adattár .github/workflows mappájában.

├── .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

Az alábbi példa bemutatja, hogyan adhat hozzá csomópontot paths egy push azure-static-web-apps-purple-pond.yml nevű fájlhoz és pull_request -szakaszokhoz.

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

Ebben a példában csak a következő fájlok módosításai aktiválnak új buildet:

• Az app1 mappában lévő fájlok
• Az api1 mappában lévő fájlok
• Az alkalmazás azure-static-web-apps-purple-pond.yml munkafolyamat-fájljának módosítása

Ha egyetlen adattárban egynél több alkalmazást szeretne támogatni, hozzon létre egy külön munkafolyamat-fájlt, és társítsa azt különböző Azure Pipelines-folyamatokhoz.

Következő lépések

Lekéréses kérelmek áttekintése éles üzem előtti környezetekben