Komunikuj się z azd za pomocą zestawu SDK

Rozszerzenia komunikują się z usługą Azure Developer CLI (azd) przez połączenie gRPC za pomocą zestawu SDK azdext. Zestaw SDK umożliwia rozszerzenie odczytywanie danych projektu i środowiska, monitowanie użytkownika i wywoływanie usług azd . W tym artykule pokazano, jak używać zestawu SDK do ulepszenia przykładowego rozszerzenia Contoso Resource Tagger z przewodnika Szybki start „Tworzenie przykładowego rozszerzenia”. Te same wzorce można zastosować do dowolnego rozszerzenia.

Uwaga / Notatka

azd rozszerzenia są obecnie w wersji beta.

Jak działa komunikacja

Po azd uruchomieniu rozszerzenia uruchamia serwer gRPC i przekazuje dwie wartości do rozszerzenia za pomocą zmiennych środowiskowych:

  • AZD_SERVER: adres serwera gRPC, taki jak localhost:12345.
  • AZD_ACCESS_TOKEN: token dostępu JWT, który autoryzuje żądania rozszerzenia.

Rozszerzenie używa zestawu SDK azdext do łączenia się z tym serwerem i wywoływania usług azd. Token określa zakres każdego żądania do możliwości, które rozszerzenie deklaruje w manifeście.

Tworzenie klienta azd

Funkcja azdext.NewAzdClient tworzy klienta, który łączy się z azd za pomocą zmiennych środowiskowych udostępnianych przez azd. Opakuj przychodzący kontekst w elemencie azdext.WithAccessToken, aby SDK dołączał token dostępu do każdego żądania:

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
}

Odczytywanie danych projektu i środowiska

Użyj usług Projektu i Środowiska, aby odczytywać informacje o bieżącym azd projekcie i środowisku. W przypadku przykładowego rozszerzenia przeczytaj projekt, aby można było sprawdzić jego zasoby i tagi:

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

Odczytywanie i zapisywanie wartości środowiska

Usługa Environment odczytuje i zapisuje wartości środowiska. Te wartości są utrwalane w .azure katalogu projektu. W przypadku przykładowego rozszerzenia zapisz wymaganą wartość tagu udostępnianą przez użytkownika:

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

Monituj użytkownika

Usługa Prompt zapewnia spójne, interaktywne komunikaty, które odpowiadają środowisku użytkownika azd. W przykładowym rozszerzeniu poproś użytkownika o brakującą wartość znacznika:

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

Usługa Prompt obsługuje również okna dialogowe wyboru, okna dialogowe potwierdzenia i okna dialogowe wielokrotnego wyboru. Użyj tych opcji zamiast pisać własną obsługę danych wejściowych, aby rozszerzenie pasło do wyglądu i działania elementu azd.

Dostępne usługi

Zestaw azdext SDK uwidacznia następujące usługi gRPC za pośrednictwem klienta:

Service Description
Project Odczytuje bieżącą konfigurację projektu.
Środowisko Odczytuje i zapisuje zmienne środowiskowe oraz ich wartości.
UserConfig Odczytuje i zapisuje konfigurację na poziomie użytkownika.
Wdrażanie Odczytuje kontekst wdrożenia i wyniki.
Konto Odczytuje informacje o subskrypcji i lokalizacji platformy Azure.
Podpowiedź Wyświetla interakcyjne monity.
Model AI Wchodzi w interakcje ze skonfigurowanymi modelami sztucznej inteligencji.
Zdarzenie Subskrybuje zdarzenia cyklu życia.
Workflow Uruchamia azd przepływy pracy.
Telemetry Raportuje użycie rozszerzenia za pomocą azdClient.Telemetry().ReportUsage.

Aby uzyskać pełną listę usług i definicji komunikatów, zobacz pliki proto w repozytorium azure-dev i dokumentację platformy rozszerzeń.

Zgłaszanie błędów

Zwracaj błędy z procedur obsługi poleceń, aby azd mógł wyświetlać je spójnie i ustawiać prawidłowy kod zakończenia. Opakowuj błędy kontekstem, używając fmt.Errorf i operatora %w, aby kod wywołujący mógł sprawdzić błąd bazowy:

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

Treści powiązane

  • Last updated on