Comunicación con azd mediante el SDK

Las extensiones se comunican con la CLI de Azure Developer (azd) a través de una conexión gRPC mediante el azdext SDK. El SDK permite que la extensión lea los datos del proyecto y del entorno, pida al usuario y llame a los azd servicios. En este artículo se muestra cómo usar el SDK para ampliar la extensión de ejemplo Contoso Resource Tagger de la guía de inicio rápido Compilación de una extensión de ejemplo. Puede aplicar los mismos patrones a cualquier extensión.

Funcionamiento de la comunicación

Cuando azd ejecuta la extensión, inicia un servidor gRPC y pasa dos valores a la extensión a través de variables de entorno:

• AZD_SERVER: la dirección del servidor gRPC, como localhost:12345.
• AZD_ACCESS_TOKEN: Un token de acceso JWT que autoriza las solicitudes de tu extensión.

La extensión usa el SDK azdext para conectarse a este servidor y llamar a los servicios azd. El token limita cada solicitud a las funcionalidades que la extensión declara en su manifiesto.

Creación de un cliente azd

La azdext.NewAzdClient función crea un cliente al que se conecta azd mediante las variables de entorno que azd proporciona. Envuelva el contexto entrante con azdext.WithAccessToken para que el SDK adjunte el token de acceso a cada solicitud:

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
}

Leer datos de proyecto y entorno

Utilice los servicios de Proyecto y Entorno para leer información sobre el azd proyecto y el entorno actuales. Para la extensión de ejemplo, lea el proyecto para poder inspeccionar sus recursos y etiquetas:

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

Leer y escribir valores de entorno

El servicio Environment lee y escribe valores de entorno. Estos valores persisten en el .azure directorio del proyecto. Para la extensión de ejemplo, almacene un valor de etiqueta necesario que proporcione el usuario:

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

Preguntar al usuario

El servicio Prompt proporciona avisos coherentes e interactivos que coinciden con la experiencia del azd usuario. Para la extensión de ejemplo, solicite al usuario un valor de etiqueta que 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

El servicio Prompt también admite avisos de selección, avisos de confirmación y avisos de selección múltiple. Utiliza estas opciones en lugar de escribir tu propia gestión de entradas para que tu extensión coincida con el aspecto y el comportamiento de azd.

Servicios disponibles

El azdext SDK expone los siguientes servicios gRPC a través del cliente:

Para obtener la lista completa de servicios y definiciones de mensajes, consulte los archivos proto en el repositorio azure-dev y la referencia del marco de extensión.

Notificar errores

Devuelve los errores de tus manejadores de comandos para que azd pueda mostrarlos de forma coherente y establecer el código de salida correcto. Envuelve los errores con contexto usando fmt.Errorf y el verbo %w para que quienes llamen puedan inspeccionar el error subyacente:

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

Contenido relacionado

• Adición de funcionalidades de extensión
• Agregar un servidor MCP a una extensión
• Publicación de una extensión
• Referencia del marco de extensibilidad