Azure Functions Go 개발자 참조

Important

Azure Functions 대한 Go 지원은 현재 공개 미리 보기로 제공됩니다. 미리 보기 중에 Go 함수 앱은 Flex 소비 계획에서만 지원됩니다.

Azure Functions 인프라를 프로비전하거나 관리하지 않고 이벤트 기반 코드를 실행하는 데 사용할 수 있는 서버리스 컴퓨팅 서비스입니다. Go 작업자를 사용하면 Azure Functions 트리거 생태계와 긴밀하게 통합된 상태에서 Go로 Azure Functions를 네이티브하게 작성할 수 있습니다.

이 가이드는 다음을 도와줍니다.

• Go 프로그래밍 모델 이해
• 프로젝트 코드 만들기 및 구조화
• 트리거 사용
• 로컬 및 Azure 앱 배포 및 실행

일반적인 Azure Functions 개발에 대한 자세한 내용은 Azure Functions 개발자 참조 참조하세요.

시작하기

워크플로에 맞는 환경을 선택하고 Go용 Azure Functions 시작합니다.

• 명령줄 빠른 시작

사전 요구 사항

• Go 1.24 이상
• Azure Functions Core Tools 버전 4.12 이상 실행 func --version 하여 설치된 버전을 확인합니다.
• Azure 리소스를 만들거나 Azure 패키지를 배포할 때 Azure CLI 버전 2.87.0 이상 실행 az version 하여 설치된 버전을 확인합니다.

프로그래밍 모델

Go 작업자는 코드 우선 프로그래밍 모델을 사용합니다. Idiomatic Go 처리기를 사용하여 서버리스 함수 및 해당 트리거를 정의합니다.

진입점

모든 Go 코드 프로젝트는 함수를 main() 만들고 FunctionApp, 함수를 등록하고, 작업자를 시작하는 함수로 시작합니다.

package main

import (
    "fmt"
    "net/http"

    "github.com/azure/azure-functions-golang-worker/sdk"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()

    app.HTTP("hello", hello,
        sdk.WithMethods("GET", "POST"),
        sdk.WithAuth("anonymous"),
    )

    worker.Start(app)
}

func hello(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    fmt.Fprintf(w, "Hello, %s!", name)
}

함수 등록

함수형 옵션 패턴과 플루언트 빌더 API를 사용하여 함수를 등록합니다. 각 트리거 형식에는 개체에 대한 등록 메서드가 있습니다 App .

// HTTP trigger
app.HTTP("myHttpFunc", handler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

// Timer trigger
app.Timer("myTimerFunc", handler,
    sdk.WithSchedule("0 */5 * * * *"),
)

// Azure Cosmos DB trigger
app.CosmosDB("myCosmosFunc", handler,
    sdk.WithDatabase("mydb"),
    sdk.WithContainer("mycontainer"),
    sdk.WithConnection("CosmosDBConnection"),
)

// Azure Service Bus trigger
app.ServiceBusQueue("myServiceBusFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("ServiceBusConnection"),
)

// Event Hubs trigger
app.EventHub("myEventHubFunc", handler,
    sdk.WithEventHubName("myeventhub"),
    sdk.WithConnection("EventHubConnection"),
)

// Event Grid trigger
app.EventGrid("myEventGridFunc", handler)

// Blob trigger (extension model)
app.Blob("myBlobFunc", handler,
    sdk.WithPath("mycontainer/{name}"),
    sdk.WithConnection("AzureWebJobsStorage"),
)

프로젝트 구조

Azure Functions Go 코드 프로젝트는 표준 Go 모듈입니다. 실행 func init --worker-runtime go하면 다음 파일이 생성됩니다.

my-function-app/
├── host.json              # Host configuration
├── local.settings.json    # Local settings (connection strings, app settings)
├── go.mod                 # Go module file
├── go.sum                 # Go module checksums
└── main.go                # Entry point with function registrations

host.json

파일에는 host.json 호스트 수준 구성 옵션이 포함되어 있습니다. 자세한 내용은 host.json 참조를 참조하세요.

local.settings.json

이 파일은 local.settings.json 로컬 개발 중에 사용되는 앱 설정 및 연결 문자열을 저장합니다. 이 파일은 Azure 게시되지 않습니다. 자세한 내용은 로컬 설정 파일을 참조하세요.

유발 요소

Go 작업자는 종속성 요구 사항에 따라 트리거를 두 계층으로 구성합니다.

핵심 트리거

코어 트리거는 gRPC를 통해 페이로드 인라인을 수신합니다. Azure Functions 호스트는 트리거 데이터를 gRPC 메시지로 직렬화하고 작업자는 이를 형식화된 Go 구조체로 역직렬화합니다. 이러한 트리거에는 다음이 있습니다.

• 컴파일 타임 안전성을 갖춘 타입이 지정된 핸들러 시그니처
• 외부 Azure SDK 종속성은 없습니다: encoding/json만 필요합니다.
• 제한된 페이로드: 변경 피드 문서, 메시지 및 이벤트는 개별적이고 크기가 제한된 개체입니다.

지원되는 핵심 트리거:

Trigger	핸들러 시그니처	등록 방법
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB (애저 코스모스 DB)	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus(큐)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (토픽)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

확장 트리거

확장 트리거는 원시 데이터 대신 인증된 Azure SDK 클라이언트를 제공합니다. 호스트는 메타데이터(예: 컨테이너 이름 및 Blob 경로)만 보내고 작업자는 특정 리소스로 범위가 지정된 클라이언트를 생성합니다. 이러한 트리거에는 다음이 있습니다.

• SDK 클라이언트 삽입: 처리기가 즉시 사용할 수 있는 클라이언트를 받습니다.
• 격리된 종속성: Azure SDK 패키지는 triggers/<name>/에 있습니다.
• 스트리밍 지원: gRPC를 통해 버퍼링하지 않고도 큰 페이로드를 읽을 수 있습니다.

확장 트리거를 사용하려면 확장 패키지에 대해 빈 가져오기를 추가합니다.

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"

Trigger	핸들러가 수신함	등록 방법
Blob Storage	*blob.Client	app.Blob()

Blob 트리거 예제

package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob"
    "github.com/azure/azure-functions-golang-worker/sdk"
    _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()
    app.Blob("processBlobTrigger", processBlob,
        sdk.WithPath("samples-workitems/{name}"),
        sdk.WithConnection("AzureWebJobsStorage"),
    )
    worker.Start(app)
}

func processBlob(ctx context.Context, client *blob.Client) error {
    get, err := client.DownloadStream(ctx, nil)
    if err != nil {
        return fmt.Errorf("download error: %w", err)
    }
    data, _ := io.ReadAll(get.Body)
    get.Body.Close()
    log.Printf("Blob size: %d bytes", len(data))
    return nil
}

HTTP 트리거

HTTP 트리거 처리기는 표준 Go net/http 형식을 사용하여 Go 개발자에게 즉시 익숙해집니다.

func myHandler(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    w.Header().Set("Content-Type", "application/json")
    fmt.Fprintf(w, `{"message": "Hello, %s!"}`, name)
}

메서드 및 권한 부여 수준에 HTTP 함수를 등록합니다.

app.HTTP("myApi", myHandler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

HTTP 스트리밍

Go 작업자는 서버에서 보낸 이벤트 또는 대용량 응답 데이터 전송과 같은 시나리오에 대해 HTTP 스트리밍을 지원합니다.

func streamHandler(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming not supported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream")
    for i := 0; i < 10; i++ {
        fmt.Fprintf(w, "data: message %d\n\n", i)
        flusher.Flush()
    }
}

타이머 트리거

타이머 트리거는 cron 식으로 정의된 일정에 따라 실행됩니다.

app.Timer("myScheduledFunc", timerHandler,
    sdk.WithSchedule("0 */5 * * * *"),
)

func timerHandler(ctx context.Context, timer bindings.TimerInfo) error {
    log.Printf("Timer trigger executed at: %s", timer.ScheduleStatus.Next)
    return nil
}

종속성 관리

Go 코드 프로젝트는 종속성 관리에 표준 Go 모듈을 사용합니다.

1. 새 모듈을 초기화합니다.

   go mod init myapp
   

2. Azure Functions Go 작업자 SDK를 추가합니다.

   go get github.com/azure/azure-functions-golang-worker
   

   Blob 트리거를 지원하려면 triggers/blob의 빈 가져오기를 통해 종속성이 자동으로 포함됩니다.

3. 깔끔한 종속성:

   go mod tidy
   

로컬 실행

Azure Functions Core Tools를 사용하여 프로젝트를 로컬로 실행합니다.

func start

핵심 도구 자동:

1. local.settings.json에서 FUNCTIONS_WORKER_RUNTIME = "native" 감지합니다.
2. go.mod 파일이 있으면 네이티브 작업자 런타임을 Go로 해석합니다.
3. 로컬 운영 체제에 대한 프로젝트를 컴파일하기 위해 실행됩니다 go build -o bin/app . .
4. gRPC를 통해 컴파일된 바이너리와 통신하는 Azure Functions 호스트를 시작합니다.
5. 함수 엔드포인트(예: http://localhost:7071/api/hello)를 표시합니다.

로컬 개발을 위한 환경 변수를 구성하는 데 사용합니다 local.settings.json .

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "",
        "FUNCTIONS_WORKER_RUNTIME": "native"
    }
}

Go 프로젝트에 대해 AzureWebJobsStorage 생성된 값이 비어 있습니다. 로컬 개발 중에 호스트 스토리지가 필요한 트리거를 사용하는 경우 스토리지 계정 연결 문자열 또는 UseDevelopmentStorage=true로 설정합니다.

Deployment

컴파일 및 패키징

Azure Functions Core Tools 버전 4.12 이상에서는 일반적인 로컬 및 Azure 배포 흐름에 대한 Go 빌드를 처리합니다.

• func start 는 로컬 Functions 호스트를 시작하기 전에 로컬 운영 체제에 대한 bin/app 으로 프로젝트를 빌드합니다.
• func azure functionapp publish Azure 기존 함수 앱에 프로젝트를 빌드, 패키지 및 배포합니다.
• func pack 는 Linux x64용 bin/app 으로 프로젝트를 빌드하고 배포 가능한 .zip 패키지를 만듭니다.

Azure 위해 패키징할 때 생성된 .zip 파일에는 Linux Functions 호스트에 필요한 파일이 포함됩니다. 컴파일된 이진 파일은 로컬 프로젝트에 bin/app 으로 저장되지만 Core Tools는 이를 배포 패키지의 루트에 앱으로 배치합니다.

func pack --no-build를 사용하는 경우 패키징하기 전에 Linux x64 바이너리를 빌드해야 합니다.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/app .

핵심 도구를 사용하여 배포

func azure functionapp publish 사용하여 Go 프로젝트를 Azure 기존 함수 앱에 배포합니다.

func azure functionapp publish <APP_NAME>

<APP_NAME>은 함수 앱 이름으로 바꿉니다.

zip 패키지 배포

게시와 별도로 배포 패키지를 만들어야 하는 경우에 사용합니다 func pack .

1. 배포 가능한 zip 아티팩트를 만듭니다.

   func pack
   

2. Azure CLI 사용하여 패키지를 배포합니다.

   az functionapp deployment source config-zip --resource-group <RESOURCE_GROUP> --name <APP_NAME> --src <ZIP_FILE_PATH>
   

func pack 의해 생성된 패키지는 Azure 실행할 준비가 되었으므로 배포할 때 원격 빌드를 요청하지 마세요.

Docker 지원

컨테이너에서 Go 코드 프로젝트를 실행할 수 있습니다. Docker 지원을 사용하여 프로젝트를 초기화합니다.

func init --worker-runtime go --docker

이 명령은 표준 프로젝트 파일과 함께 Dockerfile도 생성합니다.

원격 분석 및 관찰 가능성

Azure Functions Go 작업자는 구조적 로깅 및 OpenTelemetry 기반 관찰 가능성을 지원합니다. 표준 log/slog 패키지와 같은 slog.InfoContext컨텍스트 인식 메서드를 사용하여 로그를 현재 함수 호출과 상호 연결합니다. OpenTelemetry를 사용하도록 설정하려면 Functions 호스트를 구성하고 Go 작업자 OpenTelemetry 미들웨어를 앱에 등록합니다. 설정 지침은 Azure Functions에서 OpenTelemetry 사용 문서를 참조하세요.

알려진 제한 사항(미리 보기)

공개 미리 보기 중에는 다음과 같은 제한 사항이 적용됩니다.

• func new는 지원되지 않습니다. main.go를 직접 편집하여 함수를 추가하세요.
• 공개 미리 보기 동안에는 Go에서 Durable Functions가 지원되지 않습니다.
• Go 함수 앱은 Azure Linux에서만 실행됩니다.
• 미리 보기 중에는 트리거에 나열된 트리거 만 지원됩니다.
• Core Tools의 Go 패키징은 현재 Linux x64 앱을 대상으로 합니다.

다음 단계

• 첫 번째 Go 함수 만들기
• Azure Functions 트리거 및 바인딩
• OpenTelemetry를 Azure Functions와 함께 사용하기
• Azure Functions Go 작업자 샘플
• Azure Functions 개발자 가이드