Kommunicera med azd med hjälp av SDK

Tillägg kommunicerar med Azure Developer CLI (azd) via en gRPC-anslutning med hjälp av azdext-SDK:t. Med SDK kan ditt tillägg läsa projekt- och miljödata, fråga användaren och anropa azd tjänster. Den här artikeln visar hur du använder SDK för att förbättra Contoso Resource Tagger-exempeltillägget från snabbstarten Skapa ett exempeltillägg. Du kan använda samma mönster för alla tillägg.

Note

azd tillägg är för närvarande i betaversion.

Så här fungerar kommunikationen

När azd du kör tillägget startar det en gRPC-server och skickar två värden till tillägget via miljövariabler:

  • AZD_SERVER: Adressen till gRPC-servern, till exempel localhost:12345.
  • AZD_ACCESS_TOKEN: En JWT-åtkomsttoken som auktoriserar tilläggets begäranden.

Tillägget använder SDK:et azdext för att ansluta till den här servern och anropa azd tjänster. Token omfångsbegränsar varje begäran till de funktioner som ditt tillägg deklarerar i sitt manifest.

Skapa en azd-klient

Funktionen azdext.NewAzdClient skapar en klient som ansluter till azd med hjälp av de miljövariabler som azd tillhandahåller. Omslut den inkommande kontexten med azdext.WithAccessToken så att SDK:et kopplar åtkomsttoken till varje begäran:

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
}

Läsa projekt- och miljödata

Använd projekt- och miljötjänsterna för att läsa information om det aktuella azd projektet och miljön. För exempeltillägget läser du projektet så att du kan granska dess resurser och taggar:

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

Miljövärden för läsning och skrivning

Miljötjänsten läser och skriver miljövärden. Dessa värden finns kvar i .azure katalogen för projektet. För exempeltillägget lagrar du ett obligatoriskt taggvärde som användaren tillhandahåller:

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

Fråga användaren

Prompt-tjänsten innehåller konsekventa, interaktiva frågor som matchar azd användarupplevelsen. För exempeltillägget uppmanar du användaren att ange ett taggvärde som saknas:

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

Prompt-tjänsten stöder även markeringsprompter, bekräftelseprompter och flervalsprompter. Använd de här alternativen i stället för att skriva en egen hantering av indata så att ditt tillägg får samma utseende och känsla som azd.

Tillgängliga tjänster

azdext SDK:n exponerar följande gRPC-tjänster via klienten:

Service Description
Projekt Läser den aktuella projektkonfigurationen.
Miljö Läser och skriver miljöer och miljövärden.
Användarkonfiguration Läser och skriver konfiguration på användarnivå.
Driftsättning Läser distributionskontext och resultat.
Konto Läser Azure prenumerations- och platsinformation.
Prompt Visar interaktiva prompter.
AI-modell Interagerar med konfigurerade AI-modeller.
Event Prenumererar på livscykelhändelser.
Skriv Läser och ändrar den sammansatta uppsättningen med tjänster och resurser.
Arbetsflöde Kör azd arbetsflöden.
Telemetry Rapporterar tilläggsanvändning med hjälp azdClient.Telemetry().ReportUsageav .

En fullständig lista över tjänster och meddelandedefinitioner finns i proto-filerna på lagringsplatsen azure-dev och referensen för tilläggsramverket.

Rapportera fel

Returnera fel från dina kommandohanterare så att azd kan visa dem konsekvent och ange rätt returkod. Omslut fel med kontext med hjälp av fmt.Errorf och verbet %w så att anropare kan inspektera det underliggande felet:

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

Relaterat innehåll

  • Last updated on