Comunicare con azd usando l'SDK

Le estensioni comunicano con Azure Developer CLI (azd) tramite una connessione gRPC utilizzando l'SDK azdext. Lo SDK consente all'estensione di leggere i dati del progetto e dell'ambiente, richiedere input all'utente e chiamare i servizi azd. Questo articolo illustra come usare l'SDK per migliorare l'estensione di esempio Contoso Resource Tagger della guida introduttiva Creare un'estensione di esempio. È possibile applicare gli stessi modelli a qualsiasi estensione.

Annotazioni

azd le estensioni sono attualmente in versione beta.

Funzionamento della comunicazione

Quando azd esegue l'estensione, avvia un server gRPC e passa due valori all'estensione tramite variabili di ambiente:

  • AZD_SERVER: indirizzo del server gRPC, ad esempio localhost:12345.
  • AZD_ACCESS_TOKEN: token di accesso JWT che autorizza le richieste dell'estensione.

L'estensione usa l'SDK azdext per connettersi a questo server e chiamare azd i servizi. Il token definisce l'ambito di ogni richiesta alle funzionalità dichiarate dall'estensione nel relativo manifesto.

Creare un client azd

La azdext.NewAzdClient funzione crea un client a cui si connette azd usando le variabili di ambiente fornite azd . Racchiudi il contesto in ingresso con azdext.WithAccessToken in modo che l'SDK aggiunga il token di accesso a ogni richiesta:

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
}

Leggere i dati del progetto e dell'ambiente

Usa i servizi Progetto e Ambiente per leggere informazioni sul azd progetto e sull'ambiente correnti. Per l'estensione di esempio, leggere il progetto in modo da poter esaminare le relative risorse e tag:

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

Leggere e scrivere valori dell'ambiente

Il servizio Ambiente legge e scrive i valori dell'ambiente. Questi valori vengono mantenuti nella .azure directory del progetto. Per l'estensione di esempio, archiviare un valore di tag obbligatorio fornito dall'utente:

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

Richiedi conferma all'utente

Il servizio Prompt fornisce prompt coerenti e interattivi, in linea con l'esperienza utente azd. Per l'estensione di esempio, richiedere all'utente un valore di tag mancante:

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

Il servizio Prompt supporta anche richieste di selezione, richieste di conferma e richieste di selezione multipla. Usa queste opzioni invece di scrivere una gestione dell'input personalizzata, in modo che l'estensione abbia lo stesso aspetto e comportamento di azd.

Servizi disponibili

L'SDK azdext espone i servizi gRPC seguenti tramite il client:

Service Description
Progetto Legge la configurazione corrente del progetto.
Ambiente Legge e scrive ambienti e valori di ambiente.
UserConfig Legge e scrive la configurazione a livello di utente.
Distribuzione Legge il contesto di distribuzione e i risultati.
Account Legge le informazioni sulla sottoscrizione di Azure e sulla località.
Rapido Visualizza prompt interattivi.
Modello di intelligenza artificiale Interagisce con i modelli di intelligenza artificiale configurati.
Event Si sottoscrive agli eventi del ciclo di vita.
Flusso di lavoro Esegue azd flussi di lavoro.
Telemetry Segnala l'utilizzo dell'estensione tramite azdClient.Telemetry().ReportUsage.

Per l'elenco completo dei servizi e delle definizioni dei messaggi, consultare i file .proto nel repository azure-dev e la documentazione di riferimento del framework di estensione.

Segnalare gli errori

Restituisci gli errori dagli handler di comando in modo che azd possa visualizzarli in modo coerente e impostare il codice di uscita corretto. Racchiudere gli errori con informazioni di contesto usando fmt.Errorf e il verbo %w in modo che il codice chiamante possa esaminare l'errore sottostante:

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

Contenuti correlati

  • Ultimo aggiornamento: