Berkomunikasi dengan azd dengan menggunakan SDK

Ekstensi berkomunikasi dengan Azure Developer CLI (azd) melalui koneksi gRPC dengan menggunakan azdext SDK. SDK memungkinkan ekstensi Anda membaca data proyek dan lingkungan, meminta pengguna, dan memanggil layanan azd . Artikel ini memperlihatkan kepada Anda cara menggunakan SDK untuk meningkatkan ekstensi sampel Contoso Resource Tagger dari mulai cepat Membuat ekstensi sampel. Anda dapat menerapkan pola yang sama ke ekstensi apa pun.

Nota

azd ekstensi saat ini dalam versi beta.

Cara kerja komunikasi

Saat azd menjalankan ekstensi Anda, ekstensi memulai server gRPC dan meneruskan dua nilai ke ekstensi Anda melalui variabel lingkungan:

  • AZD_SERVER: Alamat server gRPC, seperti localhost:12345.
  • AZD_ACCESS_TOKEN: Token akses JWT yang mengotorisasi permintaan ekstensi Anda.

Ekstensi Anda menggunakan SDK azdext untuk terhubung ke server ini dan memanggil layanan azd. Token membatasi setiap permintaan pada kapabilitas yang dideklarasikan ekstensi Anda dalam manifest.

Buat klien azd

Fungsi azdext.NewAzdClient membuat klien yang terhubung ke azd menggunakan variabel lingkungan yang disediakan oleh azd. Bungkus konteks masuk dengan azdext.WithAccessToken sehingga SDK melampirkan token akses ke setiap permintaan:

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
}

Membaca data proyek dan lingkungan

Gunakan layanan Proyek dan Lingkungan untuk membaca informasi tentang azd proyek dan lingkungan saat ini. Untuk ekstensi sampel, baca proyek sehingga Anda dapat memeriksa sumber daya dan tagnya:

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

Membaca dan menulis nilai lingkungan

Layanan Lingkungan membaca dan menulis nilai lingkungan. Nilai-nilai ini bertahan di .azure direktori proyek. Untuk ekstensi sampel, simpan nilai tag yang diperlukan yang disediakan pengguna:

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

Meminta pengguna

Layanan Prompt menyediakan prompt interaktif yang konsisten dan selaras dengan pengalaman pengguna azd. Untuk ekstensi contoh, minta pengguna memasukkan nilai tag yang hilang:

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

Layanan Prompt juga mendukung perintah pemilihan, permintaan konfirmasi, dan perintah multipilih. Gunakan opsi ini alih-alih menulis penanganan input Anda sendiri sehingga ekstensi Anda cocok dengan tampilan dan nuansa azd.

Layanan yang tersedia

azdext SDK mengekspos layanan gRPC berikut melalui klien:

Service Description
Proyek Membaca konfigurasi proyek saat ini.
Lingkungan Membaca dan menulis variabel lingkungan dan nilainya.
UserConfig Membaca dan menulis konfigurasi tingkat pengguna.
Penerapan Membaca konteks dan hasil penyebaran.
Account Membaca informasi langganan dan lokasi Azure.
Petunjuk Menampilkan perintah interaktif.
Model AI Berinteraksi dengan model AI yang dikonfigurasi.
Kejadian Berlangganan ke kejadian siklus hidup.
Alur kerja Menjalankan azd alur kerja.
Telemetri Melaporkan penggunaan ekstensi dengan menggunakan azdClient.Telemetry().ReportUsage.

Untuk daftar lengkap definisi layanan dan pesan, lihat file proto di repositori azure-dev dan referensi kerangka kerja ekstensi.

Melaporkan kesalahan

Kembalikan kesalahan dari penangan perintah Anda agar azd dapat menampilkannya secara konsisten dan menetapkan kode keluar yang benar. Bungkus error dengan konteks menggunakan fmt.Errorf dan fungsi %w verb sehingga pemanggil dapat memeriksa error yang mendasarinya:

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

Konten terkait

  • Terakhir diperbarui pada