Informazioni di riferimento sullo schema dell'interfaccia della riga di comando per sviluppatori di Azure

Il azure.yaml file è il file di configurazione per i progetti dell'interfaccia della riga di comando per sviluppatori di Azure (azd). Inserirlo nella radice del progetto per definire i servizi, le risorse di Azure, l'infrastruttura, gli hook e la pipeline CI/CD che costituiscono l'applicazione. Quando si eseguono comandi come azd up, azd provisiono azd deploy, l'interfaccia della riga di comando legge questo file per comprendere la struttura dell'app e come distribuirla in Azure.

Questo articolo è un riferimento completo per lo schema azure.yaml. Per informazioni introduttive su azd modelli, vedere Panoramica dei modelli dell'interfaccia della riga di comando per sviluppatori di Azure.

Sample

Di seguito è riportato un esempio generico di un azure.yaml file per un azd modello. Per un esempio reale, vedere dal azure.yamlmodello ToDo NodeJs Mongo:

name: yourApp
metadata:
  template: yourApp@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Proprietà di primo livello

name

(string, required) Nome dell'applicazione. Sono consentite solo lettere minuscole, numeri e trattini (-). Il nome deve iniziare e terminare con una lettera o un numero. Lunghezza minima: 2 caratteri.

name: my-app

resourceGroup

(string) Nome del gruppo di risorse di Azure. Se specificato, esegue l'override del nome del gruppo di risorse usato per il provisioning dell'infrastruttura. Supporta la sostituzione delle variabili di ambiente. Deve essere compreso tra 3 e 64 caratteri.

resourceGroup: rg-my-app-${AZURE_ENV_NAME}

metadata

(oggetto) Metadati relativi al modello di applicazione.

metadata:
  template: todo-nodejs-mongo@0.0.1-beta

infra

(oggetto) Fornisce una configurazione aggiuntiva per il provisioning dell'infrastruttura di Azure.

infra.layers

(matrice di oggetti) Definisce i livelli di provisioning per l'infrastruttura di Azure. Ogni livello rappresenta un'unità indipendente di provisioning.

infra:
  provider: bicep
  layers:
    - name: core
      path: ./infra/core
    - name: services
      path: ./infra/services
      hooks:
        postprovision:
          shell: sh
          run: ./scripts/post-provision.sh

Esempio di provider Terraform as IaC

Per usare Terraform invece di Bicep, impostare su providerterraform. Per altre informazioni, vedere Usare Terraform come provider IaC.

name: yourApp-terraform
metadata:
  template: yourApp-terraform@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice
infra:
  provider: terraform

services

(oggetto) Definizione di servizi che costituiscono l'applicazione. Ogni chiave è un nome del servizio e il valore è un oggetto di configurazione del servizio.

Proprietà del servizio

Tipi di host

La host proprietà determina il tipo di risorsa di Azure usata per l'implementazione del servizio e controlla quali altre proprietà sono valide.

ai.endpoint Config

(oggetto, obbligatorio quando host è ai.endpoint) Fornisce una configurazione aggiuntiva per la distribuzione degli endpoint online di Intelligenza artificiale di Azure.

Configurazione del componente di intelligenza artificiale

Configurazione della distribuzione di intelligenza artificiale

Eredita tutte le proprietà dalla configurazione del componente di intelligenza artificiale, oltre a:

services:
  myendpoint:
    project: ./src/endpoint
    host: ai.endpoint
    config:
      workspace: my-ai-project
      deployment:
        path: ./deployment
        environment:
          MODEL_NAME: ${AZURE_OPENAI_MODEL}

docker

(oggetto) Configurazione di Docker per un servizio. Applicabile solo per gli host che supportano contenitori (containerapp, aks, ai.endpoint, azure.ai.agent).

k8s

(oggetto) Opzioni di configurazione del servizio Azure Kubernetes. Valido solo quando host è aks.

Configurazione della distribuzione

Configurazione del servizio

Configurazione in ingresso

Configurazione Helm

repositories elementi della matrice:

releases elementi della matrice:

Configurazione kustomize

Ganci di servizio

Gli hook a livello di servizio sono eseguiti durante gli eventi del ciclo di vita del servizio. Gli hook devono corrispondere ai nomi degli eventi del servizio preceduti da pre o post. Quando si specificano percorsi, devono essere relativi al percorso del servizio. Per altri dettagli, vedere Personalizzare i flussi di lavoro dell'interfaccia della riga di comando per sviluppatori di Azure usando hook di comandi ed eventi .

Hook del servizio supportati: prerestore, postrestore, prebuildpostbuild, , prepackagepostpackage, predeployprepublishpostpublish, . postdeploy

Ogni hook usa il formato di definizione hook .

Esempi di servizio

App contenitore con opzioni Docker

services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile
      context: ../
  web:
    project: ./src/web
    language: js
    host: containerapp
    docker:
      remoteBuild: true

App contenitore da un'immagine predefinita

services:
  api:
    image: myregistry.azurecr.io/myapp:latest
    host: containerapp

Servizio Azure Kubernetes con hook a livello di servizio

services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: aks
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}
  api:
    project: ./src/api
    language: js
    host: aks
    k8s:
      ingress:
        relativePath: api
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_API_BASE_URL ${SERVICE_API_ENDPOINT_URL}

resources

(oggetto) Definizione delle risorse di Azure usate dall'applicazione. Ogni chiave è un nome di risorsa e il valore è un oggetto di configurazione della risorsa. È possibile fare riferimento alle risorse tramite i servizi tramite la uses proprietà .

Proprietà comuni delle risorse

Tipi di risorse

La type proprietà determina il tipo di risorsa di Azure e controlla quali proprietà aggiuntive sono disponibili.

host.appservice proprietà

runtime Oggetto:

resources:
  web:
    type: host.appservice
    port: 8080
    runtime:
      stack: node
      version: 22-lts
    uses:
      - db

host.containerapp proprietà

ai.openai.model proprietà

model Oggetto:

resources:
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"

ai.project proprietà

models elementi della matrice:

sku Oggetto:

ai.search proprietà

db.cosmos proprietà

containers elementi della matrice:

messaging.eventhubs proprietà

messaging.servicebus proprietà

storage proprietà

keyvault proprietà

Esempio di risorse

resources:
  db:
    type: db.postgres
  cache:
    type: db.redis
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"
  web:
    type: host.containerapp
    port: 3100
    uses:
      - db
      - chatModel

pipeline

(oggetto) Definizione della pipeline di integrazione continua.

pipeline:
  provider: azdo
  variables:
    - CUSTOM_SETTING
  secrets:
    - API_KEY

hooks

(oggetto) Hook a livello di comando. Gli hook devono corrispondere azd ai nomi dei comandi preceduti pre da o post a seconda del momento in cui deve essere eseguito lo script. Quando si specificano percorsi, devono essere relativi al percorso del progetto. Per altri dettagli, vedere Personalizzare i flussi di lavoro dell'interfaccia della riga di comando per sviluppatori di Azure usando hook di comandi ed eventi .

Hook dei comandi supportati: preprovision, postprovisionpreinfracreate, postinfracreate, preinfradelete, , postinfradeletepostdownpreuppostuppostpublishpostpackageprepackagepredownpredeploypostdeployprepublish, , . postrestoreprerestore

Ogni hook usa il formato di definizione hook .

hooks:
  preprovision:
    shell: sh
    run: ./scripts/setup.sh
  postdeploy:
    shell: sh
    run: azd env set APP_URL ${SERVICE_WEB_ENDPOINT_URL}

Definizione hook

Un hook può essere un singolo oggetto hook o una matrice di oggetti hook. Ogni oggetto hook ha le proprietà seguenti:

Configurazione dell'executor hook

La config proprietà accetta proprietà diverse a seconda del kind valore.

Configurazione di JavaScript e TypeScript (js, ts)

Configurazione di Python

Configurazione di .NET (dotnet)

Configurazione della shell (sh, pwsh)

Gli executor della shell non supportano config attualmente le proprietà.

Esempi di hook

Hook specifici della piattaforma

hooks:
  preprovision:
    windows:
      shell: pwsh
      run: ./scripts/setup.ps1
    posix:
      shell: sh
      run: ./scripts/setup.sh

Hook Python con tipo

hooks:
  postprovision:
    kind: python
    run: ./scripts/seed-data.py
    dir: ./scripts
    config:
      virtualEnvName: .venv

Più hook per un singolo evento

hooks:
  postprovision:
    - shell: sh
      run: ./scripts/step1.sh
    - shell: sh
      run: ./scripts/step2.sh

requiredVersions

(oggetto) Fornisce una configurazione aggiuntiva per le versioni richieste di azd e le estensioni.

requiredVersions:
  azd: ">= 0.6.0-beta.3"
  extensions:
    azure.ai.agents: ">=1.0.0"
    my-extension: latest

state

(oggetto) Fornisce una configurazione aggiuntiva per la gestione dello stato.

state.remote

Configurazione di Archiviazione BLOB di Azure

state:
  remote:
    backend: AzureBlobStorage
    config:
      accountName: mystorageaccount
      containerName: azd-state

platform

(oggetto) Fornisce una configurazione aggiuntiva per funzionalità specifiche della piattaforma, ad esempio Azure Dev Center.

Configurazione di Dev Center

Disponibile quando type è devcenter:

platform:
  type: devcenter
  config:
    name: my-devcenter
    project: my-project
    catalog: my-catalog
    environmentDefinition: my-env-def
    environmentType: dev

workflows

(oggetto) Fornisce una configurazione aggiuntiva per i flussi di lavoro, ad esempio il comportamento di override azd up .

Passaggi del flusso di lavoro

Il up flusso di lavoro accetta una steps matrice (o può essere specificata direttamente come matrice). Ogni passaggio esegue un azd comando.

Configurare l'ordine dei passaggi del flusso di lavoro

Il file seguente azure.yaml modifica il comportamento predefinito di azd up per spostare il azd package passaggio dopo il azd provision passaggio. Usare questo approccio negli scenari in cui è necessario conoscere gli URL delle risorse durante il processo di compilazione o creazione di pacchetti.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
workflows:
  up:
    steps:
      - azd: provision
      - azd: package
      - azd: deploy --all

cloud

(oggetto) Fornisce una configurazione aggiuntiva per la distribuzione in cloud sovrani, ad esempio Azure per enti pubblici. Il cloud predefinito è AzureCloud.

cloud:
  name: AzureUSGovernment

Richiedere assistenza

Per informazioni su come inviare un bug, richiedere assistenza o proporre una nuova funzionalità per l'interfaccia della riga di comando per sviluppatori di Azure, visitare la pagina relativa alla risoluzione dei problemi e al supporto tecnico.

Passaggi successivi

• Personalizzare i flussi di lavoro usando hook di comandi ed eventi
• Panoramica dei modelli dell'interfaccia della riga di comando per sviluppatori di Azure
• Usare Terraform come provider IaC
• Gestire le variabili di ambiente