دالات Azure Go developer reference

مهم

دعم Go ل دالات Azure حاليا في المعاينة العامة. أثناء المعاينة، تدعم تطبيقات وظائف Go فقط على خطة Flex Consumption.

دالات Azure هو خدمة حوسبة بدون خادم يمكنك استخدامها لتشغيل كود مبني على الأحداث دون الحاجة إلى توفير أو إدارة البنية التحتية. يمكن عامل Go من كتابة دالات Azure بشكل أصلي في Go، مع تكامل عميق في نظام دالات Azure Trigger.

يساعدك هذا الدليل:

• فهم نموذج برمجة 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)
}

تسجيل الوظائف

قم بتسجيل وظائف باستخدام واجهة برمجة تطبيقات البناء السليمة مع نمط الخيارات الوظيفية. كل نوع من المشغلات له طريقة تسجيل على الكائن 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"),
)

هيكل Project

مشروع Code 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. لمزيد من المعلومات، راجع ملف الإعدادات المحلية.

المشغلات

ينظم عامل جو المحفزات إلى مستويين بناء على متطلبات الاعتماد الخاصة به:

المحفزات الأساسية

تستقبل المحفزات الأساسية حمولتها المتصلة عبر gRPC. يقوم مضيف دالات Azure بتسلسل بيانات المشغلة إلى رسالة gRPC، بينما يقوم العامل بإلغاء تسلسلها إلى هياكل Go المكتوبة. هذه المحفزات لها:

• توقيعات المعالج المكتوبة مع أمان وقت الترجمة
• لا توجد تبعيات Azure SDK خارجية: فقط encoding/json مطلوب
• الحمولات المحدودة: مستندات ورسائل وأحداث تغذية التغيير هي كائنات منفصلة محدودة الحجم

المحفزات الأساسية المدعومة:

Trigger	توقيع المعالج	طريقة التسجيل
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
ناقل خدمة Azure (Queue)	ServiceBusHandler	app.ServiceBusQueue()
ناقل خدمة Azure (Topic)	ServiceBusHandler	app.ServiceBusTopic()
مراكز الأحداث	EventHubHandler	app.EventHub()
شبكة الأحداث	EventGridHandler	app.EventGrid()

محفزات الامتداد

توفر مشغلات الامتدادات عميل Azure SDK مصدق بدلا من البيانات الخام. يرسل المضيف فقط بيانات وصفية (مثل اسم الحاوية ومسار الكتلة الصغيرة)، ويقوم العامل ببناء عميل مرتبط بالمورد المحدد. هذه المحفزات لها:

• حقن عميل SDK: يتلقى المعالج عميلا جاهزا للاستخدام
• الاعتماديات المعزولة: حزم Azure SDK موجودة في triggers/<name>/
• دعم البث: يتيح قراءة الحمولات الكبيرة دون الحاجة إلى التخزين المؤقت عبر gRPC

لاستخدام مشغل الامتداد، أضف استيرادا فارغا لحزمة الإضافة:

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

Trigger	هاندلر يستلم	طريقة التسجيل
مخزن البيانات الثنائية الكبيرة	*blob.Client	app.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()
    }
}

مشغل المؤقت

تعمل محفزات المؤقت على جدول محدد بتعبير الكرون:

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 Code تستخدم وحدات Go القياسية لإدارة الاعتماديات.

1. تهيئة وحدة جديدة:

   go mod init myapp
   

2. Add the دالات Azure Go worker SDK:

   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 لنظام التشغيل المحلي قبل بدء مضيف الوظائف المحلي.
• func azure functionapp publish يبني ويجمع وينشر مشروعك على تطبيق وظائف موجود في Azure.
• func pack يبني مشروعك كصندوق/تطبيق لنظام Linux x64 وينشئ حزمة .zip قابلة للنشر.

عند التغليف ل Azure، يحتوي ملف .zip المولد على الملفات المطلوبة من قبل مضيف وظائف لينكس. يتم تخزين الملف الثنائي المترجم كصويب/تطبيق في مشروعك المحلي، لكن Core Tools يضعه في جذر حزمة النشر كتطبيق.

إذا كنت تستخدم func pack --no-build، يجب عليك بناء ملف لينكس 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، لذا لا تطلب نسخة بعيدة عند نشرها.

دعم دوكر

يمكنك تشغيل مشاريع Go Code في الحاويات. تهيئة مشروع بدعم دوكر:

func init --worker-runtime go --docker

يقوم الأمر بتوليد ملف مع Dockerfile ملفات المشروع القياسية.

القياس عن بعد والقابلية للرصد

يدعم عامل دالات Azure Go التسجيل المنظم والملاحظة المعتمدة على OpenTelemetry. استخدم الطرق الواعية للسياق من الحزمة القياسية log/slog ، مثل slog.InfoContext، لربط السجلات مع استدعاء الدالة الحالي. لتفعيل OpenTelemetry، قم بتكوين مضيف الوظائف وسجل برنامج الوسيط OpenTelemetry الخاص ب Go worker في تطبيقك. للحصول على تعليمات الإعداد، انظر استخدم OpenTelemetry مع دالات Azure.

القيود المعروفة (المعاينة)

خلال المعاينة العامة، تنطبق القيود التالية:

• لا يتم دعم func new. أضف وظائف عن طريق التحرير main.go المباشر.
• Durable Functions غير مدعوم في Go أثناء المعاينة العامة.
• تطبيقات الوظائف التي تعمل على لينكس فقط في Azure.
• فقط المحفزات المدرجة في المحفزات مدعومة أثناء المعاينة.
• تغليف Go في Core Tools يستهدف حاليا تطبيقات Linux x64.

الخطوات التالية

• أنشئ أول وظيفة Go لك
• مشغلات وعمليات الربط في دالات Azure
• استخدم OpenTelemetry مع دالات Azure
• دالات Azure اذهب عينات العمال
• دالات Azure دليل المطورين