SDK を使用して azd と通信する

拡張機能は、azd SDK を使用して gRPC 接続を介して Azure Developer CLI (azdext) と通信します。 SDK を使用すると、拡張機能でプロジェクトと環境のデータを読み取り、ユーザーにプロンプトを表示し、 azd サービスを呼び出すことができます。 この記事では、SDK を使用して、サンプル拡張機能のビルド クイック スタートから Contoso Resource Tagger サンプル拡張機能を拡張する方法について説明します。 任意の拡張機能に同じパターンを適用できます。

コミュニケーションのしくみ

拡張機能 azd 実行すると、gRPC サーバーが起動し、環境変数を介して 2 つの値が拡張機能に渡されます。

• AZD_SERVER: gRPC サーバーのアドレス ( localhost:12345など)。
• AZD_ACCESS_TOKEN: 拡張機能の要求を承認する JWT アクセス トークン。

拡張機能では、 azdext SDK を使用してこのサーバーに接続し、 azd サービスを呼び出します。 トークンは、拡張機能がマニフェストで宣言する機能に対して各要求のスコープを 設定します。

azd クライアントを作成する

azdext.NewAzdClient関数は、azdが提供する環境変数を使用してazdに接続するクライアント作成します。 SDK が各要求にアクセス トークンをアタッチするように、受信コンテキストを azdext.WithAccessToken でラップします。

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
}

プロジェクトと環境のデータの読み取り

プロジェクト サービスおよび環境サービスを使用して、現在のazd プロジェクトと環境に関する情報を取得します。 サンプル拡張機能の場合は、リソースとタグを調べることができるように、プロジェクトを読みます。

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

環境値の読み取りと書き込み

環境サービスは、環境の値の読み取りと書き込みを行います。 これらの値は、プロジェクトの .azure ディレクトリに保持されます。 サンプル拡張機能の場合は、ユーザーが提供する必要なタグ値を格納します。

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

ユーザーに入力を促す

Prompt サービスは、 azd ユーザー エクスペリエンスに一致する一貫性のある対話型プロンプトを提供します。 サンプル拡張機能の場合は、不足しているタグ値をユーザーに求めます。

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

Prompt サービスでは、選択プロンプト、確認プロンプト、および複数選択プロンプトもサポートされます。 拡張機能が azdの外観と一致するように、独自の入力処理を記述する代わりに、これらのオプションを使用します。

利用可能なサービス

azdext SDK は、クライアントを介して次の gRPC サービスを公開します。

サービスとメッセージ定義の完全な一覧については、azure開発リポジトリの proto ファイルと拡張フレームワークリファレンスを参照してください。

エラーを報告する

コマンドハンドラーからエラーを返して、azd がそれらを一貫して表示し、正しい終了コードを設定できるようにします。 呼び出し元が基になるエラーを確認できるように、fmt.Errorf と %w 動詞を使ってコンテキスト情報を付けてエラーをラップします。

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

関連するコンテンツ

• 拡張機能の追加
• MCP サーバーを拡張機能に追加する
• 拡張機能を発行する
• 拡張機能フレームワークリファレンス