Comunica com o azd usando o SDK

As extensões comunicam com a CLI do Azure Developer (azd) através de uma ligação gRPC usando o azdext SDK. O SDK permite que a sua extensão leia dados do projeto e do ambiente, alerte o utilizador e ligue para azd serviços. Este artigo mostra-lhe como utilizar o SDK para melhorar a extensão de exemplo Contoso Resource Tagger do guia de início rápido Criar uma extensão de exemplo. Podes aplicar os mesmos padrões a qualquer extensão.

Como funciona a comunicação

Quando azd executa a sua extensão, inicia um servidor gRPC e passa dois valores à sua extensão através de variáveis de ambiente:

• AZD_SERVER: O endereço do servidor gRPC, como localhost:12345.
• AZD_ACCESS_TOKEN: Um token de acesso JWT que autoriza as solicitações da sua extensão.

A sua extensão utiliza o SDK azdext para estabelecer ligação a este servidor e invocar os serviços azd. O token restringe cada pedido às capacidades que a sua extensão declara no manifest.

Criar um cliente azd

A função azdext.NewAzdClient cria um cliente que se liga a azd utilizando as variáveis de ambiente que azd fornece. Envolva o contexto de entrada com azdext.WithAccessToken para que o SDK anexe o token de acesso a cada pedido:

import (
    "context"
    "fmt"

    "github.com/azure/azure-dev/cli/azd/pkg/azdext"
)

func run(ctx context.Context) error {
    // Attach the AZD_ACCESS_TOKEN to outgoing requests.
    ctx = azdext.WithAccessToken(ctx)

    azdClient, err := azdext.NewAzdClient()
    if err != nil {
        return fmt.Errorf("failed to create azd client: %w", err)
    }
    defer azdClient.Close()

    // Use azdClient to call azd services.
    return nil
}

Ler dados do projeto e do ambiente

Use os serviços Projeto e Ambiente para ler informações sobre o projeto azd atual e o ambiente. Para a extensão de exemplo, leia o projeto para poder inspecionar os seus recursos e tags:

// Get the current project.
getProject, err := azdClient.Project().Get(ctx, &azdext.EmptyRequest{})
if err != nil {
    return fmt.Errorf("failed to get project: %w", err)
}

fmt.Printf("Project name: %s\n", getProject.Project.Name)
fmt.Printf("Project path: %s\n", getProject.Project.Path)

// Get the current environment.
getEnv, err := azdClient.Environment().GetCurrent(ctx, &azdext.EmptyRequest{})
if err != nil {
    return fmt.Errorf("failed to get environment: %w", err)
}

fmt.Printf("Environment name: %s\n", getEnv.Environment.Name)

Leia e escreva valores do ambiente

O serviço de Ambiente lê e escreve os valores do ambiente. Estes valores persistem no .azure diretório do projeto. Para a extensão de exemplo, armazene um valor de etiqueta obrigatório que o utilizador fornece:

// Read an environment value.
getValue, err := azdClient.Environment().GetValue(ctx, &azdext.GetEnvRequest{
    EnvName: getEnv.Environment.Name,
    Key:     "CONTOSO_COST_CENTER",
})
if err == nil {
    fmt.Printf("Cost center: %s\n", getValue.Value)
}

// Write an environment value.
_, err = azdClient.Environment().SetValue(ctx, &azdext.SetEnvRequest{
    EnvName: getEnv.Environment.Name,
    Key:     "CONTOSO_COST_CENTER",
    Value:   "CC-1001",
})
if err != nil {
    return fmt.Errorf("failed to set environment value: %w", err)
}

Avise o utilizador

O serviço Prompt fornece prompts consistentes e interativos que correspondem à experiência do azd utilizador. Para a extensão de exemplo, peça ao utilizador um valor de etiqueta em falta:

promptResponse, err := azdClient.Prompt().Prompt(ctx, &azdext.PromptRequest{
    Options: &azdext.PromptOptions{
        Message: "Enter the cost center tag value",
    },
})
if err != nil {
    return fmt.Errorf("failed to prompt for value: %w", err)
}

costCenter := promptResponse.Value

O serviço Prompt também suporta pedidos de seleção, pedidos de confirmação e pedidos de seleção múltipla. Utilize estas opções em vez de escrever o seu próprio processamento de entradas para que a sua extensão corresponda à aparência e ao comportamento de azd.

Serviços disponíveis

O azdext SDK expõe os seguintes serviços gRPC através do cliente:

Para a lista completa de serviços e definições de mensagens, consulte os ficheiros proto no repositório azure-dev e a referência da estrutura de extensões.

Reportar erros

Devolve os erros dos processadores de comandos para que o azd os possa apresentar de forma consistente e definir o código de saída correto. Encapsule os erros com contexto utilizando fmt.Errorf e o verbo %w para que os chamadores possam inspecionar o erro subjacente:

if err != nil {
    return fmt.Errorf("failed to apply tags: %w", err)
}

Conteúdo relacionado

• Adicionar capacidades de extensão
• Adicionar um servidor MCP a uma extensão
• Publicar uma extensão
• Referência do quadro de extensão