Azure İşlevleri özel işleyicileri

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 konak işleminden olayları alan basit web sunucularıdır. HTTP temel öğelerini destekleyen tüm kod projelerini Azure İşlevleri'ne dağıtmak için özel işleyiciler kullanabilirsiniz.

Özel işleyiciler, şu durumlarda en uygun olanlardır:

• Şu anda kullanıma hazır olarak sunulmayan Go veya Rust gibi 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'ne dağıtın.

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

Go ve Rust'ta hızlı başlangıçlarla Azure İşlevleri özel işleyicileri kullanmaya 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'nin desteklediği 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ının host.json, local.settings.json ve function.json dosyalarını birkaç kurala göre yapılandırması gerekir.

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

Özel işleyiciler, Azure İşlevleri'nde 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'da barındırmak için basit ve kolaylaştırılmış bir deneyim sağlar. Daha fazla bilgi için bkz: Azure İşlevleri üzerinde kendi barındırılan uzak MCP sunucusu.

Not

Resmi MCP SDK'larını kullanarak oluşturduğunuz Azure İşlevleri'nin MCP sunucularını barındırma özelliğ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"
    }
  }
}

bölümü tarafından customHandlerdefaultExecutablePathtanı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 arguments bağımsız değişken geçirmek için 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. Bunun yerine Azure'da uygulama ayarlarını kullanın.

Özel işleyiciler için local.settings.jsonFUNCTIONS_WORKER_RUNTIMEayarlayın Custom.

{
  "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	function.jsonbindingstarafı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	Çıktı function.json dosyasında olduğu gibi $returnyapı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

HTTP olaylarını almayı destekleyen herhangi bir dilde özel işleyiciler uygulayabilirsiniz. Aşağıdaki örneklerde, Go programlama dilini kullanarak özel işleyicinin nasıl uygulandığı gösterilmektedir.

Bağlamaları 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.

sipariş/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, şekilde yapılandırılır.

{
  "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şlevi yolunda /ordertanımlanır. Konak, özel işleyiciye yolunda /orderbir 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ı, üyenin Outputs anahtarların function.json dosyasında tanımlandığı şekilde çıkışlarla eşleştiği bir JSON değeri tuttuğu anahtar/değer çiftleri halinde 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
}

Çıktıyı message istekten gelen sipariş verilerine eşit olarak ayarlayarak işlev, verileri yapılandırılan kuyruğa sipariş eden çıkışlar oluşturur. İşlevler ana bilgisayarı, içinde yapılandırılan res HTTP yanıtını da çağırana 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'ne 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 ara sunucu 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 Uygulaması Hizmetinde ç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, veya hello kabul eden adlı GET bir POST 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": "anonymous",
      "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ünde, host.json dosyası çalıştırılacak handler.exe şekilde yapılandırılır ve enableProxyingHttpRequest olarak trueayarlanı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 bir dize döndürülerek işlenir ve POST istekler istek gövdesine erişebilir.

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ğıtılıyor

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.

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

Azure İşlevleri Çekirdek Araçları'nı 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. GitHub deposu özel işleyici örnekleri.

Sorun giderme ve destek

İzleme günlüğü

Ö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.jsonlogLevelayarı logging 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, günlük iletilerini görüntülemek için Application Insights izlemelerini sorgulayın. 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.

Özel işleyiciyi yalıtarak 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ında barındırılan özel bir 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ıyla Go veya Rust'ta bir Azure İşlevleri uygulaması oluşturmaya başlayın.