Komunikace s Azd pomocí sady SDK

Rozšíření komunikují s nástrojem Azure Developer CLI (azd) prostřednictvím připojení gRPC za použití sady SDK azdext. SDK umožňuje vašemu rozšíření číst data o projektu a prostředí, vyzvat uživatele a volat služby azd. V tomto článku se dozvíte, jak pomocí sady SDK vylepšit ukázkové rozšíření Contoso Resource Tagger z rychlého startu Sestavení ukázkového rozšíření. Stejné vzory můžete použít u libovolného rozšíření.

Note

azd rozšíření jsou aktuálně v beta verzi.

Jak funguje komunikace

Když azd spustí vaše rozšíření, spustí server gRPC a předá vašemu rozšíření dvě hodnoty pomocí proměnných prostředí:

  • AZD_SERVER: Adresa serveru gRPC, například localhost:12345.
  • AZD_ACCESS_TOKEN: Přístupový token JWT, který autorizuje požadavky vašeho rozšíření.

Vaše rozšíření používá azdext sadu SDK pro připojení k tomuto serveru a volání azd služeb. Token omezuje každý požadavek na oprávnění, která vaše rozšíření deklaruje v manifestu.

Vytvoření klienta azd

Funkce azdext.NewAzdClient vytvoří klienta, ke kterému se azd připojí pomocí proměnných prostředí, které azd poskytují. Zabalte příchozí kontext tak azdext.WithAccessToken , aby sada SDK připojila přístupový token ke každému požadavku:

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
}

Číst data projektu a prostředí

Pomocí služeb Project a Environment můžete získat informace o aktuálním azd projektu a prostředí. Pro ukázkové rozšíření si přečtěte projekt, abyste mohli zkontrolovat jeho prostředky a značky:

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

Čtení a zápis hodnot prostředí

Služba Prostředí čte a zapisuje hodnoty prostředí. Tyto hodnoty se uchovávají v .azure adresáři projektu. Pro ukázkové rozšíření uložte požadovanou hodnotu značky, kterou uživatel poskytuje:

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

Vyzvat uživatele

Služba Prompt poskytuje konzistentní interaktivní výzvy, které odpovídají uživatelskému azd prostředí. V případě ukázkového rozšíření se uživateli zobrazí výzva k zadání chybějící hodnoty značky:

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

Služba Prompt také podporuje výzvy k výběru, potvrzovací výzvy a výzvy k vícenásobnému výběru. Tyto možnosti použijte místo psaní vlastního zpracování vstupu, aby vaše rozšíření odpovídalo vzhledu a chování azd.

Dostupné služby

Sada azdext SDK prostřednictvím klienta zveřejňuje následující služby gRPC:

Service Description
Project Přečte aktuální konfiguraci projektu.
Životní prostředí Čte a zapisuje prostředí i jejich hodnoty.
UserConfig Čte a zapisuje konfiguraci na úrovni uživatele.
Nasazení Čte kontext nasazení a výsledky.
Účet Čte informace o předplatném Azure a umístění.
Výzva Zobrazí interaktivní výzvy.
Model AI Komunikuje s nakonfigurovanými modely AI.
Událost Přihlásí se k odběru událostí životního cyklu.
Workflow Spouští azd pracovní postupy.
Telemetry Vykazuje využití rozšíření pomocí azdClient.Telemetry().ReportUsage.

Úplný seznam služeb a definic zpráv najdete v souborech proto v úložišti azure-dev a v referenční dokumentaci k rozhraní rozšíření.

Hlášení chyb

Vracejte chyby z obslužných rutin příkazů, abyste azd je mohli konzistentně zobrazit a nastavit správný ukončovací kód. Zapouzdřete chyby s kontextem pomocí fmt.Errorf a slovesa %w, aby volající kód mohl zkontrolovat původní chybu:

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

Související obsah

  • Poslední aktualizace v