SDK를 사용하여 azd와 통신

확장은 SDK를 사용하여 azd gRPC 연결을 통해 Azure 개발자 CLI(azdext)와 통신합니다. SDK를 사용하면 확장에서 프로젝트 및 환경 데이터를 읽고, 사용자에게 메시지를 표시하고, 서비스를 호출할 azd 수 있습니다. 이 문서에서는 SDK를 사용하여 샘플 확장 만들기 빠른 시작의 Contoso Resource Tagger 샘플 확장을 확장하는 방법을 설명합니다. 모든 확장에 동일한 패턴을 적용할 수 있습니다.

Note

azd 확장은 현재 베타 버전입니다.

통신 작동 방식

확장을 실행하면 azd gRPC 서버를 시작하고 환경 변수를 통해 확장에 두 값을 전달합니다.

  • 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
}

프로젝트 및 환경 데이터 읽기

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과 일치할 수 있도록 사용자 고유의 입력 처리를 작성하는 대신 이러한 옵션을 사용합니다.

사용 가능한 서비스

SDK는 azdext 클라이언트를 통해 다음과 같은 gRPC 서비스를 노출합니다.

서비스 Description
프로젝트 현재 프로젝트 구성을 읽습니다.
환경 환경 및 환경 값을 읽고 씁니다.
UserConfig 사용자 수준 구성을 읽고 씁니다.
배포 배포 컨텍스트 및 결과를 읽습니다.
거래처 Azure 구독 및 위치 정보를 읽습니다.
프롬프트 대화형 프롬프트를 표시합니다.
AI 모델 구성된 AI 모델과 상호 작용합니다.
Event 수명 주기 이벤트를 구독합니다.
작성 구성된 서비스 및 리소스 집합을 읽고 수정합니다.
워크플로 azd 워크플로를 실행합니다.
테레메트리 를 사용하여 azdClient.Telemetry().ReportUsage확장 사용량을 보고합니다.

서비스 및 메시지 정의의 전체 목록은 azure 개발 리포지토리의 proto 파일 및 확장 프레임워크 참조를 참조하세요.

오류 보고

명령 처리기에서 오류를 반환하여 azd가 해당 오류를 일관되게 표시하고 올바른 종료 코드를 설정할 수 있도록 하세요. 호출자가 근본 원인 오류를 검사할 수 있도록 fmt.Errorf 및 %w 동사를 사용해 오류를 컨텍스트와 함께 래핑하세요.

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

관련 콘텐츠

  • Last updated on