Aracılığıyla paylaş

Azure İşlevleri özel işleyicileri

  • Makale

Her İşlev uygulaması dile özgü bir işleyici tarafından yürütülür. Azure İşlevleri varsayılan olarak birçok dil işleyicisi olsa da, diğer dilleri veya çalışma zamanlarını kullanmak isteyebileceğiniz durumlar vardır.

Özel işleyiciler, İşlevler konağından olay alan basit web sunucularıdır. HTTP temel öğelerini destekleyen tüm diller özel bir işleyici uygulayabilir.

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

  • Şu anda kullanıma 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.

Ö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.

Azure İşlevleri özel işleyiciye genel bakış

  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ının host.json, local.settings.json ve function.json dosyalarını birkaç kurala göre yapılandırması gerekir.

Uygulama yapısı

Özel işleyici uygulamak için uygulamanızda aşağıdaki yönlere ihtiyacınız 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

Uygulama, host.json ve local.settings.json dosyaları aracılığıyla yapılandırılır.

host.json

host.json, İşlevler konağına HTTP olaylarını işleyebilen bir web sunucusuna işaret ederek isteklerin nereye gönderileceği bildirmektedir.

Özel işleyici, host.json dosyasını bölüm aracılığıyla customHandler web sunucusunun nasıl çalıştırılmasıyla ilgili ayrıntılarla yapılandırarak tanımlanır.

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

bölümü tarafından customHandler defaultExecutablePathtanı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österimi kullanarak %% ortam değişkenlerinin (uygulama ayarları) genişletilmesine destek olur.

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 diziler içerebileceği için local.settings.json kaynak denetiminden dışlanmalıdır. Bunun yerine Azure'da uygulama ayarlarını kullanın.

Özel işleyiciler için local.settings.json olarak ayarlayın Custom FUNCTIONS_WORKER_RUNTIME.

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

İşlev meta verileri

Özel işleyiciyle kullanıldığında, function.json içeriği başka bir bağlam altında işlev tanımlama yönteminizden farklı değildir. Tek gereksinim, function.json dosyalarının işlev adıyla eşleşmesi için adlı bir klasörde bulunması 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ü

Kuyruk iletisi alındığında İşlevler konağı, gövdede yükü olan özel işleyiciye bir HTTP gönderi isteği gönderir.

Aşağıdaki kod örnek istek yükünü temsil eder. 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.json dizi tarafından bindings 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şleyici tarafından kuyruğa gönderilen iletilere ayarlanan adlı myQueueOutputbir anahtar içerir.
Logs dizi İletiler İşlev çağırma günlüklerinde görünür.

Azure'da çalışırken iletiler Application Insights'ta görünür.
ReturnValue Dize Çıktı function.json dosyasında olduğu gibi $return yapılandırıldığında yanıt sağlamak için kullanılır.

Bu bir yanıt yükü örneğidir.

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

Örnekler

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

Bağlamaları olan işlev

Bu örnekte uygulanan senaryo, bir ürün siparişini temsil eden yüke sahip olan öğesini kabul POST eden adlı order bir işlev içerir. İşleve bir sipariş gönderildiğinde, Kuyruk Depolama iletisi oluşturulur ve bir HTTP yanıtı döndürülü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, host.json dosyası (handler Linux veya macOS'ta) adlı handler.exe yürütülebilir dosyayı çalıştıracak şekilde yapılandırılır.

{
  "version": "2.0",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.exe"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.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 dinleyecek şekilde ayarlanır.

İşlevler konağı konumunda /api/orderözgün HTTP isteği almış olsa 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.

İstekler bu işleve gönderildikçe POST , tetikleyici verileri ve işlev meta verileri HTTP istek gövdesi aracılığıyla kullanılabilir. Özgün HTTP isteği gövdesine yükünün Data.req.Bodyiçinde erişilebilir.

İş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. Bu davranış host.json ayarı kullanılarak enableForwardingHttpRequest yapılandırılabilir.

Önemli

Özel işleyiciler özelliğinin birincil amacı, şu anda Azure İşlevleri birinci sınıf desteği olmayan dilleri ve çalışma zamanlarını etkinleştirmektir. Web uygulamalarını özel işleyiciler kullanarak çalıştırmak mümkün olsa da Azure İşlevleri standart bir ters proxy değildir. Yanıt akışı, HTTP/2 ve WebSockets gibi bazı özellikler kullanılamaz. BELIRLI üst bilgiler ve yollar gibi HTTP isteğinin bazı bileşenleri kısıtlanabilir. Uygulamanız aşırı soğuk başlatmayla da 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 POST kabul eden adlı hello bir GET 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"
    }
  ]
}

işlevi hem hem de GET POST isteklerini kabul etmek üzere yapılandırılır ve sonuç değeri adlı resbir 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 enableForwardingHttpRequest olarak trueayarlanır.

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

olduğunda enableForwardingHttpRequest true, yalnızca HTTP işlevlerinin davranışı varsayılan özel işleyici davranışından şu şekilde farklıdır:

  • HTTP isteği, özel işleyiciler istek yükünü içermez. Bunun yerine İşlevler ana bilgisayarı, işleyiciyi özgün HTTP isteğinin bir kopyasıyla çağırır.
  • İşlevler ana bilgisayarı, herhangi bir sorgu dizesi parametresi de dahil olmak üzere özgün istekle aynı yola sahip işleyiciyi çağırır.
  • İşlevler ana bilgisayarı, özgün isteğe yanıt olarak işleyicinin HTTP yanıtının bir kopyasını döndürür.

aşağıda İşlevler konağına gönderilen bir POST isteği yer alır. İşlevler konağı daha sonra isteğin bir kopyasını aynı yoldaki ö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 dinleyecek şekilde ayarlanır.

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. Bu bağlantı noktası, İşlevler konağı tarafından özel işleyiciyi çağırmak için kullanılır.

Dağıtılıyor

Her Azure İşlevleri barındırma seçeneğine özel bir işleyici dağıtılabilir. İş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ştururken yığın olarak .NET Core'un seçilmesini öneririz.

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 GitHub deposu özel işleyici örneklerine bakın.

Sorun giderme ve destek

İzleme günlüğü

Özel işleyici işleminiz başlatılamıyorsa veya İşlevler konağıyla iletişimde sorun yaşıyorsa, konaktan daha fazla tanılama iletisi görmek için Trace işlev uygulamasının günlük düzeyini artırabilirsiniz.

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

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

İşlevler ana bilgisayarı, özel işleyici işlemiyle ilgili bilgiler de dahil olmak üzere ek günlük iletileri oluşturur. Ö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ı bir web sunucusu işlemidir, bu nedenle kendi başı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, bunları Azure İşlevleri Premium planında barındırılan özel bir kapsayıcı görüntüsü kullanarak ç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ğlayamıyor.

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.