Personalizzare i flussi di lavoro dell'interfaccia della riga di comando per sviluppatori di Azure usando hook di comandi ed eventi

Articolo
01/30/2025

L'interfaccia della riga di comando per sviluppatori di Azure supporta vari punti di estensione per personalizzare i flussi di lavoro e le distribuzioni. Il middleware hook consente di eseguire script personalizzati prima e dopo azd comandi ed eventi del ciclo di vita del servizio. gli hook seguono una convenzione di denominazione usando e post prefissi sul nome dell'evento del servizio o del comando corrispondente azd.

Ad esempio, è possibile eseguire uno script personalizzato negli scenari seguenti:

Usare l'hook di pre-archivio per personalizzare la gestione delle dipendenze.
Usare l'hook pre-distribuzione per verificare le dipendenze esterne o le configurazioni personalizzate prima di distribuire l'app.
Usare il postup hook alla fine di un flusso di lavoro o di una pipeline per eseguire operazioni di pulizia o registrazione personalizzate.

Hook disponibili

Sono disponibili gli hook dei comandi azd seguenti:

prerestore e postrestore: eseguire prima e dopo il ripristino delle dipendenze del pacchetto.
preprovision e postprovision: eseguire prima e dopo la creazione delle risorse di Azure.
predeploy e postdeploy: eseguire prima e dopo la distribuzione del codice dell'applicazione in Azure.
preup e postup: eseguire prima e dopo la pipeline di distribuzione combinata. Up è un comando abbreviato che esegue restore, provisione deploy in sequenza.
predown e postdown: eseguire prima e dopo la rimozione delle risorse.

Sono disponibili gli hook di eventi del ciclo di vita del servizio seguenti:

prerestore e postrestore: eseguire prima e dopo il ripristino dei pacchetti e delle dipendenze del servizio.
prebuild e postbuild: eseguire prima e dopo la compilazione del codice sorgente o del contenitore del servizio.
prepackage e postpackage: eseguire prima e dopo il pacchetto dell'app per la distribuzione.
predeploy e postdeploy: eseguire prima e dopo la distribuzione del codice del servizio in Azure.

Configurazione hook

Gli hook possono essere registrati nel file azure.yaml nella radice o all'interno di una configurazione del servizio specifica. Tutti i tipi di hook supportano le opzioni di configurazione seguenti:

shell: sh | pwsh
- Nota: PowerShell 7 è necessario per pwsh.
run: definire uno script inline o un percorso di un file.
continueOnError: quando il set continuerà a essere eseguito anche dopo che si è verificato un errore di script durante un hook dei comandi (impostazione predefinita false).
interactive: se impostato associa lo script in esecuzione alla console stdin, stdout & stderr (valore predefinito false).
windows: specifica che le configurazioni annidate verranno applicate solo nel sistema operativo Windows. Se questa opzione di configurazione è esclusa, l'hook viene eseguito su tutte le piattaforme.
posix: specifica che le configurazioni annidate verranno applicate solo ai sistemi operativi basati su POSIX (Linux & MaxOS). Se questa opzione di configurazione è esclusa, l'hook viene eseguito su tutte le piattaforme.

Esempi di hook

Gli esempi seguenti illustrano diversi tipi di registrazioni e configurazioni hook.

Registrazione del comando radice

Gli hook possono essere configurati per l'esecuzione per comandi di azd specifici nella radice del file azure.yaml.

La directory del progetto (in cui si trova il file azure.yaml) è la directory di lavoro corrente predefinita (cwd) per gli hook dei comandi.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: # Example of an inline script. (shell is required for inline scripts)
    shell: sh
    run: echo 'Hello'
  preprovision: # Example of external script (Relative path from project root)
    run: ./hooks/preprovision.sh
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Registrazione del servizio

Gli hook possono anche essere configurati per l'esecuzione solo per servizi specifici definiti nel file .yaml.

La directory del servizio (lo stesso percorso definito nella proprietà project della configurazione del servizio nel file azure.yaml) è la cwd predefinita per gli hook del servizio.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice
    hooks:
      prerestore: # Example of an inline script. (shell is required for inline scripts)
        shell: sh
        run: echo 'Restoring API service...'
      prepackage: # Example of external script (Relative path from service path)
        run: ./hooks/prepackage.sh

Hook specifici del sistema operativo

Facoltativamente, gli hook possono essere configurati anche per l'esecuzione in Windows o Posix (Linux & MaxOS). Per impostazione predefinita, se le configurazioni di Windows o Posix vengono escluse, l'hook viene eseguito su tutte le piattaforme.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: 
    posix: # Only runs on Posix environments
      shell: sh
      run: echo 'Hello'
   windows: # Only runs on Windows environments
     shell: pwsh
     run: Write-Host "Hello"
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Più hook per evento

È possibile configurare più hook per evento in ambiti diversi, ad esempio il livello di registrazione radice o per un servizio specifico:

name: example-project
services:
    api:
        project: src/api
        host: containerapp
        language: ts
        hooks:
            postprovision:
                - shell: sh
                  run: scripts/postprovision1.sh
                - shell: sh
                  run: scripts/postprovision2.sh
hooks:
    postprovision:
        - shell: sh
          run: scripts/postprovision1.sh
        - shell: sh
          run: scripts/postprovision2.sh

Usare le variabili di ambiente con hook

Gli hook possono ottenere e impostare variabili di ambiente nel file .env usando i comandi azd env get-values e azd set <key> <value>. Gli hook possono anche recuperare le variabili di ambiente dall'ambiente locale usando la sintassi ${YOUR_ENVIRONMENT VARIABLE}. azd imposta automaticamente determinate variabili di ambiente nel file di .env quando vengono eseguiti comandi, ad esempio AZURE_ENV_NAME e AZURE_LOCATION. Anche i parametri di output del file main.bicep vengono impostati nel file .env. La pagina gestire le variabili di ambiente include altre informazioni sui flussi di lavoro delle variabili di ambiente.

Gli hook possono ottenere e impostare variabili di ambiente inline o tramite script di riferimento, come illustrato nell'esempio seguente:

name: azure-search-openai-demo
metadata:
  template: azure-search-openai-demo@0.0.2-beta
services:
  backend:
    project: ./app/backend
    language: py
    host: appservice
hooks:
  postprovision:
    windows: # Run referenced script that uses environment variables (script shown below)
      shell: pwsh
      run: ./scripts/prepdocs.ps1
      interactive: true
      continueOnError: false
    posix:
      shell: sh
      run: ./scripts/prepdocs.sh
      interactive: true
      continueOnError: false
  postdeploy: # Pull environment variable inline from local device and set in .env file
      shell: sh
      run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}

Script di riferimento: prepdocs.sh:

echo "Loading azd .env file from current environment"

# Use the `get-values` azd command to retrieve environment variables from the `.env` file
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values) 
EOF

echo 'Creating python virtual environment "scripts/.venv"'
python3 -m venv scripts/.venv

echo 'Installing dependencies from "requirements.txt" into virtual environment'
./scripts/.venv/bin/python -m pip install -r scripts/requirements.txt

echo 'Running "prepdocs.py"'
./scripts/.venv/bin/python ./scripts/prepdocs.py './data/*' 
    --storageaccount "$AZURE_STORAGE_ACCOUNT"
    --container "$AZURE_STORAGE_CONTAINER"
    --searchservice "$AZURE_SEARCH_SERVICE"
    --openaiservice "$AZURE_OPENAI_SERVICE"
    --openaideployment "$AZURE_OPENAI_EMB_DEPLOYMENT"
    --index "$AZURE_SEARCH_INDEX"
    --formrecognizerservice "$AZURE_FORMRECOGNIZER_SERVICE"
    --tenantid "$AZURE_TENANT_ID" -v

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 risoluzione dei problemi e supporto.

Condividi tramite