Visão geral dos modelos da CLI do Azure Developer

Um modelo Azure Developer CLI (azd) é um repositório de código que segue azd convenções. Combina configuração de projetos, infraestrutura como código e código fonte opcional para que possas criar ambientes e implementações Azure repetíveis.

Os modelos podem suportar diferentes tipos de projetos, incluindo:

• Uma aplicação completa com um ou mais serviços implantáveis.
• Uma solução apenas de infraestrutura, sem código de aplicação.
• Um ponto de partida reutilizável que outro programador pode inicializar e expandir.
• Um projeto existente que prepara para provisionamento e implementação com azd.

Este artigo explica a estrutura de um template e como azd os comandos utilizam os seus ficheiros.

Porque usar um modelo?

Um template capta as decisões necessárias para executar um projeto no Azure. Dependendo do projeto, pode definir:

• Recursos do Azure e a sua configuração.
• Serviços de aplicação implantáveis e instruções de embalagem.
• Ligações entre serviços de aplicação e recursos do Azure.
• Parâmetros e saídas específicas do ambiente.
• Desenvolvimento local, integração contínua e configuração de entrega contínua.

Como a configuração é armazenada com o projeto, as equipas podem rever alterações no controlo de versões e criar ambientes consistentes de desenvolvimento, teste e produção.

Como azd utiliza um modelo

Os ficheiros num modelo suportam diferentes fases do azd fluxo de trabalho:

• azd init inicializa o projeto e cria um azd ambiente. Também pode usar o GitHub Copilot para gerar um template inicial ou copiar um template existente.
• azd provisionAvalia as definições de infraestrutura e cria ou atualiza recursos do Azure.
• azd package prepara serviços aplicacionais implementáveis de acordo com azure.yaml.
• azd deployassocia cada serviço ao seu host Azure e implementa o pacote da aplicação.
• azd up executa as fases de provisionamento, empacotamento e implementação como um fluxo de trabalho combinado.

Os ficheiros modelo mantêm-se ficheiros fonte normais ao longo deste processo. Podes revê-los, editá-los e controlar versões dos mesmos juntamente com o resto do projeto.

Explore a estrutura do modelo da CLI do Azure Developer

azd Os templates são repositórios de código padrão com ativos adicionais de configuração e infraestrutura. A maioria dos modelos utiliza a seguinte estrutura:

• azure.yaml ficheiro - Define o projeto e associa diretórios de origem passíveis de implementação aos recursos do Azure.
• infra pasta - Contém os ficheiros de infraestrutura como código Bicep ou Terraform que criam os recursos do Azure.
• src pasta - Normalmente contém código-fonte de aplicação implantável. Os modelos apenas de infraestrutura podem omitir a fonte da aplicação, e os modelos podem usar outros nomes de diretórios de origem.
• .azure pasta - Contém ambientes locais e valores criados por azd. Esta pasta é o estado local do projeto e normalmente não é partilhada como parte de um modelo reutilizável.

Por exemplo, um modelo comum azd pode corresponder à seguinte estrutura de pastas:

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 Os modelos também incluem opcionalmente uma ou mais das seguintes pastas:

• .github Pasta - Contém ficheiros de fluxo de trabalho CI/CD para GitHub Actions.
• .azdo pasta - Se você decidir usar o Azure Pipelines for CI/CD, defina os arquivos de configuração do fluxo de trabalho nessa pasta.
• .devcontainer pasta - Define um ambiente de contentor de desenvolvimento para o projeto.

O diagrama seguinte mostra como os ativos principais do template funcionam em conjunto:

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

Recursos obrigatórios e opcionais

A estrutura exata varia consoante o projeto, mas a maioria dos modelos utiliza os seguintes recursos.

azure.yaml

O azure.yaml ficheiro é o ficheiro principal de configuração do projeto. Define o nome do projeto e pode definir serviços implantáveis, fornecedores de infraestrutura, ganchos, fluxos de trabalho e outros azd comportamentos.

Para um serviço de aplicação, azure.yaml identifica comumente:

• O caminho para o código-fonte da aplicação.
• A linguagem de programação ou a estratégia de empacotamento.
• O serviço Azure que hospeda a aplicação.
• Configurações de compilação, implementação, contentor ou Kubernetes.

Modelos apenas de infraestrutura podem omitir serviços de aplicação. Para o modelo de configuração completo, veja o azure.yaml esquema.

O exemplo seguinte define dois serviços de aplicação. Os nomes dos serviços, caminhos de origem, linguagens e alvos de alojamento indicam azd o que embalar e onde implementar:

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

Infraestrutura como código

A maioria dos templates contém um infra diretório com ficheiros Bicep ou Terraform. Estes ficheiros definem os recursos do Azure, atribuições de funções, rede, definições de aplicação e resultados de implementação exigidos pelo projeto.

Para o provedor predefinido do Bicep, azd normalmente utiliza infra/main.bicep como ponto de entrada para a implementação e infra/main.parameters.json para mapear azd os valores de ambiente para parâmetros do Bicep. Os templates de Terraform usam infra/main.tf frequentemente e ficheiros Terraform relacionados.

Por exemplo, um ficheiro de parâmetros Bicep pode passar valores selecionados por azd para a implementação da infraestrutura:

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

Quando o provisionamento Bicep termina, azd armazena as saídas do ponto de entrada como valores de ambiente. Os serviços da aplicação e os hooks podem utilizar estes valores para endpoints de recursos, nomes e outras configurações em tempo de execução.

output API_ENDPOINT string = api.outputs.uri

Fonte da aplicação

O código fonte da aplicação é opcional. Quando um modelo contém serviços implantáveis, cada definição de serviço em azure.yaml aponta para o seu diretório de origem. Um modelo pode organizar serviços em src, usar diretórios noutros locais do repositório, ou apontar um serviço para a raiz do repositório.

O nome da pasta em si não é significativo. O valor de project em azure.yaml determina onde azd encontra cada serviço.

Configuração do ambiente

O .azure diretório contém o estado do ambiente local e os valores criados por azd. Pode conter valores de subscrição, localização, nome do recurso, endpoint e valores de saída da implementação para múltiplos ambientes.

Trate este diretório como estado local em vez de um ativo de modelo reutilizável. Não faça commit de ficheiros de configuração do ambiente que contenham dados sensíveis ou valores específicos de cada ambiente.

Ativos de apoio

Os modelos também podem conter:

• Definições de GitHub Actions ou Azure Pipelines.
• Dockerfiles e configuração de contentores.
• Configuração de contentores de desenvolvimento.
• Ganchos de comando e de serviço.
• Testes, scripts e documentação de projetos.

Estes recursos são opcionais e devem ser incluídos apenas quando suportam a experiência de template pretendida.

Associação de serviços e recursos

Para implementar um serviço de aplicação, azd deve associar a sua definição a azure.yaml um recurso Azure provisionado. Por defeito, azd encontra um recurso cuja azd-service-name etiqueta corresponde ao nome do serviço.

Por exemplo, um serviço chamado api mapeia para um recurso etiquetado com azd-service-name: api. Pode, em vez disso, usar a resourceName propriedade de serviço para identificar explicitamente o destino de implementação.

A seguinte expressão Bicep adiciona a etiqueta de descoberta às etiquetas existentes de um recurso:

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

Mantenha os nomes dos serviços, definições de descoberta de recursos, saídas de infraestrutura e variáveis do ambiente da aplicação alinhados quando editar um modelo.

Constrói ou adapta um modelo

A experiência de criação recomendada é executar azd init e selecionar Configurar com o GitHub Copilot (Pré-visualização). A sessão dedicada do agente do Copilot pode analisar ficheiros existentes, ajudar a planear um novo projeto, gerar ativos de modelo e validar o resultado. Para este fluxo de trabalho e outros métodos de autoria, veja Começar com um novo modelo.

Os ficheiros gerados não estão ligados ao Copilot. Pode explorar e editar os ficheiros template diretamente após a inicialização. Também podes criar os mesmos ficheiros manualmente ou com outro agente de programação de IA.

Se um modelo da Microsoft, da sua organização ou da comunidade de programadores já fornecer uma arquitetura útil, comece pelo modelo existente e adapte-o ao seu projeto. Navegue pelos modelos disponíveis nas galerias de modelos.

Diretrizes de utilização de modelos

Cada modelo é licenciado pelo seu proprietário ao abrigo do acordo que acompanha o modelo. Determine qual a licença aplicável antes de usar ou distribuir um modelo.

A Microsoft não é responsável por modelos que não sejam da Microsoft e não os verifica quanto a questões de segurança, privacidade, compatibilidade ou desempenho. Os modelos, incluindo os fornecidos pela Microsoft, não são suportados por um programa ou serviço de suporte da Microsoft e são fornecidos tal como estão, sem garantia.

Revise todos os ficheiros template antes de provisionar. Em particular, avalie atribuições de funções, exposição da rede, métodos de autenticação, níveis de serviço, localização de recursos e custos esperados.

Próximos passos

Visão geral do desenvolvimento de modelos