Communiceren met azd met behulp van de SDK

Extensies communiceren met de Azure Developer CLI (azd) via een gRPC-verbinding met behulp van de azdext SDK. Met de SDK kan uw extensie project- en omgevingsgegevens lezen, de gebruiker vragen en services aanroepen azd . In dit artikel leest u hoe u de SDK gebruikt om de voorbeeldextensie Contoso Resource Tagger te verbeteren vanuit de quickstart een voorbeeldextensie bouwen. U kunt dezelfde patronen toepassen op elke extensie.

Opmerking

azd extensies zijn momenteel beschikbaar in de bètaversie.

Hoe communicatie werkt

Wanneer azd uw extensie wordt uitgevoerd, wordt er een gRPC-server gestart en worden twee waarden doorgegeven aan uw extensie via omgevingsvariabelen:

  • AZD_SERVER: Het adres van de gRPC-server, zoals localhost:12345.
  • AZD_ACCESS_TOKEN: Een JWT-toegangstoken dat de aanvragen van uw extensie autoriseert.

Uw extensie maakt gebruik van de azdext SDK om verbinding te maken met deze server en services aan te roepen azd . Het token beperkt elk verzoek tot de mogelijkheden die je extensie opgeeft in het manifest.

Een azd-client maken

De azdext.NewAzdClient functie maakt een client die verbinding maakt met azd met behulp van de omgevingsvariabelen die azd biedt. Verpak de inkomende context met azdext.WithAccessToken, zodat de SDK het toegangstoken aan elk verzoek toevoegt:

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
}

Project- en omgevingsgegevens lezen

Gebruik de Project- en omgevingsservices om informatie te lezen over de huidige azd project en omgeving. Lees het project voor de voorbeeldextensie zodat u de resources en tags ervan kunt controleren:

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

Omgevingswaarden lezen en schrijven

De omgevingsservice leest en schrijft omgevingswaarden. Deze waarden blijven behouden in de .azure map van het project. Sla voor de voorbeeldextensie een vereiste tagwaarde op die de gebruiker biedt:

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

Gebruiker vragen

De promptservice biedt consistente, interactieve prompts die overeenkomen met de azd gebruikerservaring. Voor de voorbeeldextensie vraagt u de gebruiker om een ontbrekende tagwaarde:

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

De promptservice ondersteunt ook selectieprompts, bevestigingsprompts en multiselect-prompts. Gebruik deze opties in plaats van uw eigen invoerverwerking te schrijven, zodat uw extensie overeenkomt met het uiterlijk van azd.

Beschikbare services

De azdext SDK maakt de volgende gRPC-services beschikbaar via de client:

Dienst Description
Project Leest de huidige projectconfiguratie.
Milieu Leest en schrijft omgevingen en omgevingswaarden.
UserConfig Leest en schrijft configuratie op gebruikersniveau.
Implementatie Leest de uitrolcontext en resultaten.
Rekening Leest Azure abonnements- en locatiegegevens.
Prompt Geeft interactieve prompts weer.
AI-model Communiceert met geconfigureerde AI-modellen.
Gebeurtenis Abonneert zich op levenscyclusgebeurtenissen.
Compose Leest en wijzigt de samengestelde verzameling services en bronnen.
Werkproces Voert azd workflows uit.
Telemetry Rapporteert het gebruik van extensies met behulp van azdClient.Telemetry().ReportUsage.

Zie de proto-bestanden in de azure-dev-opslagplaats en de referentie voor het extensieframework voor de volledige lijst met services en berichtdefinities.

Fouten rapporteren

Geef fouten door vanuit je commandhandlers, zodat azd ze consistent kan weergeven en de juiste exitcode kan instellen. Verpakt fouten met context met behulp van fmt.Errorf en het %w werkwoord, zodat bellers de onderliggende fout kunnen inspecteren:

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

Verwante onderwerpen

  • Last updated on