تكوين الإنشاء ل Azure Static Web Apps

يتم تشغيل تكوين إنشاء Azure Static Web Apps إما بواسطة GitHub Actions أو Azure Pipelines. يحتوي كل موقع على ملف تكوين YAML يتحكم في كيفية إنشاء موقع ونشره. تشرح هذه المقالة بنية الملف وخياراته.

يسرد الجدول التالي إعدادات التكوين المتوفرة.

الخاصية	الوصف	مطلوب
app_location	يحتوي هذا المجلد على التعليمات البرمجية المصدر لتطبيق الواجهة الأمامية. القيمة نسبة إلى جذر المستودع في GitHub ومجلد العمل الحالي في Azure DevOps. عند استخدامها مع skip_app_build: true، هذه القيمة هي موقع إخراج بناء التطبيق.	‏‏نعم‬
api_location	هذا المجلد الذي يحتوي على التعليمات البرمجية المصدر لتطبيق API الخاص بك. القيمة نسبة إلى جذر المستودع في GitHub ومجلد العمل الحالي في Azure DevOps. عند استخدامها مع skip_api_build: true، هذه القيمة هي موقع إخراج بناء واجهة برمجة التطبيقات.	لا
output_location	إذا كان تطبيق الويب الخاص بك يقوم بتشغيل خطوة إنشاء، فإن موقع الإخراج هو المجلد الذي يتم فيه إنشاء الملفات العامة. بالنسبة لمعظم المشاريع، output_location تكون نسبة إلى app_location. ومع ذلك، بالنسبة لمشاريع .NET، يكون الموقع نسبة إلى مجلد إخراج النشر.	لا
app_build_command	بالنسبة لتطبيقات Node.js، يمكنك تعريف أمر مخصص لإنشاء تطبيق المحتوى الثابت. على سبيل المثال، لتكوين بناء إنتاج لتطبيق Angular، قم بإنشاء برنامج نصي npm يسمى build-prod للتشغيل ng build --prod وإدخال npm run build-prod كأمر مخصص. إذا ترك فارغا، يحاول سير العمل تشغيل npm run build الأوامر أو npm run build:azure .	لا
api_build_command	بالنسبة لتطبيقات Node.js، يمكنك تعريف أمر مخصص لإنشاء تطبيق Azure Functions API.	لا
skip_app_build	قم بتعيين القيمة إلى true لتخطي إنشاء تطبيق الواجهة الأمامية.	لا
skip_api_build	قم بتعيين القيمة إلى true لتخطي إنشاء وظائف واجهة برمجة التطبيقات.	لا
cwd (Azure Pipelines فقط)	المسار المطلق إلى مجلد العمل. الإعدادات الافتراضية لـ $(System.DefaultWorkingDirectory).	لا
build_timeout_in_minutes	قم بتعيين هذه القيمة لتخصيص مهلة البناء. الإعدادات الافتراضية لـ 15.	لا

باستخدام هذه الإعدادات، يمكنك إعداد GitHub Actions أو Azure Pipelines لتشغيل التكامل المستمر/التسليم المستمر (CI/CD) لتطبيق الويب الثابت.

اسم الملف وموقعه

GitHub Actions

يتم إنشاء ملف التكوين بواسطة GitHub وتخزينه في المجلد .github/workflows ، المسمى باستخدام التنسيق التالي: azure-static-web-apps-<RANDOM_NAME>.yml.

مسارات Azure

بشكل افتراضي، يتم تخزين ملف التكوين في جذر المستودع الخاص بك باسم azure-pipelines.yml.

ضبط البنية

يراقب تكوين العينة التالي المستودع للتغييرات. عند دفع التثبيتات إلى main الفرع، يتم إنشاء التطبيق من app_location المجلد ويتم تقديم الملفات في output_location إلى الويب العام. بالإضافة إلى ذلك، يتوفر التطبيق في مجلد api ضمن مسار الموقع api .

GitHub Actions

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"

في هذا التكوين:

• main تتم مراقبة الفرع للتثبيتات.
• يتم تشغيل سير عمل إجراءات GitHub عندما يكون طلب السحب على main الفرع: مفتوحا أو متزامنا أو أعيد فتحه أو مغلقا.
• build_and_deploy_job ينفذ عند دفع التثبيتات أو فتح طلب سحب مقابل الفرع المدرج في الخاصية on .
• app_location يشير إلى src المجلد الذي يحتوي على الملفات المصدر لتطبيق الويب. لتعيين هذه القيمة إلى جذر المستودع، استخدم /.
• api_location يشير إلى api المجلد الذي يحتوي على تطبيق Azure Functions لنقاط نهاية واجهة برمجة تطبيقات الموقع. لتعيين هذه القيمة إلى جذر المستودع، استخدم /.
• output_location يشير إلى public المجلد الذي يحتوي على الإصدار النهائي من ملفات مصدر التطبيق. إنها نسبة إلى app_location. بالنسبة لمشاريع .NET، يكون الموقع نسبة إلى مجلد إخراج النشر.

لا تقم بتغيير قيم repo_tokenو actionو azure_static_web_apps_api_token كما تم تعيينها لك بواسطة Azure Static Web Apps.

مسارات Azure

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)

في هذا التكوين:

• main تتم مراقبة الفرع للتثبيتات.
• app_location يشير إلى src المجلد الذي يحتوي على الملفات المصدر لتطبيق الويب. هذه القيمة نسبة إلى دليل العمل (cwd). لتعيينه إلى دليل العمل، استخدم /.
• api_location يشير إلى api المجلد الذي يحتوي على تطبيق Azure Functions لنقاط نهاية واجهة برمجة تطبيقات الموقع. هذه القيمة نسبة إلى دليل العمل (cwd). لتعيينه إلى دليل العمل، استخدم /.
• output_location يشير إلى public المجلد الذي يحتوي على الإصدار النهائي من ملفات مصدر التطبيق. هذه القيمة نسبة إلى app_location. بالنسبة لمشاريع .NET، يكون الموقع نسبة إلى مجلد إخراج النشر.
• cwd هو مسار مطلق يشير إلى دليل العمل. يتم تعيينه افتراضيا إلى $(System.DefaultWorkingDirectory).
• $(deployment_token) يشير المتغير إلى رمز توزيع Azure DevOps الذي تم إنشاؤه.

إشعار

app_locationapi_location ويجب أن تكون نسبة إلى دليل العمل (cwd) ويجب أن تكون أدلة فرعية ضمن cwd.

أوامر الإنشاء المخصصة

بالنسبة لتطبيقات Node.js، يمكنك التحكم الدقيق في الأوامر التي يتم تشغيلها أثناء عملية إنشاء التطبيق أو واجهة برمجة التطبيقات. يوضح المثال التالي كيفية تعريف البنية بقيم ل app_build_command و api_build_command.

إشعار

حاليا، يمكنك فقط تعريف app_build_command و api_build_command لNode.js builds. لتحديد إصدار Node.js، استخدم engines الحقل في package.json الملف.

GitHub Actions

...

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'

مسارات Azure

...

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)

تخطي إنشاء تطبيق الواجهة الأمامية

إذا كنت بحاجة إلى التحكم الكامل في البنية لتطبيق الواجهة الأمامية، يمكنك تجاوز البنية التلقائية ونشر التطبيق المضمن في خطوة سابقة.

لتخطي إنشاء تطبيق الواجهة الأمامية:

• قم بتعيين app_location إلى الموقع الذي تريد نشر الملفات فيه.
• عيّن skip_app_build إلى true.
• تعيين output_location إلى سلسلة فارغة ('').

إشعار

تأكد من نسخ الملف الخاص بك staticwebapp.config.json أيضا في دليل الإخراج .

GitHub Actions

...

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

مسارات Azure

...

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)

تخطي إنشاء واجهة برمجة التطبيقات

إذا كنت ترغب في تخطي إنشاء واجهة برمجة التطبيقات، يمكنك تجاوز الإنشاء التلقائي ونشر واجهة برمجة التطبيقات المضمنة في خطوة سابقة.

خطوات لتخطي إنشاء واجهة برمجة التطبيقات:

• في الملف staticwebapp.config.json ، قم بتعيين apiRuntime إلى وقت التشغيل والإصدار الصحيحين. راجع تكوين Azure Static Web Apps للحصول على قائمة أوقات التشغيل والإصدارات المدعومة.

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

• عيّن skip_api_build إلى true.
• قم بتعيين api_location إلى المجلد الذي يحتوي على تطبيق API المضمن للنشر. هذا المسار نسبة إلى جذر المستودع في GitHub Actions وفي cwd Azure Pipelines.

GitHub Actions

...

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

مسارات Azure

...

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

تمديد مهلة الإنشاء

بشكل افتراضي، تقتصر إصدارات التطبيق وواجهة برمجة التطبيقات على 15 دقيقة. يمكنك تمديد مهلة الإنشاء عن طريق تعيين الخاصية build_timeout_in_minutes .

GitHub Actions

...

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

مسارات Azure

...

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

تشغيل سير العمل بدون أسرار النشر

في بعض الأحيان تحتاج إلى سير العمل الخاص بك لمتابعة المعالجة حتى عندما تكون بعض الأسرار مفقودة. SKIP_DEPLOY_ON_MISSING_SECRETS قم بتعيين متغير البيئة إلى true لتكوين سير العمل الخاص بك للمتابعة دون أسرار محددة.

عند التمكين، تسمح هذه الميزة لسير العمل بالمتابعة دون نشر محتوى الموقع.

GitHub Actions

...

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

مسارات Azure

...

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

متغيرات البيئة

يمكنك تعيين متغيرات البيئة للبناء الخاص بك عبر env قسم تكوين الوظيفة.

GitHub Actions

...

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

مسارات Azure

...

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

monorepo هو مستودع يحتوي على تعليمات برمجية لأكثر من تطبيق واحد. بشكل افتراضي، يتعقب سير العمل جميع الملفات في مستودع، ولكن يمكنك ضبط التكوين لاستهداف تطبيق واحد.

لاستهداف ملف سير عمل إلى تطبيق واحد، يمكنك تحديد مسارات في push المقطعين و pull_request .

GitHub Actions

عند إعداد monorepo، يتم تحديد نطاق كل تكوين تطبيق ثابت إلى ملفات لتطبيق واحد فقط. ملفات سير العمل المختلفة مباشرة جنبا إلى جنب في مجلد .github/workflows الخاص بالمستودع.

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

يوضح المثال التالي كيفية إضافة عقدة pathspush إلى قسمي و pull_request من ملف يسمى 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

في هذا المثال، تقوم التغييرات التي تم إجراؤها على الملفات التالية فقط بتشغيل بنية جديدة:

• أي ملفات داخل مجلد app1
• أي ملفات داخل مجلد api1
• تغييرات على ملف سير عمل azure-static-web-apps-purple-pond.yml للتطبيق

مسارات Azure

لدعم أكثر من تطبيق واحد في مستودع واحد، قم بإنشاء ملف سير عمل منفصل وربطه ب Azure Pipelines مختلفة.

الخطوات التالية

مراجعة طلبات السحب في بيئات ما قبل الإنتاج