Azure İşlevleri Go geliştirici başvuru kılavuzu

Important

Azure İşlevleri için git desteği şu anda genel önizleme aşamasındadır. Önizleme sırasında Go işlev uygulamaları yalnızca Flex Consumption planında desteklenir.

Azure İşlevleri, altyapıyı sağlamadan veya yönetmeden olay temelli kodu çalıştırmak için kullanabileceğiniz sunucusuz bir işlem hizmetidir. Go worker’ı, Azure İşlevleri tetikleyici ekosistemiyle derin entegrasyon sayesinde Azure İşlevleri’ı doğrudan Go’da geliştirmenizi sağlar.

Bu kılavuz size yardımcı olur:

• Go programlama modelini anlama
• Proje kodunuzu oluşturma ve yapılandırma
• Tetikleyicilerle çalışma
• Uygulamanızı yerel olarak ve Azure dağıtma ve çalıştırma

Genel olarak Azure İşlevleri geliştirme hakkında daha fazla bilgi edinmek için bkz. Azure İşlevleri geliştirici başvurusu.

Başlangıç Yapmak

İş akışınıza uygun ortamı seçin ve Go için Azure İşlevleri kullanmaya başlayın:

• Komut satırı hızlı başlangıcı

Prerequisites

• 1.24 veya sonraki bir sürüme git
• Azure İşlevleri Core Tools sürüm 4.12 veya üzeri. Yüklü sürümünüzü doğrulamak için komutunu çalıştırın func --version .
• Azure CLI sürüm 2.87.0 veya üzeri, Azure kaynakları oluşturduğunuzda veya paketleri Azure dağıttığınızda. Yüklü sürümünüzü doğrulamak için komutunu çalıştırın az version .

Programlama modeli

Go çalışanı, kod öncelikli bir programlama modeli kullanır. Sunucusuz işlevleri ve tetikleyicilerini idiomatic Go işleyicilerini kullanarak tanımlarsınız.

Giriş noktası

Her Go kod projesi, bir main() oluşturan, fonksiyonları kaydeden ve çalışanı başlatan bir FunctionApp fonksiyonuyla başlar:

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

İşlev kaydı

İşlevsel seçenekler deseniyle akıcı oluşturucu API'sini kullanarak işlevleri kaydedin. Her tetikleyici türü için, App nesnesi üzerinde bir kayıt yöntemi bulunur:

// 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"),
)

Proje yapısı

Azure İşlevleri için Go kod projesi standart bir Go modülüdür. komutunu çalıştırdığınızda func init --worker-runtime goaşağıdaki dosyalar oluşturulur:

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

Dosya konak host.json düzeyinde yapılandırma seçeneklerini içerir. Daha fazla bilgi için host.json başvurusuna bakın.

local.settings.json

Dosya, local.settings.json yerel geliştirme sırasında kullanılan uygulama ayarlarını ve bağlantı dizelerini depolar. Bu dosya Azure yayımlanmaz. Daha fazla bilgi için bkz . Yerel ayarlar dosyası.

Tetikleyiciler

Go çalışanı, bağımlılık gereksinimlerine göre tetikleyicileri iki katman halinde düzenler:

Çekirdek tetikleyicileri

Çekirdek tetikleyiciler, yük verilerini gRPC aracılığıyla doğrudan alır. Azure İşlevleri ana bilgisayarı tetikleyici verilerini gRPC iletisine serileştirir ve çalışan bunu türlendirilmiş Go struct’larına seri durumdan çıkarır. Bu tetikleyiciler şunlara sahiptir:

• Derleme zamanı güvenliğine sahip yazılan işleyici imzaları
• Harici Azure SDK bağımlılıkları yok: yalnızca encoding/json gereklidir
• Sınırlanmış yükler: değişiklik akışı belgeleri, iletileri ve olayları ayrık, boyutu sınırlı nesnelerdir

Desteklenen çekirdek tetikleyiciler:

Trigger	İşleyici imzası	Kayıt yöntemi
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB veritabanı	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus (Kuyruk)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (Konu Başlığı)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Uzantı tetikleyicileri

Uzantı tetikleyicileri ham veriler yerine kimliği doğrulanmış bir Azure SDK istemcisi sağlar. Ana bilgisayar yalnızca meta verileri (kapsayıcı adı ve blob yolu gibi) gönderir ve çalışan, belirli kaynağa yönelik bir istemci oluşturur. Bu tetikleyiciler şunlara sahiptir:

• SDK istemci ekleme: işleyici kullanıma hazır bir istemci alır
• Yalıtılmış bağımlılıklar: Azure SDK paketleri triggers/<name>/
• Akış desteği: gRPC aracılığıyla arabelleğe almadan büyük yüklerin okunmasını sağlar

Bir uzantı tetikleyicisi kullanmak için, uzantı paketi için boş bir içe aktarma ekleyin:

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

Trigger	İşleyici alır	Kayıt yöntemi
Blob Depolama	*blob.Client	app.Blob()

Blob tetikleyici örneği

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 tetikleyicileri

HTTP tetikleyici işleyicileri standart Go net/http türlerini kullanarak Go geliştiricilerine hemen alışmalarını sağlar:

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 işlevlerini yöntemlerle ve yetkilendirme düzeyiyle kaydedin:

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

HTTP akışı

Go çalışanı, sunucu tarafından gönderilen olaylar veya büyük yanıt verileri gönderme gibi senaryolar için HTTP akışını destekler:

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()
    }
}

Zamanlayıcı tetikleyicisi

Zamanlayıcı tetikleyicileri, bir cron ifadesi tarafından tanımlanan bir zamanlamaya göre çalışır:

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
}

Bağımlılık yönetimi

Go kod projeleri bağımlılık yönetimi için standart Go modüllerini kullanır.

1. Yeni bir modül başlatın:

   go mod init myapp
   

2. Azure İşlevleri Go çalışan SDK'sını ekleyin:

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

   Blob tetikleyicisi desteği için bağımlılık, triggers/blob öğesinin boş içe aktarımı aracılığıyla otomatik olarak eklenir.

3. Düzenli bağımlılıklar:

   go mod tidy
   

Yerel çalıştır

Projenizi yerel olarak çalıştırmak için Azure İşlevleri Temel Araçları'nı kullanın:

func start

Core Tools otomatik olarak:

1. FUNCTIONS_WORKER_RUNTIME = "native" içinden local.settings.json algılar.
2. Bir go.mod dosya mevcut olduğunda yerel çalışan çalışma zamanını Go olarak çözümler.
3. Projenizi yerel işletim sisteminiz için derlemek için çalışır go build -o bin/app . .
4. gRPC üzerinden derlenmiş ikili dosyayla iletişim kuran Azure İşlevleri ana bilgisayarını başlatır.
5. İşlev uç noktalarınızı görüntüler (örneğin, http://localhost:7071/api/hello).

Yerel geliştirme için ortam değişkenlerini yapılandırmak için kullanın local.settings.json :

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

Oluşturulan AzureWebJobsStorage değer Go projeleri için boş. Yerel geliştirme sırasında konak depolaması gerektiren tetikleyiciler kullandığınızda bunu bir depolama hesabı bağlantı dizesine veya UseDevelopmentStorage=true değerine ayarlayın.

Deployment

Derleme ve paketleme

Azure İşlevleri Core Tools sürüm 4.12 veya üzeri, yaygın yerel ve Azure dağıtım akışları için Go derlemelerini işler:

• func start yerel İşlevler ana bilgisayarını başlatmadan önce projenizi yerel işletim sisteminiz için bin/app olarak oluşturur.
• func azure functionapp publish projenizi Azure'daki mevcut bir işlev uygulamasına derler, paketler ve dağıtır.
• func pack projenizi Linux x64 için bin/app olarak oluşturur ve dağıtılabilir bir .zip paketi oluşturur.

Azure için paketleme yaparken, oluşturulan .zip dosyası Linux İşlevleri konağı tarafından gereken dosyaları içerir. Derlenen ikili dosya yerel projenizde bin/app olarak depolanır, ancak Core Tools bunu dağıtım paketinin köküne uygulama olarak yerleştirir.

kullanıyorsanız func pack --no-build, paketlemeden önce Linux x64 ikili dosyasını oluşturmanız gerekir:

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

Core Tools ile dağıtın

Go projenizi Azure'daki mevcut bir işlev uygulamasına dağıtmak için func azure functionapp publish kullanın:

func azure functionapp publish <APP_NAME>

<APP_NAME> değerini işlev uygulamanızın adıyla değiştirin.

Zip paketi dağıtma

Yayımlamadan ayrı bir dağıtım paketi oluşturmanız gerektiğinde kullanın func pack :

1. Dağıtılabilir zip yapıtı oluşturma:

   func pack
   

2. Azure CLI kullanarak paketi dağıtın:

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

func pack tarafından üretilen paket Azure'da çalışmaya hazırdır, bu nedenle dağıttığınızda uzak derleme isteğinde bulunmayın.

Docker desteği

Go kod projelerini kapsayıcılarda çalıştırabilirsiniz. Docker desteğiyle bir proje başlatın:

func init --worker-runtime go --docker

komutu, standart proje dosyalarıyla birlikte bir Dockerfile oluşturur.

Telemetri ve gözlemlenebilirlik

Azure İşlevleri Go çalışanı, yapılandırılmış günlükleme ve OpenTelemetry tabanlı gözlemlenebilirliği destekler. Günlükleri mevcut fonksiyon çağrısıyla ilişkilendirmek için standart log/slog paketindeki slog.InfoContext gibi bağlama duyarlı yöntemleri kullanın. OpenTelemetry'yi etkinleştirmek için İşlevler ana bilgisayarını yapılandırın ve Go çalışanı OpenTelemetry ara yazılımını uygulamanıza kaydedin. Kurulum yönergeleri için bkz. Azure İşlevleri ile OpenTelemetry kullanma.

Bilinen sınırlamalar (önizleme)

Genel önizleme sırasında aşağıdaki sınırlamalar geçerlidir:

• func new desteklenmez. main.go öğesini doğrudan düzenleyerek işlevler ekleyin.
• genel önizleme sırasında Go için Dayanıklı İşlevler desteklenmez.
• Go işlev uygulamaları yalnızca Azure Linux üzerinde çalışır.
• Önizleme sırasında yalnızca Tetikleyiciler'de listelenen tetikleyiciler desteklenir.
• Core Tools’da Go paketleme şu anda Linux x64 uygulamalarını hedefler.

Sonraki Adımlar

• İlk Go işlevinizi oluşturma
• Azure İşlevleri tetikleyicileri ve bağlamaları
• Azure İşlevler ile OpenTelemetry'yi Kullanma
• Azure İşlevleri Go çalışan örnekleri
• Azure İşlevleri geliştirici kılavuzu