Azure İşlevleri özel işleyiciler

Tip

Go mu arıyorsunuz? Go artık Azure İşlevleri(genel önizleme) üzerinde birinci sınıf dil olarak destekleniyor. Başlamak için Go geliştirici referansına ve Go hızlı başlangıç kılavuzuna göz atın.

Azure İşlevleri, dile özgü işleyicileri kullanarak uygulama kodunuzu yürütür. Bu dile özgü işleyiciler, İşlevler'in varsayılan olarak çoğu anahtar dili desteklemesine olanak sağlar. Ancak kodu başka bir dilde veya pakette çalıştırmanız gerekebilir.

Özel işleyiciler, Azure İşlevleri ana bilgisayar sürecinden olayları alan hafif web sunucularıdır. HTTP temel öğelerini destekleyen herhangi bir kod projesine Azure İşlevleri dağıtmak için özel işleyiciler kullanabilirsiniz.

Özel işleyiciler, şu durumlarda en iyi şekilde kullanılabilir:

• Rust gibi kullanıma hazır olarak sunulmayan bir dilde işlev uygulaması uygulayın.
• Deno gibi varsayılan olarak öne çıkarılmayan bir çalışma zamanında işlev uygulaması uygulayın.
• Standart MCP SDK'ları ile oluşturulmuş bir sunucuyu Azure İşlevleri'a dağıtın.

Özel işleyicilerle, uzantı paketleri aracılığıyla tetikleyicileri ve giriş ve çıkış bağlamalarını kullanabilirsiniz.

Rust ile hızlı başlangıçlarla Azure İşlevleri özel işleyicileriyle çalışmaya başlayın.

Genel bakış

Aşağıdaki diyagramda İşlevler konağı ile özel işleyici olarak uygulanan bir web sunucusu arasındaki ilişki gösterilmektedir.

1. Her olay İşlevler konağına gönderilen bir isteği tetikler. Olay, Azure İşlevleri tarafından desteklenen herhangi bir tetikleyicidir.
2. İşlevler ana bilgisayarı daha sonra web sunucusuna bir istek yükü gönderir. Yük, işlev için tetikleyici ve giriş bağlama verilerini ve diğer meta verileri tutar.
3. Web sunucusu tek tek işlevi yürütür ve İşlevler konağına bir yanıt yükü döndürür.
4. İşlevler konağı, yanıttan verileri işleme için işlevin çıkış bağlamalarına geçirir.

Özel işleyici olarak uygulanan bir Azure İşlevleri uygulaması host.json, local.settings.json ve function.json dosyalarını birkaç kurala göre yapılandırmalıdır.

Şirket içinde barındırılan MCP sunucularını dağıtın.

Özel işleyiciler, Azure İşlevleri'de resmi MCP SDK'larını kullanarak oluşturduğunuz MCP sunucularını barındırmanıza da olanak tanır. Özel işleyiciler, MCP sunucularınızı Azure barındırmak için basit ve kolaylaştırılmış bir deneyim sağlar. Daha fazla bilgi için Azure İşlevleri üzerinde kendi kendine barındırılan uzak MCP sunucusu bölümüne bakın.

Not

Azure İşlevleri'ın, resmi MCP SDK'larını kullanarak oluşturduğunuz MCP sunucularını barındırma yeteneği şu anda önizleme aşamasındadır.

Uygulama yapısı

Özel işleyici uygulamak için uygulamanızın aşağıdaki yönlerine ihtiyacı vardır:

• Uygulamanızın kökünde bir host.json dosyası
• Uygulamanızın kökünde bir local.settings.json dosyası
• Her işlev için bir function.json dosyası (işlev adıyla eşleşen bir klasörün içinde)
• Web sunucusu çalıştıran bir komut, betik veya yürütülebilir dosya

Aşağıdaki diyagramda, bu dosyaların "MyQueueFunction" adlı bir işlev ve handler.exe adlı özel işleyici yürütülebilir dosyası için dosya sisteminde nasıl göründüğü gösterilmektedir.

| /MyQueueFunction
|   function.json
|
| host.json
| local.settings.json
| handler.exe

Yapılandırma

Uygulamayı host.json ve local.settings.json dosyaları aracılığıyla yapılandırabilirsiniz.

host.json

host.json , http olaylarını işleyebilen bir web sunucusuna işaret ederek İşlevler ana bilgisayarını isteklerin gönderileceği yere yönlendirir.

host.json dosyasındaki customHandler bölümünü kullanarak web sunucusunun nasıl çalıştırılacağını belirten ayrıntılarla yapılandırarak özel bir işleyici tanımlayın.

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.exe"
    }
  }
}

customHandler bölümü, defaultExecutablePath tarafından tanımlanan bir hedefi gösterir. Yürütme hedefi, web sunucusunun uygulandığı bir komut, yürütülebilir dosya veya dosya olabilir.

Yürütülebilir dosyaya bağımsız değişkenleri geçirmek için arguments dizisini kullanın. Bağımsız değişkenler, %% gösterimini kullanarak ortam değişkenlerinin (uygulama ayarları) genişletilmesini destekler.

ile yürütülebilir dosya workingDirectorytarafından kullanılan çalışma dizinini de değiştirebilirsiniz.

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "app/handler.exe",
      "arguments": [
        "--database-connection-string",
        "%DATABASE_CONNECTION_STRING%"
      ],
      "workingDirectory": "app"
    }
  }
}

Bağlama desteği

Standart tetikleyiciler ve giriş ve çıkış bağlamaları, host.json dosyanızdaki uzantı paketlerine başvurarak kullanılabilir.

local.settings.json

local.settings.json, işlev uygulamasını yerel olarak çalıştırırken kullanılan uygulama ayarlarını tanımlar. Gizli bilgiler içerebileceğinden local.settings.json dosyasını kaynak kontrolünden çıkartın. Azure yerine uygulama ayarlarını kullanın.

Özel işleyiciler için, local.settings.json dosyasında FUNCTIONS_WORKER_RUNTIME değerini Custom olarak ayarlayın.

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "Custom"
  }
}

İşlev meta verileri

Özel işleyici kullandığınızda ,function.json içeriği başka bir bağlamda işlev tanımladığınızla aynıdır. Tek gereksinim, function.json dosyaları işlev adıyla eşleşecek şekilde adlı bir klasöre yerleştirmeniz gerektiğidir.

Aşağıdaki function.json kuyruk tetikleyicisi ve kuyruk çıkış bağlaması olan bir işlevi yapılandırır. MyQueueFunction adlı bir klasörde olduğundan MyQueueFunction adlı bir işlev tanımlar.

MyQueueFunction/function.json

{
  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages-incoming",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "$return",
      "type": "queue",
      "direction": "out",
      "queueName": "messages-outgoing",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

İstek yükü

İşlevler konağı bir kuyruk iletisi aldığında, içinde yük bulunan bir HTTP gönderi isteğini özel işleyiciye gönderir.

Aşağıdaki kodda örnek istek yükü gösterilmektedir. Yük, iki üyeye sahip bir JSON yapısı içerir: Data ve Metadata.

Üye, Data function.json dosyasındaki bağlamalar dizisinde tanımlanan giriş ve tetikleyici adlarıyla eşleşen anahtarlar içerir.

Üye, Metadata olay kaynağından oluşturulan meta verileri içerir.

{
  "Data": {
    "myQueueItem": "{ message: \"Message sent\" }"
  },
  "Metadata": {
    "DequeueCount": 1,
    "ExpirationTime": "2019-10-16T17:58:31+00:00",
    "Id": "800ae4b3-bdd2-4c08-badd-f08e5a34b865",
    "InsertionTime": "2019-10-09T17:58:31+00:00",
    "NextVisibleTime": "2019-10-09T18:08:32+00:00",
    "PopReceipt": "AgAAAAMAAAAAAAAAAgtnj8x+1QE=",
    "sys": {
      "MethodName": "QueueTrigger",
      "UtcNow": "2019-10-09T17:58:32.2205399Z",
      "RandGuid": "24ad4c06-24ad-4e5b-8294-3da9714877e9"
    }
  }
}

Yanıt yükü

Kural gereği işlev yanıtları anahtar/değer çiftleri olarak biçimlendirilir. Desteklenen anahtarlar şunlardır:

Yük anahtarı	Veri türü	Açıklamalar
Outputs	nesne	dizisinde function.json tarafından tanımlanan yanıt değerlerini tutar. Örneğin, bir işlev "myQueueOutput" adlı bir kuyruk çıkış bağlamasıyla yapılandırılmışsa, Outputs özel işleyicinin kuyruğa gönderdiği iletilere ayarladığı adlı myQueueOutputbir anahtar içerir.
Logs	dizi	İşlev çağırma günlüklerinde görünen iletiler. Azure'da çalışırken, iletiler Application Insights'ta görünür.
ReturnValue	Dize	Bir çıktı $return olarak function.json dosyasında yapılandırıldığında yanıt sağlamak için kullanılır.

Bu tabloda yanıt yükü örneği gösterilmektedir.

{
  "Outputs": {
    "res": {
      "body": "Message enqueued"
    },
    "myQueueOutput": [
      "queue message 1",
      "queue message 2"
    ]
  },
  "Logs": [
    "Log message 1",
    "Log message 2"
  ],
  "ReturnValue": "{\"hello\":\"world\"}"
}

Örnekler

Önemli

Go ile yazılmış yeni Azure İşlevleri uygulamaları için özel işleyiciler yerine birinci sınıf Go desteğini kullanın. Go Geliştirici Referansı'na ve Go Hızlı Başlangıç Kılavuzu'na bakın.

HTTP olaylarını almayı destekleyen herhangi bir dilde özel işleyiciler uygulayabilirsiniz. Aşağıdaki örneklerde, yalnızca yerleşik Azure İşlevleri desteği olmayan diller veya çalışma zamanları için özel işleyici protokollerini göstermek için Go kullanılır.

Bağlantıları olan işlev

Bu örnekte, bir ürün siparişini temsil eden yükü olan bir order isteği kabul eden adlı POST bir işlev gösterilmektedir. İşleve bir sipariş gönderdiğinizde, bir Kuyruk Depolama iletisi oluşturur ve bir HTTP yanıtı döndürür.

Uygulama

order adlı bir klasörde function.json dosyası HTTP ile tetiklenen işlevi yapılandırıyor.

order/function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "queue",
      "name": "message",
      "direction": "out",
      "queueName": "orders",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Bu işlev, HTTP yanıtı döndüren ve Kuyruk depolama iletisi veren HTTP ile tetiklenen bir işlev olarak tanımlanır.

Uygulamanın kökünde, host.json dosyası, handler.exe adlı yürütülebilir bir dosyayı çalıştıracak şekilde yapılandırılmıştır (handler Linux veya macOS'ta).

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.exe"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

bu, İşlevler çalışma zamanına gönderilen HTTP isteğidir.

POST http://127.0.0.1:7071/api/order HTTP/1.1
Content-Type: application/json

{
  "id": 1005,
  "quantity": 2,
  "color": "black"
}

İşlevler çalışma zamanı, özel işleyiciye aşağıdaki HTTP isteğini gönderir:

POST http://127.0.0.1:<FUNCTIONS_CUSTOMHANDLER_PORT>/order HTTP/1.1
Content-Type: application/json

{
  "Data": {
    "req": {
      "Url": "http://localhost:7071/api/order",
      "Method": "POST",
      "Query": "{}",
      "Headers": {
        "Content-Type": [
          "application/json"
        ]
      },
      "Params": {},
      "Body": "{\"id\":1005,\"quantity\":2,\"color\":\"black\"}"
    }
  },
  "Metadata": {
  }
}

Not

Yükün bazı bölümleri kısa bir süre için kaldırıldı.

handler.exe, bir web sunucusu çalıştıran ve İşlevler ana bilgisayarından işlev çağırma isteklerine yanıt veren derlenmiş Go özel işleyici programıdır.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

type InvokeRequest struct {
	Data     map[string]json.RawMessage
	Metadata map[string]interface{}
}

type InvokeResponse struct {
	Outputs     map[string]interface{}
	Logs        []string
	ReturnValue interface{}
}

func orderHandler(w http.ResponseWriter, r *http.Request) {
	var invokeRequest InvokeRequest

	d := json.NewDecoder(r.Body)
	d.Decode(&invokeRequest)

	var reqData map[string]interface{}
	json.Unmarshal(invokeRequest.Data["req"], &reqData)

	outputs := make(map[string]interface{})
	outputs["message"] = reqData["Body"]

	resData := make(map[string]interface{})
	resData["body"] = "Order enqueued"
	outputs["res"] = resData
	invokeResponse := InvokeResponse{outputs, nil, nil}

	responseJson, _ := json.Marshal(invokeResponse)

	w.Header().Set("Content-Type", "application/json")
	w.Write(responseJson)
}

func main() {
	customHandlerPort, exists := os.LookupEnv("FUNCTIONS_CUSTOMHANDLER_PORT")
	if !exists {
		customHandlerPort = "8080"
	}
	mux := http.NewServeMux()
	mux.HandleFunc("/order", orderHandler)
	fmt.Println("Go server Listening on: ", customHandlerPort)
	log.Fatal(http.ListenAndServe(":"+customHandlerPort, mux))
}

Bu örnekte, özel işleyici HTTP olaylarını işlemek için bir web sunucusu çalıştırır ve aracılığıyla FUNCTIONS_CUSTOMHANDLER_PORTistekleri dinler.

İşlev ana bilgisayarı /api/order konumunda orijinal HTTP isteğini alsa da, işlev adını (klasör adı) kullanarak özel işleyiciyi çağırır. Bu örnekte, işlev /order yolunda tanımlanır. Sunucu, özel işleyiciye /order yolunda bir HTTP isteği gönderir.

Bu işleve istek gönderdiğinizde POST , tetikleyici verileri ve işlev meta verileri HTTP istek gövdesi aracılığıyla kullanılabilir. Yükün Data.req.Body içindeki orijinal HTTP isteği gövdesine erişebilirsiniz.

İşlevin yanıtı, Outputs üyesinin bir JSON değerini tuttuğu ve buradaki anahtarların function.json dosyasında tanımlanan çıkışlarla eşleştiği anahtar/değer çiftleri şeklinde biçimlendirilir.

Bu, bu işleyicinin İşlevler konağına döndürdüğü örnek bir yükdür.

{
  "Outputs": {
    "message": "{\"id\":1005,\"quantity\":2,\"color\":\"black\"}",
    "res": {
      "body": "Order enqueued"
    }
  },
  "Logs": null,
  "ReturnValue": null
}

İsteğe gelen sipariş verilerine eşit olacak şekilde message çıktısını ayarlayarak, işlev bu sipariş verilerini yapılandırılan kuyruğa gönderir. İşlev ana bilgisayarı, HTTP yanıtını res içinde yapılandırılan şekilde çağırana da döndürür.

Yalnızca HTTP işlevi

Ek bağlamaları veya çıkışları olmayan HTTP ile tetiklenen işlevler için, işleyicinizin özel işleyici isteği ve yanıt yükleri yerine doğrudan HTTP isteği ve yanıtıyla çalışmasını isteyebilirsiniz. host.json dosyasında, yanıt akışını destekleyen enableProxyingHttpRequest ayarını kullanarak bu davranışı yapılandırabilirsiniz.

Önemli

Özel işleyiciler özelliğinin birincil amacı, şu anda Azure İşlevleri'de birinci sınıf desteği olmayan dilleri ve çalışma zamanlarını etkinleştirmektir. Özel işleyicileri kullanarak web uygulamaları çalıştırabilirsiniz ancak Azure İşlevleri standart bir ters proxy değildir. BELIRLI üst bilgiler ve yollar gibi HTTP isteğinin bazı bileşenleri kısıtlanmış olabilir. Uygulamanız da aşırı soğuk başlatmayla karşılaşabilir.

Bu koşulları ele almak için web uygulamalarınızı Azure App Service üzerinde çalıştırmayı göz önünde bulundurun.

Aşağıdaki örnekte ek bağlamalar veya çıkışlar olmadan HTTP ile tetiklenen bir işlevin nasıl yapılandırıldığı gösterilmektedir. Bu örnekte uygulanan senaryo, hello veya GET kabul eden bir POST adlı işlev içerir.

Uygulama

hello adlı klasörde function.json dosyası HTTP ile tetiklenen işlevi yapılandırıyor.

hello/function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "authLevel": "function",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

İşlev, hem GET hem de POST isteklerini kabul edecek şekilde yapılandırılmıştır ve sonuç değeri, res adlı bir bağımsız değişken aracılığıyla sağlanır.

Uygulamanın kök dizininde, host.json dosyası çalıştırılmak üzere handler.exe biçiminde yapılandırılır ve enableProxyingHttpRequest öğesi true olarak ayarlanır.

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.exe"
    },
    "enableProxyingHttpRequest": true
  }
}

aşağıda İşlevler konağına gönderilen bir POST isteği yer alır. İşlevler konağı daha sonra isteği özel işleyiciye gönderir.

POST http://127.0.0.1:7071/api/hello HTTP/1.1
Content-Type: application/json

{
  "message": "Hello World!"
}

handler.go dosyası bir web sunucusu ve HTTP işlevi uygular.

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"os"
)

func helloHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	if r.Method == "GET" {
		w.Write([]byte("hello world"))
	} else {
		body, _ := ioutil.ReadAll(r.Body)
		w.Write(body)
	}
}

func main() {
	customHandlerPort, exists := os.LookupEnv("FUNCTIONS_CUSTOMHANDLER_PORT")
	if !exists {
		customHandlerPort = "8080"
	}
	mux := http.NewServeMux()
	mux.HandleFunc("/api/hello", helloHandler)
	fmt.Println("Go server Listening on: ", customHandlerPort)
	log.Fatal(http.ListenAndServe(":"+customHandlerPort, mux))
}

Bu örnekte, özel işleyici HTTP olaylarını işlemek için bir web sunucusu oluşturur ve aracılığıyla FUNCTIONS_CUSTOMHANDLER_PORTistekleri dinler.

GET istekler dize döndürülerek işlenir ve POST istekler istek gövdesine erişim sağlar.

Buradaki /api/helloorder işlevinin yolu, özgün istekle aynıdır.

Not

FUNCTIONS_CUSTOMHANDLER_PORT işlevi çağırmak için kullanılan genel kullanıma yönelik bağlantı noktası değildir. İşlevler konağı, özel işleyiciyi çağırmak için bu bağlantı noktasını kullanır.

Dağıtma

Her Azure İşlevleri barındırma seçeneğine özel bir işleyici dağıtabilirsiniz. İşleyiciniz işletim sistemi veya platform bağımlılıkları (dil çalışma zamanı gibi) gerektiriyorsa , özel bir kapsayıcı kullanmanız gerekebilir.

özel işleyiciler için Azure bir işlev uygulaması oluşturduğunuzda yığın olarak .NET Core'u seçin.

Azure İşlevleri Core Tools kullanarak özel bir işleyici uygulaması dağıtmak için aşağıdaki komutu çalıştırın.

func azure functionapp publish $functionAppName

Not

Özel işleyicinizi çalıştırmak için gereken tüm dosyaların klasörde olduğundan ve dağıtıma dahil olduğundan emin olun. Özel işleyiciniz ikili yürütülebilir dosyaysa veya platforma özgü bağımlılıklara sahipse, bu dosyaların hedef dağıtım platformuyla eşleştiğinden emin olun.

Kısıtlamalar

• Özel işleyici web sunucusunun 60 saniye içinde başlatılması gerekir.

Örnekler

İşlevleri çeşitli dillerde uygulama örnekleri için bkz. özel işleyici örnekleri GitHub depo.

Sorun giderme ve destek

İzleme kaydı

Özel işleyici işleminiz başlamazsa veya Functions ana bilgisayarı ile iletişimde sorun yaşıyorsa, ana bilgisayardan daha fazla tanılama iletisi görmek için işlev uygulamanızın günlük seviyesini Trace olarak artırın.

İşlev uygulamasının varsayılan günlük düzeyini değiştirmek için host.json dosyasının logLevel bölümündeki logging ayarını yapılandırın.

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.exe"
    }
  },
  "logging": {
    "logLevel": {
      "default": "Trace"
    }
  }
}

İşlevler ana bilgisayarı, özel işleyici süreciyle ilgili bilgiler de dahil olmak üzere, başka ekstra günlük mesajları çıkartır. Özel işleyici işleminizi başlatma veya özel işleyicinizdeki işlevleri çağırma sorunlarını araştırmak için günlükleri kullanın.

Günlükler yerel olarak konsola yazdırılır.

Azure'da Application Insights izlemelerini sorgulayarak günlük iletilerini görmek için. Uygulamanız yüksek hacimli günlükler üretirse Application Insights'a günlük iletilerinin yalnızca bir alt kümesi gönderilir. Tüm iletilerin günlüğe kaydedildiğinden emin olmak için örneklemeyi devre dışı bırakın.

İzole şekilde özel işleyiciyi test edin

Özel işleyici uygulamaları web sunucusu işlemleridir, bu nedenle bunları kendi başlarına başlatmak ve sahte HTTP istekleri göndererek işlev çağrılarını test etmek yararlı olabilir. Yükleri olan HTTP istekleri göndermek için verilerinizin güvenliğini sağlayan bir araç seçtiğinizden emin olun. Daha fazla bilgi için bkz . HTTP test araçları.

Bu stratejiyi, özel işleyicinizde otomatikleştirilmiş testler çalıştırmak için CI/CD işlem hatlarınızda da kullanabilirsiniz.

Yürütme ortamı

Özel işleyiciler, tipik bir Azure İşlevleri uygulamasıyla aynı ortamda çalışır. Ortamın çalışması için gereken tüm bağımlılıkları içerdiğinden emin olmak için işleyicinizi test edin. Ek bağımlılıklar gerektiren uygulamalar için, Azure İşlevleri Premium planı üzerinde barındırılan custom kapsayıcı görüntüsü kullanarak bunları çalıştırmanız gerekebilir.

Destek alın

Özel işleyicileri olan bir işlev uygulamasında yardıma ihtiyacınız varsa, normal destek kanalları aracılığıyla bir istek gönderebilirsiniz. Ancak, özel işleyici uygulamaları oluşturmak için kullanılan çok çeşitli olası diller nedeniyle destek sınırsız değildir.

İşlevler ana bilgisayarında özel işleyici işlemi başlatılırken veya özel işleyici işlemiyle iletişim kurarken sorun yaşanırsa destek sağlanır. Seçilen dil veya çerçeveyle ilgili sorunlar gibi özel işleyici sürecinizin iç çalışmalarına özgü sorunlar için Destek Ekibimiz bu bağlamda yardım sağlayamaz.

Sonraki adımlar

özel işleyiciler hızlı başlangıcı ile Rust'ta Azure İşlevleri uygulaması oluşturmaya başlayın. Go için Go geliştirici başvurusuna bakın.