Comunicar-se com o azd usando o SDK

As extensões se comunicam com a CLI do Desenvolvedor do Azure (azd) por meio de uma conexão gRPC usando o azdext SDK. O SDK permite que sua extensão acesse dados do projeto e do ambiente, solicite informações ao usuário e chame serviços azd. Este artigo mostra como usar o SDK para aprimorar a extensão de exemplo Contoso Resource Tagger do guia de início rápido Criar uma extensão de exemplo. Você pode aplicar os mesmos padrões a qualquer extensão.

Note

azd as extensões estão atualmente na versão beta.

Como a comunicação funciona

Quando azd executa sua extensão, ela inicia um servidor gRPC e passa dois valores para sua extensão por meio 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.

Sua extensão usa o SDK azdext para se conectar a esse servidor e chamar os serviços azd. O token define os escopos de cada solicitação para os recursos que sua extensão declara em seu manifesto.

Criar um cliente do azd

A função azdext.NewAzdClient cria um cliente que se conecta a azd usando as variáveis de ambiente fornecidas por azd. Envolva o contexto de entrada com azdext.WithAccessToken para que o SDK anexe o token de acesso a cada solicitação:

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 de Projeto e Ambiente para ler informações sobre o projeto e o ambiente atuais azd. Na extensão de exemplo, abra o projeto para inspecionar 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)

Ler e gravar valores de variáveis de ambiente

O serviço de Ambiente lê e grava valores do ambiente. Esses valores persistem no .azure diretório do projeto. Para a extensão de exemplo, armazene um valor de tag obrigatório fornecido pelo usuário:

// 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)
}

Solicite ao usuário

O serviço prompt fornece prompts interativos consistentes que correspondem à experiência do azd usuário. Para a extensão de exemplo, solicite ao usuário um valor ausente da tag:

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 dá suporte a prompts de seleção, prompts de confirmação e prompts de seleção múltipla. Use estas opções em vez de criar sua própria manipulação de entrada, para que sua extensão corresponda à aparência e à experiência de uso de azd.

Serviços disponíveis

O azdext SDK expõe os seguintes serviços gRPC por meio do cliente:

Service Description
Projeto Lê a configuração atual do projeto.
Ambiente Lê e escreve variáveis de ambiente e seus valores.
UserConfig Lê e grava a configuração no nível do usuário.
Implantação Lê o contexto e os resultados da implantação.
Conta Lê informações de assinatura do Azure e de localização.
Prompt Exibe avisos interativos.
Modelo de IA Interage com modelos de IA configurados.
Event Inscreve-se em eventos de ciclo de vida.
Escrever Lê e modifica o conjunto composto de serviços e recursos.
Workflow Executa fluxos de trabalho azd.
Telemetry Relata o uso da extensão usando azdClient.Telemetry().ReportUsage.

Para obter a lista completa de serviços e definições de mensagens, consulte os arquivos proto no repositório azure-dev e a referência do framework de extensão.

Relatar erros

Retorne erros de seus manipuladores de comando para que azd possa exibi-los de forma consistente e definir o código de saída correto. Encapsular erros com o uso de contexto fmt.Errorf e o %w verbo para que os chamadores possam inspecionar o erro subjacente:

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

Conteúdo relacionado

  • Last updated on