Usare le variabili di ambiente dell'interfaccia della riga di comando per sviluppatori di Azure

L'interfaccia della riga di comando per sviluppatori di Azure (azd) usa le variabili di ambiente per archiviare e gestire le impostazioni di configurazione per gli ambienti di distribuzione. Queste variabili controllano il provisioning, la distribuzione e l'esecuzione dell'applicazione in Azure. Questo articolo illustra il funzionamento delle variabili di ambiente all'interno degli azd ambienti e fornisce indicazioni sulla gestione efficace delle variabili di ambiente.

Informazioni sulle variabili di ambiente

Nel contesto dell'interfaccia della riga di comando per sviluppatori di Azure, le variabili di ambiente sono coppie chiave-valore associate a ambienti denominati specifici, ad esempio sviluppo, test o produzione. Ogni azd ambiente mantiene un proprio set di variabili di ambiente, consentendo di configurare impostazioni diverse per destinazioni di distribuzione diverse.

Le variabili di ambiente in azd vengono archiviate nei .env file all'interno delle cartelle dell'ambiente nella .azure cartella . Fungono da input per:

Flussi di lavoro di distribuzione delle applicazioni
Configurazioni per servizi e connessioni di Azure
Fornitura dell'infrastruttura tramite Bicep e Terraform

A differenza delle variabili di ambiente tradizionali esistenti a livello di sistema operativo, azd le variabili di ambiente hanno come ambito ambienti specifici all'interno del progetto, fornendo l'isolamento tra destinazioni di distribuzione diverse.

Le variabili di ambiente offrono diversi vantaggi chiave quando si lavora con azd:

Isolamento dell'ambiente: mantenere le configurazioni per sviluppo, test e produzione separate e distinte.
Coerenza della configurazione: assicurarsi che tutti i membri del team usino le stesse impostazioni per un ambiente specifico.
Infrastruttura come codice: definire la parametrizzazione dell'infrastruttura tramite variabili anziché valori hardcoded.
Automazione della distribuzione: abilitare le pipeline CI/CD per la distribuzione in ambienti diversi usando la stessa codebase ma configurazioni diverse.
Gestione semplificata: aggiornare facilmente le impostazioni in tutti i servizi in un ambiente da una posizione centrale.

Ogni azd ambiente ha un proprio set di variabili, consentendo configurazioni specifiche dell'ambiente usando lo stesso codice dell'applicazione e gli stessi modelli di infrastruttura.

Variabili di ambiente e file con estensione env

Le azd variabili di ambiente vengono archiviate nei .env file all'interno delle directory specifiche dell'ambiente del progetto. Quando si crea un ambiente usando azd env new <name>, viene creata una struttura di directory:

.azure/
├── <environment-name>/
│   ├── .env                   # Environment variables for this environment

Il .env file usa un formato standard in cui ogni riga rappresenta una coppia chiave-valore:

KEY1=value1
KEY2=value2

Suggerimento

Per altre informazioni sugli ambienti, vedere l'articolo azd.

Quando esegui comandi come azd up, azd carica automaticamente le variabili dal file dell'ambiente selezionato .env.

Queste variabili influenzano:

Provisioning dell'infrastruttura: variabili come AZURE_LOCATION e AZURE_SUBSCRIPTION_ID determinano dove e come vengono create le risorse.
Distribuzione: variabili come gli endpoint di servizio controllano il modo in cui l'applicazione si connette ai servizi di Azure.
Configurazione dell'applicazione: le variabili possono essere passate alla configurazione dell'applicazione per controllarne il comportamento.
Denominazione delle risorse: variabili come AZURE_RESOURCE_GROUP influenzare i modelli di denominazione delle risorse.

Il .env file viene aggiornato automaticamente anche da azd durante operazioni come azd init, azd provisione azd deploy, acquisendo output dai modelli di infrastruttura e archiviandoli per un uso futuro.

Impostare le variabili di ambiente

È possibile usare metodi diversi per impostare azd le variabili di ambiente, a seconda dello scenario.

Usare i comandi CLI

Il modo consigliato per impostare una variabile di ambiente consiste nell'usare il azd env set comando , che include controlli per garantire valori validi:

azd env set <key> <value>

Ad esempio, per impostare un valore di configurazione per l'applicazione:

azd env set API_TIMEOUT 5000

Il comando aggiunge o aggiorna la variabile nel .env file dell'ambiente attualmente selezionato. È anche possibile specificare come destinazione un ambiente specifico usando il --environment flag :

azd env set API_TIMEOUT 5000 --environment prod

Per verificare che la variabile di ambiente sia stata impostata correttamente:

azd env get-value API_TIMEOUT

Output di Bicep

Una potente funzionalità di azd è la sua capacità di acquisire automaticamente i parametri di output dai modelli di infrastruttura Bicep come variabili ambiente. Ad esempio, quando si definisce un parametro di output nel main.bicep file:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Dopo l'esecuzione di azd provision, questo output viene salvato automaticamente nel file dell'ambiente .env.

API_ENDPOINT=https://api-dev-123456.azurewebsites.net

Questo approccio garantisce che l'applicazione abbia sempre accesso alle informazioni sulle risorse più aggiornate, ad esempio:

Endpoint di servizio e URL
Nomi e identificatori delle risorse

Ottenere e usare le variabili di ambiente

Dopo aver impostato, è possibile accedere alle variabili di ambiente in diversi contesti.

Comandi CLI

Per visualizzare tutte le variabili di ambiente per l'ambiente corrente:

azd env get-values

Per visualizzare il valore di una variabile specifica:

azd env get-value API_ENDPOINT

Per l'output leggibile del computer (utile negli script):

azd env get-values --output json

Usare le variabili di ambiente nei file di infrastruttura

È possibile usare le variabili di ambiente per personalizzare i modelli di infrastruttura. Ciò è utile per la denominazione, l'assegnazione di tag o la configurazione delle risorse in base all'ambiente corrente. azd usa anche i tag per individuare le risorse in Azure per la distribuzione e altre attività.

Considerare il flusso comune seguente:

Durante azd init, azd imposta queste variabili di ambiente in base alla risposta dell'utente alle richieste:
```
AZURE_ENV_NAME=myapp-dev
AZURE_LOCATION=eastus2
```

Fare riferimento a tali variabili nella main.parameters.jsoninfra cartella . azd sostituisce i valori durante il provisioning e passa i parametri risolti a Bicep:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "value": "${AZURE_ENV_NAME}"
    },
    "location": {
      "value": "${AZURE_LOCATION}"
    }
  }
}

Definire i parametri corrispondenti nel modello Bicep:

@description('Name of the environment used to derive resource names and tags.')
param name string

@minLength(1)
@description('Primary Azure region for all resources.')
param location string

azd fornisce questi parametri Bicep con i valori sostituiti in main.parameters.json.

Usare i parametri per la denominazione delle risorse e i tag per identificare in un secondo momento l'ambiente a cui appartiene una risorsa:

var resourceToken = toLower(uniqueString(resourceGroup().id, name, location))

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'st${resourceToken}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  tags: {
    Environment: name
    Project: 'myproject'
  }
}

Questo modello mantiene i modelli flessibili, consente la personalizzazione per ambiente senza modifiche al codice e migliora la governance delle risorse (denominazione, assegnazione di tag e individuazione).

Annotazioni

azd si basa anche sull'assegnazione di tag per individuare le risorse di Azure durante la fase di distribuzione.

Hook

azd Le variabili di ambiente vengono caricate automaticamente e disponibili negli hook e negli script personalizzati definiti nel azure.yaml file, è possibile accedere alle variabili di ambiente usando la sintassi seguente:

Bash
PowerShell

# Use the variables in your script
echo "API endpoint: $API_ENDPOINT"
echo "Deploying to: $AZURE_LOCATION"

# Use the variables in your script
Write-Host "API endpoint: $API_ENDPOINT"
Write-Host "Deploying to: $AZURE_LOCATION"

È possibile definire hook nel azure.yaml file per eseguire questi script in punti specifici del azd ciclo di vita:

hooks:
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/load-env-vars.ps1
      interactive: false
    posix:
      shell: sh
      run: ./scripts/load-env-vars.sh
      interactive: false

Suggerimento

Per altre informazioni sull'uso degli hook, vedere l'articolo Personalizzare i flussi di lavoro con hook .

Rimuovere o aggiornare le variabili

Per rimuovere una variabile dall'ambiente:

azd env unset VARIABLE_NAME

Per aggiornare una variabile esistente:

azd env set VARIABLE_NAME "new-value"

Per aggiornare le variabili di ambiente locali dallo stato corrente delle risorse di Azure:

azd env refresh

L'aggiornamento dell'ambiente è utile quando:

Si vuole assicurarsi che il file locale .env rifletta gli output più recenti dell'infrastruttura, ad esempio stringhe di connessione, endpoint e così via.
È necessario sincronizzare le variabili di ambiente dopo che un compagno di squadra ha aggiornato l'ambiente.

AzD e variabili di ambiente del sistema operativo

azd le variabili di ambiente e le variabili di ambiente del sistema operativo servono scopi diversi e funzionano in modi diversi:

Concetto	CLI per sviluppatori di Azure	Sistema operativo
Posizione	Archiviato nei `.azure/<env-name>/.env` file	Impostare nell'ambiente del sistema operativo
Ambito	Ambito limitato ad un ambiente specifico denominato all'interno di un progetto	Globale per la sessione utente o il sistema
Gestione	Gestito usando `azd env` comandi	Gestito con comandi specifici del sistema operativo (`export`, `set`e così via)
Access	Caricato automaticamente dai `azd` comandi	In genere caricato in modo esplicito in script o applicazioni
Target	Associato a risorse e distribuzioni di Azure	Configurazione del sistema per utilizzo generico
Ciclo di vita	Mantenere la persistenza tra sessioni del terminale	Può essere temporaneo o persistente a seconda della modalità di impostazione

azd non legge o scrive automaticamente le variabili di ambiente del sistema operativo. Tuttavia, è possibile interagire con entrambi i tipi di variabili usando script personalizzati.

Leggere azd le variabili di ambiente e le variabili di ambiente del sistema operativo:

Bash
PowerShell

# Access OS environment variable
echo "OS variable: $PATH"

# Access azd environment variable
echo "AZD variable: $(azd env get-value MY_VARIABLE)"

# Access OS environment variable
Write-Host "OS variable: $env:PATH"

# Access azd environment variable
Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"

Scrivere le azd variabili di ambiente nel sistema operativo o nelle variabili di ambiente del framework:

Bash
PowerShell

# Load all azd environment variables into the current shell session
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

# Load all azd environment variables into the current PowerShell session
foreach ($line in (& azd env get-values)) {
    if ($line -match "([^=]+)=(.*)") {
        $key = $matches[1]
        $value = $matches[2] -replace '^"|"$'
        $env:$key = $value
    }
}

Variabili di ambiente standard

azd imposta e usa diverse variabili di ambiente comuni in tutti gli ambienti:

Variabile	Descrizione	Example	Quando impostata
`AZURE_ENV_NAME`	Nome dell'ambiente corrente	`dev`	Quando viene creato l'ambiente
`AZURE_LOCATION`	Area di Azure in cui vengono distribuite le risorse	`eastus`	Durante il primo provisioning
`AZURE_SUBSCRIPTION_ID`	ID della sottoscrizione di Azure usata	`00000000-0000-0000-0000-000000000000`	Durante il primo provisioning
`AZURE_RESOURCE_GROUP`	Nome del gruppo di risorse	`rg-myapp-dev`	Durante la configurazione
`AZURE_PRINCIPAL_ID`	ID dell'utente/entità del servizio in esecuzione	`00000000-0000-0000-0000-000000000000`	Durante la configurazione
`AZURE_PRINCIPAL_TYPE`	Tipo di entità nell'ambiente.	`1a2b3c`	Durante la configurazione
`AZURE_TENANT_ID`	ID del tenant di Azure utilizzato.	`00000000-0000-0000-0000-000000000000`	Durante la configurazione

Considerazioni su segreti e dati sensibili

Anche se le variabili di ambiente sono utili per la configurazione, richiedono una gestione speciale per i dati sensibili:

Evitare di archiviare segreti nei file con estensione env

.env i file vengono in genere archiviati in testo normale e possono essere facilmente:

Commit accidentale nel controllo del codice sorgente
Condiviso o copiato senza protezioni appropriate
Visualizzato da chiunque abbia accesso ai file di progetto
** Inclusi nei registri di sistema o nei rapporti di errore

Avvertimento

Non archiviare mai segreti in un file dell'interfaccia della riga di comando .env per sviluppatori di Azure. Questi file possono essere facilmente condivisi o copiati in percorsi non autorizzati o controllati nel controllo del codice sorgente. Usare servizi come Azure Key Vault o Il controllo degli accessi in base al ruolo di Azure per soluzioni protette o senza segreti.

Alternative per la gestione dei segreti

Per i dati sensibili, prendere in considerazione questi approcci più sicuri:

Riferimenti ad Azure Key Vault: archiviare i segreti in Azure Key Vault e farvi riferimento nel .env file:
```
azd env set-secret <secret-value>
```
Questo comando crea un segreto del Key Vault e archivia un riferimento a esso nel file .env anziché il valore effettivo.
Identità gestite: configurare i servizi di Azure per l'uso di identità gestite anziché di stringhe di connessione o chiavi di accesso.
Sicurezza specifica dell'ambiente: applicare controlli di sicurezza più rigorosi agli ambienti di produzione rispetto a quelli di sviluppo.
Segreti Just-in-time: Generare credenziali a breve termine durante la distribuzione anziché archiviare segreti persistenti.

Passaggi successivi

Lavora con gli ambienti nell'Azure Developer CLI Personalizza i tuoi flussi di lavoro nell'Azure Developer CLI usando ganci

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-08-14