使用 SDK 与 azd 通信

扩展使用 azd SDK 通过 gRPC 连接与Azure开发人员 CLI（azdext）通信。 SDK 允许扩展读取项目和环境数据、提示用户并调用服务 azd 。 本文介绍如何使用 SDK 增强来自 构建示例扩展快速入门 的 Contoso 资源标记器示例扩展。 可以将相同的模式应用于任何扩展。

Note

azd 扩展目前以 beta 版提供。

通信的工作原理

运行扩展时 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
}

读取项目和环境数据

使用项目和环境服务读取有关当前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
项目 读取当前项目配置。
环境 读取和写入环境和环境值。
UserConfig 读取和写入用户级配置。
Deployment 读取部署上下文和结果。
帐户 读取Azure订阅和位置信息。
提示 显示交互式提示。
AI 模型 与配置的 AI 模型交互。
事件 订阅生命周期事件。
Workflow 运行 azd 工作流。
Telemetry 通过 azdClient.Telemetry().ReportUsage 报告扩展使用情况。

有关服务和消息定义的完整列表，请参阅 azure 开发存储库中的 proto 文件和扩展框架参考。

报告错误

从命令处理程序返回错误，以便 azd 可以一致地显示错误并设置正确的退出代码。 使用 fmt.Errorf 和 %w 动词为错误添加上下文信息，以便调用方可以检查底层错误：

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

相关内容

  • Last updated on