SDK kullanarak azd ile iletişim kurma

Uzantılar, azd SDK’sını kullanarak bir gRPC bağlantısı üzerinden Azure Geliştirici CLI’si (azdext) ile iletişim kurar. SDK, uzantınızın proje ve ortam verilerini okumasına, kullanıcıya sormasına ve hizmetlere çağrı yapmasını azd sağlar. Bu makale, Örnek uzantı oluşturma hızlı başlangıç kılavuzundaki Contoso Resource Tagger örnek uzantısını geliştirmek için SDK’yı nasıl kullanacağınızı gösterir. Aynı desenleri herhangi bir uzantıya uygulayabilirsiniz.

Note

azd uzantılar şu anda beta sürümündedir.

İletişim nasıl çalışır?

Uzantınızı çalıştırdığında azd bir gRPC sunucusu başlatır ve ortam değişkenleri aracılığıyla uzantınıza iki değer geçirir:

  • AZD_SERVER: gRPC sunucusunun adresi, örneğin localhost:12345.
  • AZD_ACCESS_TOKEN: Uzantınızın isteklerini yetkilendirilen bir JWT erişim belirteci.

Uzantınız, bu sunucuya bağlanmak ve azdext hizmetlerini çağırmak için azd SDK’sını kullanır. Belirteç, her isteği uzantınızın bildiriminde bildir ettiği özelliklere göre kapsamlar.

Azd istemcisi oluşturma

azdext.NewAzdClient işlevi, azd tarafından sağlanan ortam değişkenlerini kullanarak azd'e bağlanan bir istemci oluşturur. SDK'nın erişim belirtecini her isteğe eklemesi için gelen bağlamı azdext.WithAccessToken ile sarın:

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
}

Proje ve ortam verilerini okuma

Geçerli azd proje ve ortam hakkındaki bilgileri okumak için Project ve Environment hizmetlerini kullanın. Örnek uzantı için, kaynaklarını ve etiketlerini inceleyebilmeniz için projeyi okuyun:

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

Ortam değerlerini okuma ve yazma

Ortam hizmeti ortam değerlerini okur ve yazar. Bu değerler projenin dizininde .azure kalır. Örnek uzantı için, kullanıcının sağladığı gerekli bir etiket değerini depolayın:

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

Kullanıcıya sor

İstem hizmeti, kullanıcı deneyimiyle azd eşleşen tutarlı ve etkileşimli istemler sağlar. Örnek uzantı için kullanıcıdan eksik etiket değerini iste:

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

İstem hizmeti ayrıca seçim istemlerini, onay istemlerini ve çoklu seçim istemlerini de destekler. Uzantınızın görünümüyle azdeşleşmesi için kendi giriş işlemenizi yazmak yerine bu seçenekleri kullanın.

Kullanılabilir hizmetler

SDK, azdext istemci aracılığıyla aşağıdaki gRPC hizmetlerini kullanıma sunar:

Service Description
Proje Geçerli proje yapılandırmasını okur.
Çevre Ortamları ve ortam değerlerini okur ve yazar.
UserConfig Kullanıcı düzeyinde yapılandırmayı okur ve yazar.
Dağıtım Dağıtım bağlamını ve sonuçlarını okur.
Hesabı Azure aboneliği ve konum bilgilerini okur.
Uyarı Etkileşimli istemleri görüntüler.
Yapay Zeka Modeli Yapılandırılmış yapay zeka modelleriyle etkileşim kurar.
Olay Yaşam döngüsü olaylarına abone olur.
Workflow azd iş akışlarını çalıştırır.
Telemetry Uzantı kullanımını azdClient.Telemetry().ReportUsage kullanarak bildirir.

Hizmetlerin ve ileti tanımlarının tam listesi için azure-dev deposundaki proto dosyalarına ve uzantı çerçevesi başvurusuna bakın.

Rapor hataları

Komut işleyicilerinizden hatalar döndürerek azd bunları tutarlı bir şekilde görüntüleyebilir ve doğru çıkış kodunu ayarlayabilirsiniz. Çağıranların altta yatan hatayı inceleyebilmesi için, hataları fmt.Errorf kullanarak ve %w fiiliyle bağlamla sarın:

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

İlgili içerik

  • Last updated on