Обмен данными с azd с помощью пакета SDK

Расширения взаимодействуют с Azure Developer CLI (azd) через подключение gRPC с помощью пакета SDK azdext. SDK позволяет вашему расширению читать данные проекта и среды, запрашивать ввод у пользователя и вызывать службы azd. В этой статье показано, как использовать пакет SDK для улучшения примера расширения Contoso Resource Tagger из краткого руководства по созданию примера расширения. К любому расширению можно применить те же шаблоны.

Замечание

azd расширения в настоящее время находятся в бета-версии.

Принцип работы коммуникации

Когда azd запускает ваше расширение, он запускает сервер gRPC и передаёт вашему расширению два значения через переменные среды:

  • AZD_SERVER: адрес сервера gRPC, например localhost:12345.
  • AZD_ACCESS_TOKEN: Токен доступа JWT, который авторизует запросы вашего расширения.

Ваше расширение использует SDK azdext для подключения к этому серверу и вызова служб 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 Считывает и записывает конфигурацию уровня пользователя.
Развертывание Считывает контекст развертывания и результаты.
Учетная запись Считывает сведения о подписке Azure и местоположении.
Prompt Отображает интерактивные подсказки.
Модель ИИ Взаимодействует с настроенными моделями ИИ.
Событие Подписывается на события жизненного цикла.
Рабочий процесс Выполняет azd рабочие процессы.
Телеметрия Сообщает об использовании расширения с помощью azdClient.Telemetry().ReportUsage.

Полный список служб и определений сообщений см. в файлах proto в репозитории azure-dev и в справочнике по платформе расширений.

Сообщить об ошибках

Возвращайте ошибки из обработчиков команд, чтобы azd мог единообразно отображать их и устанавливать правильный код завершения. Оборачивайте ошибки контекстом с помощью fmt.Errorf и глагола %w, чтобы вызывающие функции могли проверить исходную ошибку:

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

Связанные материалы

  • Last updated on