Communiquer avec azd à l’aide du Kit de développement logiciel (SDK)

Les extensions communiquent avec Azure Developer CLI (azd) via une connexion gRPC, en utilisant le SDK azdext. Le SDK permet à votre extension de lire les données du projet et de l’environnement, de solliciter l’utilisateur et de faire appel aux services azd. Cet article vous montre comment utiliser le SDK pour améliorer l’extension d’exemple Contoso Resource Tagger issue du guide de démarrage rapide Créer une extension d’exemple. Vous pouvez appliquer les mêmes modèles à n’importe quelle extension.

Fonctionnement de la communication

Quand vous azd exécutez votre extension, elle démarre un serveur gRPC et transmet deux valeurs à votre extension via des variables d’environnement :

• AZD_SERVER: L’adresse du serveur gRPC, par exemple localhost:12345.
• AZD_ACCESS_TOKEN: jeton d’accès JWT qui autorise les demandes de votre extension.

Votre extension utilise le azdext Kit de développement logiciel (SDK) pour se connecter à ce serveur et appeler azd des services. Le jeton étend chaque requête aux fonctionnalités déclarées par votre extension dans son manifeste.

Créer un client azd

La fonction azdext.NewAzdClient crée un client qui se connecte à azd à l’aide des variables d’environnement que fournit azd. Enveloppez le contexte entrant avec azdext.WithAccessToken afin que le SDK joigne le jeton d’accès à chaque requête :

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
}

Lire les données de projet et d’environnement

Utilisez les services Projet et Environnement pour lire des informations sur le azd projet et l’environnement actuels. Pour l’exemple d’extension, lisez le projet pour pouvoir inspecter ses ressources et ses balises :

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

Lire et écrire des valeurs d’environnement

Le service Environment lit et écrit les valeurs d’environnement. Ces valeurs persistent dans le .azure répertoire du projet. Pour l’exemple d’extension, stockez une valeur d’étiquette requise que l’utilisateur fournit :

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

Inviter l’utilisateur

Le service Prompt fournit des invites cohérentes et interactives qui correspondent à l’expérience azd utilisateur. Pour l’exemple d’extension, invitez l’utilisateur à entrer une valeur de balise manquante :

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

Le service Prompt prend également en charge les boîtes de dialogue de sélection, de confirmation et de sélection multiple. Utilisez ces options au lieu d’écrire votre propre gestion des entrées afin que votre extension corresponde à l’apparence de azd.

Services disponibles

Le azdext Kit de développement logiciel (SDK) expose les services gRPC suivants via le client :

Pour obtenir la liste complète des services et définitions de messages, consultez les fichiers proto dans le référentiel azure-dev et la référence du framework d’extension.

Signaler des erreurs

Retournez les erreurs de vos gestionnaires de commandes afin que azd puisse les afficher de façon cohérente et définir le code de sortie approprié. Encapsulez les erreurs avec leur contexte à l’aide de fmt.Errorf et du verbe %w afin que les appelants puissent inspecter l’erreur sous-jacente :

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

Contenu connexe

• Ajouter des fonctionnalités d’extension
• Ajouter un serveur MCP à une extension
• Publier une extension
• Référence du cadre d’extension