Panoramica dei modelli dell'interfaccia della riga di comando per sviluppatori di Azure

Un modello Azure Developer CLI (azd) è un repository di codice che segue le convenzioni azd. Combina la configurazione del progetto, l'infrastruttura come codice e, facoltativamente, il codice sorgente dell'applicazione, consentendo di creare ambienti Azure e distribuzioni ripetibili.

I modelli possono supportare diversi tipi di progetto, tra cui:

• Applicazione completa con uno o più servizi distribuibili.
• Soluzione di sola infrastruttura senza codice dell'applicazione.
• Punto di partenza riutilizzabile che un altro sviluppatore può inizializzare ed estendere.
• Progetto esistente preparato per il provisioning e la distribuzione con azd.

Questo articolo illustra la struttura di un modello e il modo in cui azd i comandi usano i relativi file.

Perché usare un modello?

Un modello acquisisce le decisioni necessarie per eseguire un progetto in Azure. A seconda del progetto, può definire:

• Azure risorse e la relativa configurazione.
• Servizi applicativi distribuibili e istruzioni per la pacchettizzazione.
• Connessioni tra i servizi dell'applicazione e le risorse di Azure.
• Parametri e risultati specifici dell'ambiente.
• Sviluppo locale, integrazione continua e configurazione della continuous delivery.

Poiché la configurazione viene archiviata con il progetto, i team possono esaminare le modifiche nel controllo del codice sorgente e creare ambienti di sviluppo, test e produzione coerenti.

Come azd usa un modello

I file in un modello supportano diverse fasi del azd flusso di lavoro:

• azd init inizializza il progetto e crea un azd ambiente. Può anche usare GitHub Copilot per generare un modello iniziale o copiare un modello esistente.
• azd provisionvaluta le definizioni dell'infrastruttura e crea o aggiorna le risorse Azure.
• azd package predispone servizi applicativi distribuibili secondo azure.yaml.
• azd deployassocia ogni servizio al relativo host Azure e distribuisce il pacchetto dell'applicazione.
• azd up esegue le fasi di provisioning, creazione di pacchetti e distribuzione come flusso di lavoro combinato.

I file modello rimangono file di origine regolari durante questo processo. È possibile esaminarli, modificarli e gestirne il versioning insieme al resto del progetto.

Esplorare la struttura del template Azure Developer CLI

azd i template sono repository di codice standard dotati di risorse aggiuntive di configurazione e infrastruttura. La maggior parte dei modelli usa la struttura seguente:

• azure.yaml file: definisce il progetto e esegue il mapping delle directory di origine distribuibili alle risorse Azure.
• infra folder: contiene i file Bicep o Terraform infrastructure-as-code che creano le risorse Azure.
• src folder : contiene in genere il codice sorgente dell'applicazione distribuibile. I modelli di sola infrastruttura possono omettere l'origine dell'applicazione e i modelli di applicazione possono usare altri nomi di directory di origine.
• .azure folder : contiene gli ambienti e i valori locali creati da azd. Questa cartella è lo stato del progetto locale e non viene normalmente condivisa come parte di un modello riutilizzabile.

Ad esempio, un modello comune azd potrebbe corrispondere alla struttura di cartelle seguente:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd I modelli includono facoltativamente anche una o più delle cartelle seguenti:

• .github cartella : contiene i file del flusso di lavoro CI/CD per GitHub Actions.
• .azdo folder : se si decide di usare Azure Pipelines per CI/CD, definire i file di configurazione del flusso di lavoro in questa cartella.
• .devcontainer folder : definisce un ambiente contenitore di sviluppo per il progetto.

Il diagramma seguente mostra come interagiscono gli asset del modello primario:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Asset obbligatori e facoltativi

La struttura esatta varia in base al progetto, ma la maggior parte dei modelli usa gli asset seguenti.

azure.yaml

Il azure.yaml file è il file di configurazione del progetto primario. Definisce il nome del progetto e può definire servizi distribuibili, provider di infrastruttura, hook, flussi di lavoro e altri azd comportamenti.

Per un servizio dell'applicazione, azure.yaml in genere identifica:

• Il percorso della sorgente dell'applicazione.
• Linguaggio di programmazione o strategia di creazione di pacchetti.
• Servizio Azure che ospita l'applicazione.
• Impostazioni di compilazione, distribuzione, container o Kubernetes.

I modelli di sola infrastruttura possono omettere i servizi dell'applicazione. Per il modello di configurazione completo, vedere lo azure.yamlschema.

Nell'esempio seguente vengono definiti due servizi dell'applicazione. I nomi dei servizi, i percorsi di origine, le lingue e le destinazioni di hosting indicano azd cosa creare un pacchetto e dove distribuirlo:

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Infrastruttura come codice

La maggior parte dei modelli contiene una infra directory con file Bicep o Terraform. Questi file definiscono le risorse Azure, le assegnazioni di ruolo, la rete, le impostazioni dell'applicazione e gli output di distribuzione richiesti dal progetto.

Per il provider di Bicep predefinito, azd in genere usa infra/main.bicep come punto di ingresso della distribuzione e infra/main.parameters.json per eseguire il mapping azd dei valori di ambiente ai parametri Bicep. I modelli Terraform usano infra/main.tf comunemente e i file Terraform correlati.

Ad esempio, un file di parametri Bicep può passare i valori selezionati da azd nella distribuzione dell'infrastruttura:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Al termine del provisioning Bicep, azd archivia gli output dal punto di ingresso come valori di ambiente. I servizi applicativi e gli hook possono usare questi valori per gli endpoint delle risorse, i nomi e altre configurazioni di esecuzione.

output API_ENDPOINT string = api.outputs.uri

Origine dell'applicazione

L'origine dell'applicazione è facoltativa. Quando un modello contiene servizi distribuibili, ogni definizione di servizio punta azure.yaml alla relativa directory di origine. Un template può organizzare i servizi sotto src, utilizzare directory presenti altrove nel repository o far puntare un servizio alla radice del repository.

Il nome della cartella non è significativo. Il project valore in azure.yaml determina dove azd trova ogni servizio.

Configurazione dell'ambiente

La .azure directory contiene lo stato dell'ambiente locale e i valori creati da azd. Può contenere valori di sottoscrizione, località, nome della risorsa, endpoint e valori di output della distribuzione per più ambienti.

Considerare questa directory come stato locale anziché come asset modello riutilizzabile. Non eseguire il commit dei file di ambiente che contengono segreti o valori specifici dell'ambiente.

Asset di supporto

I modelli possono contenere anche:

• definizioni di GitHub Actions o di Azure Pipelines.
• Dockerfiles e configurazione del contenitore.
• Configurazione del contenitore di sviluppo.
• Agganci di comandi e servizi
• Test, script e documentazione del progetto.

Questi asset sono facoltativi e devono essere inclusi solo quando supportano l'esperienza di modello prevista.

Associazione di servizi e risorse

Per distribuire un servizio applicazione, azd deve associarne la definizione in azure.yaml a una risorsa di Azure di cui è già stato eseguito il provisioning. Per impostazione predefinita, azd trova una risorsa il cui azd-service-name tag corrisponde al nome del servizio.

Ad esempio, un servizio chiamato api corrisponde a una risorsa contrassegnata dal tag azd-service-name: api. È invece possibile usare la proprietà del resourceName servizio per identificare in modo esplicito la destinazione di distribuzione.

L'espressione Bicep seguente aggiunge il tag di individuazione ai tag esistenti di una risorsa:

tags: union(tags, {
  'azd-service-name': 'api'
})

Mantenere i nomi dei servizi, le impostazioni di individuazione delle risorse, gli output dell'infrastruttura e le variabili di ambiente dell'applicazione allineati quando si modifica un modello.

Compilare o adattare un modello

L'esperienza di creazione consigliata consiste nell'eseguire azd init e selezionare Configura con GitHub Copilot (anteprima). La sessione dedicata agente Copilot può analizzare i file esistenti, pianificare un nuovo progetto, generare asset modello e convalidare il risultato. Per questo flusso di lavoro e altri metodi di creazione, vedere Iniziare con un nuovo modello.

I file generati non sono associati a Copilot. È possibile esplorare e modificare i file modello direttamente dopo l'inizializzazione. È anche possibile creare gli stessi file manualmente o con un altro agente di codifica di intelligenza artificiale.

Se un modello di Microsoft, l'organizzazione o la community degli sviluppatori fornisce già un'architettura utile, iniziare dal modello esistente e adattarlo per il progetto. Esplorare i modelli disponibili nelle raccolte di modelli.

Linee guida per l'utilizzo dei modelli

Ogni modello è concesso in licenza dal proprietario in base al contratto che accompagna il modello. Determinare quale licenza si applica prima di usare o distribuire un modello.

Microsoft non è responsabile dei modelli non Microsoft e non li visualizza per problemi di sicurezza, privacy, compatibilità o prestazioni. I modelli, inclusi i modelli forniti da Microsoft, non sono supportati da un programma o un servizio di supporto Microsoft e vengono forniti così come sono senza garanzia.

Esaminare tutti i file di modello prima del provisioning. In particolare, valutare le assegnazioni di ruolo, l'esposizione della rete, i metodi di autenticazione, i livelli di servizio, le posizioni delle risorse e i costi previsti.

Passaggi successivi