Справочник разработчика Функции Azure Go

Функции Azure — это бессерверная служба вычислений, которую можно использовать для запуска управляемого событиями кода без подготовки или управления инфраструктурой. Рабочий процесс Go позволяет писать функции Azure непосредственно на Go с глубокой интеграцией в экосистему триггеров Функции Azure.

Это руководство поможет вам:

• Общие сведения о модели программирования Go
• Создание и структура кода проекта
• Работа с триггерами
• Развертывание и запуск приложения локально и в Azure

Дополнительные сведения о разработке Функции Azure см. в справочнике по разработчику Функции Azure.

Начало работы

Выберите среду, которая подходит для вашего рабочего процесса, и начните работу с Функции Azure for Go:

• Краткое руководство по командной строке

Необходимые условия

• Go 1.24 или более поздней версии
• Функции Azure Core Tools версии 4.12 или более поздней версии. Запустите func --version, чтобы проверить установленную версию.
• Azure CLI версии 2.87.0 или более поздней версии при создании ресурсов Azure или развертывании пакетов в Azure. Выполните команду az version, чтобы проверить установленную версию.

Модель программирования

Обработчик Go использует модель программирования с приоритетом кода. Вы определяете бессерверные функции и их триггеры с помощью идиоматических обработчиков 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 построителя fluent с помощью шаблона функциональных параметров. Каждый тип триггера имеет метод регистрации объекта 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"),
)

структура проекта

Проект кода Go для Функции Azure — это стандартный модуль 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 сериализует данные триггера в сообщение gRPC, а рабочий процесс десериализует их в типизированные структуры Go. Эти триггеры имеют следующие компоненты:

• Типизированные подписи обработчика с безопасностью во время компиляции
• Без внешних зависимостей от Azure SDK: требуется только encoding/json
• Полезные нагрузки ограниченного размера: документы ленты изменений, сообщения и события являются отдельными объектами ограниченного размера

Поддерживаемые основные триггеры:

Триггеры расширения

Триггеры расширения предоставляют проверенный клиент Azure SDK вместо необработанных данных. Хост отправляет только метаданные (например, имя контейнера и путь к BLOB-объекту), а рабочий процесс создает клиент для конкретного ресурса. Эти триггеры имеют следующие компоненты:

• Внедрение клиента SDK: обработчик получает клиент, готовый к использованию
• Изолированные зависимости: пакеты Azure SDK живут в triggers/<name>/
• Поддержка потоковой передачи: позволяет считывать большие полезные данные без буферизации с помощью gRPC

Чтобы использовать триггер расширения, добавьте пустой импорт для пакета расширения:

import _ "github.com/azure/azure-functions-golang-worker/triggers/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. Добавьте пакет SDK обработчика Go для Функции Azure:

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

   Для поддержки триггера больших двоичных объектов зависимость добавляется автоматически через пустой импорт triggers/blob.

3. Упорядочить зависимости:

   go mod tidy
   

Запустить локально

Используйте Функции Azure Core Tools для локального запуска проекта:

func start

Базовые инструменты автоматически:

1. Обнаруживает FUNCTIONS_WORKER_RUNTIME = "native" из local.settings.json.
2. Определяет Go как среду выполнения собственного рабочего процесса при наличии файла go.mod.
3. Запускает go build -o bin/app ., чтобы скомпилировать ваш проект для вашей локальной операционной системы.
4. Запускает узел Функции Azure, который взаимодействует с скомпилируемым двоичным файлом через gRPC.
5. Отображает конечные точки функции (например, http://localhost:7071/api/hello).

Используется local.settings.json для настройки переменных среды для локальной разработки:

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

Значение AzureWebJobsStorage, созданное для проектов Go, пусто. Установите для него значение строки подключения учетной записи хранения или UseDevelopmentStorage=true, если при локальной разработке вы используете триггеры, которым требуется хранилище узла.

Развертывание

Компиляция и упаковка

Функции Azure Core Tools, начиная с версии 4.12 , поддерживают сборку Go в типичных сценариях локального развертывания и развертывания в Azure:

• func start собирает ваш проект в исполняемый файл bin/app для вашей локальной операционной системы перед запуском локального узла Functions.
• func azure functionapp publish собирает, упаковывает и развертывает ваш проект в существующее приложение-функцию в Azure.
• func pack создает проект в виде bin/app для Linux x64 и создает развернутый пакет .zip.

При упаковке для Azure созданный .zip-файл содержит файлы, необходимые узлу Функций Linux. Скомпилированный двоичный файл хранится в виде bin/app в локальном проекте, но основные инструменты помещает его в корень пакета развертывания в качестве приложения.

Если используется func pack --no-build, перед упаковкой необходимо создать двоичный файл Linux x64:

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

Развертывание с помощью Core Tools

Используйте 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 Go поддерживает структурированное ведение журнала и наблюдаемость на основе OpenTelemetry. Используйте методы с учетом контекста из стандартного log/slog пакета, например slog.InfoContextдля сопоставления журналов с текущим вызовом функции. Чтобы включить OpenTelemetry, настройте среду выполнения Functions и зарегистрируйте в приложении промежуточное ПО OpenTelemetry для обработчика Go. Инструкции по настройке см. в разделе Use OpenTelemetry с Функции Azure.

Известные ограничения (предварительная версия)

Во время общедоступной предварительной версии применяются следующие ограничения:

• func new не поддерживается. Добавление функций путем непосредственного редактирования main.go .
• Устойчивые функции не поддерживается для Go во время общедоступной предварительной версии.
• Приложения-функции Go выполняются только в Linux в Azure.
• Во время предварительной версии поддерживаются только триггеры, перечисленные в триггерах .
• Упаковка Go-приложений в Core Tools в настоящее время ориентирована на 64-разрядные приложения Linux.

Дальнейшие действия

• Создание первой функции Go
• Функции Azure triggers and bindings (Триггеры и привязки в Функциях Azure)
• Используйте OpenTelemetry с Функции Azure
• Примеры обработчика Go для Функции Azure
• Руководство разработчиков Функций Azure