使用 SDK 與 azd 溝通

擴充功能使用 azd SDK，透過 gRPC 連線與 Azure Developer CLI（azdext）通訊。 SDK 讓你的擴充功能讀取專案和環境資料、提示使用者，並呼叫服務。azd 本文說明如何使用 SDK，強化 建置範例擴充功能快速入門中的 Contoso 資源標記器範例擴充功能。 你可以把相同的模式套用到任何擴充功能上。

Note

azd 擴展目前處於測試階段。

溝通運作方式

執行你的擴充功能時 azd ，會啟動一個 gRPC 伺服器，並透過環境變數將兩個值傳給你的擴充功能：

  • AZD_SERVER：gRPC 伺服器的位址，例如 localhost:12345。
  • AZD_ACCESS_TOKEN：一個 JWT 存取權杖，授權你的擴充功能請求。

你的擴充功能會使用 azdext SDK 連接到這台伺服器並呼叫 azd 服務。 令牌會將每個請求的權限範圍限定於你的擴充功能在 manifest 中宣告的權限。

建立一個 azd 客戶端

這個azdext.NewAzdClient函式會建立一個客戶端，並利用所azd提供的環境變數連接到 azd 。 將進入的上下文包裝成 azdext.WithAccessToken ，讓 SDK 將存取權杖附加到每個請求：

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
}

閱讀專案與環境資料

使用 Project 和 Environment 服務來讀取目前 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)
}

提示使用者

提示服務提供一致 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

提示服務同時支援選擇提示、確認提示及多重選擇提示。 請使用這些選項，而不要自行編寫輸入處理功能，讓你的擴充功能與 azd 的外觀與操作體驗保持一致。

可用的服務

azdext SDK 透過客戶端提供下列 gRPC 服務：

Service Description
計畫 讀取目前專案配置。
環境 讀取及寫入環境和環境變數值。
使用者設定 讀取與寫入使用者層級的設定。
部署 讀取部署上下文與結果。
帳戶 讀取 Azure 訂閱和位置資訊。
提示 顯示互動提示。
AI 模型 與已配置的 AI 模型互動。
事件 訂閱生命週期事件。
Workflow 執行 azd 工作流程。
Telemetry 使用 azdClient.Telemetry().ReportUsage 回報擴充功能的使用情況。

欲了解完整的服務與訊息定義清單，請參閱 azure-dev 儲存庫中的 proto 檔案及擴充框架參考。

報告錯誤

從您的命令處理常式回傳錯誤，讓 azd 能一致地顯示這些錯誤，並設定正確的結束代碼。 使用 fmt.Errorf 和 %w 動詞以帶有上下文的方式包裝錯誤，讓呼叫端可以檢查底層錯誤：

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

相關內容

  • Last updated on