Aangepaste handlers Azure FunctionsAzure Functions custom handlers

Elke functions-app wordt uitgevoerd door een taalspecifieke handler.Every Functions app is executed by a language-specific handler. Hoewel Azure Functions veel taal ingangen ondersteunt, zijn er situaties waarin u mogelijk andere talen of Runtimes wilt gebruiken.While Azure Functions supports many language handlers by default, there are cases where you may want to use other languages or runtimes.

Aangepaste handlers zijn Lightweight webservers die gebeurtenissen ontvangen van de host functions.Custom handlers are lightweight web servers that receive events from the Functions host. Elke taal die HTTP-primitieven ondersteunt, kan een aangepaste handler implementeren.Any language that supports HTTP primitives can implement a custom handler.

Aangepaste handlers zijn het meest geschikt voor situaties waar u het volgende wilt doen:Custom handlers are best suited for situations where you want to:

  • Implementeer een functie-app in een taal die momenteel niet wordt ondersteund, zoals Go of roest.Implement a function app in a language that's not currently supported, such as Go or Rust.
  • Implementeer een functie-app in een runtime die momenteel niet wordt ondersteund, zoals Deno.Implement a function app in a runtime that's not currently supported, such as Deno.

Met aangepaste handlers kunt u Triggers en invoer-en uitvoer bindingen gebruiken via uitbreidings bundels.With custom handlers, you can use triggers and input and output bindings via extension bundles.

Aan de slag met Azure Functions aangepaste handlers met Quick starts in go en roest.Get started with Azure Functions custom handlers with quickstarts in Go and Rust.

OverzichtOverview

In het volgende diagram ziet u de relatie tussen de host functions en een webserver die is geïmplementeerd als een aangepaste handler.The following diagram shows the relationship between the Functions host and a web server implemented as a custom handler.

Overzicht van Azure Functions aangepaste handler

  1. Elke gebeurtenis activeert een aanvraag die wordt verzonden naar de host functions.Each event triggers a request sent to the Functions host. Een gebeurtenis is een trigger die wordt ondersteund door Azure Functions.An event is any trigger that is supported by Azure Functions.
  2. De host functions verzendt vervolgens een aanvraag lading aan de webserver.The Functions host then issues a request payload to the web server. De payload bevat trigger-en invoer bindings gegevens en andere meta gegevens voor de functie.The payload holds trigger and input binding data and other metadata for the function.
  3. De webserver voert de afzonderlijke functie uit en retourneert een nettolading van de reactie op de host functions.The web server executes the individual function, and returns a response payload to the Functions host.
  4. Met de functie-host worden gegevens door gegeven van het antwoord op de uitvoer bindingen van de functie voor verwerking.The Functions host passes data from the response to the function's output bindings for processing.

Een Azure Functions-app die is geïmplementeerd als aangepaste handler moet de host.jsop, local.settings.jsop en function.jsop bestanden configureren volgens een aantal conventies.An Azure Functions app implemented as a custom handler must configure the host.json, local.settings.json, and function.json files according to a few conventions.

Toepassings structuurApplication structure

Als u een aangepaste handler wilt implementeren, hebt u de volgende aspecten nodig voor uw toepassing:To implement a custom handler, you need the following aspects to your application:

  • Een host.jsin het bestand in de hoofdmap van uw appA host.json file at the root of your app
  • Een local.settings.jsin het bestand in de hoofdmap van uw appA local.settings.json file at the root of your app
  • Een function.jsin het bestand voor elke functie (in een map die overeenkomt met de naam van de functie)A function.json file for each function (inside a folder that matches the function name)
  • Een opdracht, script of uitvoerbaar bestand, waarmee een webserver wordt uitgevoerdA command, script, or executable, which runs a web server

In het volgende diagram ziet u hoe deze bestanden eruitzien op het bestands systeem voor een functie met de naam ' MyQueueFunction ' en een uitvoerbaar bestand van een aangepaste handler met de naam handler.exe.The following diagram shows how these files look on the file system for a function named "MyQueueFunction" and an custom handler executable named handler.exe.

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

ConfiguratieConfiguration

De toepassing wordt geconfigureerd via de host.jsop en local.settings.jsop bestanden.The application is configured via the host.json and local.settings.json files.

host.jsophost.json

host.js geeft aan dat de functions-host waar aanvragen moet worden verzonden door een webserver aan te wijzen die http-gebeurtenissen kan verwerken.host.json tells the Functions host where to send requests by pointing to a web server capable of processing HTTP events.

Er wordt een aangepaste handler gedefinieerd door de host.js te configureren in het bestand met informatie over het uitvoeren van de webserver via de customHandler sectie.A custom handler is defined by configuring the host.json file with details on how to run the web server via the customHandler section.

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

De customHandler sectie verwijst naar een doel zoals gedefinieerd door de defaultExecutablePath .The customHandler section points to a target as defined by the defaultExecutablePath. Het doel van de uitvoering kan een opdracht, een uitvoerbaar bestand of een file zijn waarin de webserver is geïmplementeerd.The execution target may either be a command, executable, or file where the web server is implemented.

Gebruik de arguments matrix om eventuele argumenten door te geven aan het uitvoer bare bestand.Use the arguments array to pass any arguments to the executable. Argumenten ondersteunen de uitbrei ding van omgevings variabelen (toepassings instellingen) met behulp van een %% notatie.Arguments support expansion of environment variables (application settings) using %% notation.

U kunt de werkmap die wordt gebruikt door het uitvoer bare bestand ook wijzigen met workingDirectory .You can also change the working directory used by the executable with workingDirectory.

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

Standaard triggers samen met invoer-en uitvoer bindingen zijn beschikbaar door te verwijzen naar uitbreidings bundels in uw host.js in het bestand.Standard triggers along with input and output bindings are available by referencing extension bundles in your host.json file.

local.settings.jsonlocal.settings.json

local.settings.jsop definieert toepassings instellingen die worden gebruikt bij het lokaal uitvoeren van de functie-app.local.settings.json defines application settings used when running the function app locally. Omdat het mogelijk geheimen bevat, moet local.settings.jsop worden uitgesloten van broncode beheer.As it may contain secrets, local.settings.json should be excluded from source control. In azure gebruikt u in plaats daarvan toepassings instellingen.In Azure, use application settings instead.

Stel voor aangepaste handlers FUNCTIONS_WORKER_RUNTIME in op Custom in local.settings.jsop.For custom handlers, set FUNCTIONS_WORKER_RUNTIME to Custom in local.settings.json.

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

Functie-meta gegevensFunction metadata

Wanneer u gebruikt met een aangepaste handler, zijn de function.jsop inhoud niet verschillend van hoe u een functie onder elke andere context definieert.When used with a custom handler, the function.json contents are no different from how you would define a function under any other context. De enige vereiste is dat function.jsop bestanden moet zich in een map bevinden met de naam die overeenkomt met de naam van de functie.The only requirement is that function.json files must be in a folder named to match the function name.

Met de volgende function.jsop configureert u een functie met een wachtrij trigger en een binding van de wachtrij-uitvoer.The following function.json configures a function that has a queue trigger and a queue output binding. Omdat het zich in een map bevindt met de naam MyQueueFunction, wordt een functie gedefinieerd met de naam MyQueueFunction.Because it's in a folder named MyQueueFunction, it defines a function named MyQueueFunction.

MyQueueFunction/function.jsopMyQueueFunction/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"
    }
  ]
}

Payload aanvragenRequest payload

Wanneer een wachtrij bericht wordt ontvangen, verzendt de host functions een HTTP POST-aanvraag naar de aangepaste handler met een nettolading in de hoofd tekst.When a queue message is received, the Functions host sends an HTTP post request to the custom handler with a payload in the body.

De volgende code vertegenwoordigt een nettolading van de voorbeeld aanvraag.The following code represents a sample request payload. De payload bevat een JSON-structuur met twee leden: Data en Metadata .The payload includes a JSON structure with two members: Data and Metadata.

Het Data lid bevat sleutels die overeenkomen met de namen van de invoer en de trigger, zoals gedefinieerd in de bindingen matrix in de function.jsvoor het bestand.The Data member includes keys that match input and trigger names as defined in the bindings array in the function.json file.

Het Metadata lid bevat meta gegevens die zijn gegenereerd op basis van de bron van de gebeurtenis.The Metadata member includes metadata generated from the event source.

{
  "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"
    }
  }
}

Nettolading van reactieResponse payload

Per Conventie worden functie reacties opgemaakt als sleutel/waarde-paren.By convention, function responses are formatted as key/value pairs. Ondersteunde sleutels zijn onder andere:Supported keys include:

Payload-sleutelPayload key GegevenstypeData type OpmerkingenRemarks
Outputs objectobject Bevat reactie waarden zoals gedefinieerd door de bindings matrix in function.jsop.Holds response values as defined by the bindings array in function.json.

Als een functie bijvoorbeeld is geconfigureerd met een wachtrij-uitvoer binding met de naam ' myQueueOutput ', Outputs bevat deze een sleutel met myQueueOutput de naam, die door de aangepaste handler wordt ingesteld op de berichten die naar de wachtrij worden verzonden.For instance, if a function is configured with a queue output binding named "myQueueOutput", then Outputs contains a key named myQueueOutput, which is set by the custom handler to the messages that are sent to the queue.
Logs matrixarray Berichten worden weer gegeven in de functie Logboeken van functies.Messages appear in the Functions invocation logs.

Bij het uitvoeren in Azure worden berichten weer gegeven in Application Insights.When running in Azure, messages appear in Application Insights.
ReturnValue tekenreeksstring Wordt gebruikt om een reactie te geven wanneer een uitvoer is geconfigureerd als $return in de function.jsvoor het bestand.Used to provide a response when an output is configured as $return in the function.json file.

Dit is een voor beeld van een nettolading van een reactie.This is an example of a response payload.

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

VoorbeeldenExamples

Aangepaste handlers kunnen worden geïmplementeerd in elke taal die ondersteuning biedt voor het ontvangen van HTTP-gebeurtenissen.Custom handlers can be implemented in any language that supports receiving HTTP events. In de volgende voor beelden ziet u hoe u een aangepaste handler implementeert met behulp van de programmeer taal go.The following examples show how to implement a custom handler using the Go programming language.

Functie met bindingenFunction with bindings

Het scenario dat in dit voor beeld wordt geïmplementeerd, bevat een functie met de naam order die een-Payload accepteert die POST een product order vertegenwoordigt.The scenario implemented in this example features a function named order that accepts a POST with a payload representing a product order. Als een order wordt gepost naar de functie, wordt een Queue Storage bericht gemaakt en wordt een HTTP-antwoord geretourneerd.As an order is posted to the function, a Queue Storage message is created and an HTTP response is returned.

ImplementatieImplementation

In een map met de naam order wordt met de function.jsin het bestand de functie http-activering geconfigureerd.In a folder named order, the function.json file configures the HTTP-triggered function.

order/function.jsoporder/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"
    }
  ]
}

Deze functie is gedefinieerd als een http-geactiveerde functie die een http-antwoord retourneert en een wachtrij-opslag bericht uitvoert.This function is defined as an HTTP triggered function that returns an HTTP response and outputs a Queue storage message.

In de hoofdmap van de app is de host.jsin het bestand geconfigureerd voor het uitvoeren van een uitvoerbaar bestand met de naam handler.exe ( handler in Linux of macOS).At the root of the app, the host.json file is configured to run an executable file named handler.exe (handler in Linux or macOS).

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

Dit is de HTTP-aanvraag die wordt verzonden naar de functions-runtime.This is the HTTP request sent to the Functions runtime.

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

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

De runtime van functions stuurt vervolgens de volgende HTTP-aanvraag naar de aangepaste handler:The Functions runtime will then send the following HTTP request to the custom handler:

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": {
  }
}

Notitie

Sommige delen van de payload zijn verwijderd voor de boog.Some portions of the payload were removed for brevity.

handler.exe is het gecompileerde, aangepaste handler-programma dat een webserver uitvoert en reageert op aanvragen voor het aanroepen van de functie van de host functions.handler.exe is the compiled Go custom handler program that runs a web server and responds to function invocation requests from the Functions host.

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

In dit voor beeld voert de aangepaste handler een webserver uit voor het afhandelen van HTTP-gebeurtenissen en wordt ingesteld om te Luis teren naar aanvragen via de FUNCTIONS_CUSTOMHANDLER_PORT .In this example, the custom handler runs a web server to handle HTTP events and is set to listen for requests via the FUNCTIONS_CUSTOMHANDLER_PORT.

Hoewel de functie host de oorspronkelijke HTTP-aanvraag op heeft ontvangen /api/order , roept deze de aangepaste handler aan met behulp van de naam (de naam van de map).Even though the Functions host received original HTTP request at /api/order, it invokes the custom handler using the function name (its folder name). In dit voor beeld wordt de functie gedefinieerd in het pad van /order .In this example, the function is defined at the path of /order. De host verzendt de aangepaste handler een HTTP-aanvraag op het pad van /order .The host sends the custom handler an HTTP request at the path of /order.

Wanneer POST aanvragen naar deze functie worden verzonden, zijn de meta gegevens van de trigger en de functie beschikbaar via de hoofd tekst van de HTTP-aanvraag.As POST requests are sent to this function, the trigger data and function metadata are available via the HTTP request body. De oorspronkelijke hoofd tekst van de HTTP-aanvraag kan worden geopend in de payload Data.req.Body .The original HTTP request body can be accessed in the payload's Data.req.Body.

De reactie van de functie is ingedeeld in sleutel-waardeparen waarbij het Outputs lid een JSON-waarde bevat waarin de sleutels overeenkomen met de uitvoer zoals gedefinieerd in de function.jsvoor het bestand.The function's response is formatted into key/value pairs where the Outputs member holds a JSON value where the keys match the outputs as defined in the function.json file.

Dit is een voor beeld-nettolading die door deze handler wordt geretourneerd naar de host functions.This is an example payload that this handler returns to the Functions host.

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

Door de message uitvoer gelijk te stellen aan de volg orde van de gegevens in de aanvraag, wordt de functie uitgevoerd die gegevens bestelt in de geconfigureerde wachtrij.By setting the message output equal to the order data that came in from the request, the function outputs that order data to the configured queue. De host functions retourneert ook het HTTP-antwoord res dat is geconfigureerd voor aan de aanroeper.The Functions host also returns the HTTP response configured in res to the caller.

Alleen HTTP-functieHTTP-only function

Voor HTTP-geactiveerde functies zonder extra bindingen of uitvoer, wilt u mogelijk dat uw handler rechtstreeks werkt met de HTTP-aanvraag en het antwoord in plaats van de nettolading van de aangepaste handler- aanvraag en de reactie .For HTTP-triggered functions with no additional bindings or outputs, you may want your handler to work directly with the HTTP request and response instead of the custom handler request and response payloads. Dit gedrag kan worden geconfigureerd in host.jsvoor het gebruik van de enableForwardingHttpRequest instelling.This behavior can be configured in host.json using the enableForwardingHttpRequest setting.

Belangrijk

Het primaire doel van de functie voor aangepaste handlers is om talen en Runtimes in te scha kelen die momenteel geen eersteklas ondersteuning voor de Azure Functions hebben.The primary purpose of the custom handlers feature is to enable languages and runtimes that do not currently have first-class support on Azure Functions. Hoewel het mogelijk is om webtoepassingen uit te voeren met aangepaste handlers, is Azure Functions geen standaard omgekeerde proxy.While it may be possible to run web applications using custom handlers, Azure Functions is not a standard reverse proxy. Sommige functies, zoals het streamen van antwoorden, HTTP/2 en websockets zijn niet beschikbaar.Some features such as response streaming, HTTP/2, and WebSockets are not available. Sommige onderdelen van de HTTP-aanvraag, zoals bepaalde headers en routes, zijn mogelijk beperkt.Some components of the HTTP request such as certain headers and routes may be restricted. Uw toepassing ondervindt mogelijk ook overmatig koud starten.Your application may also experience excessive cold start.

Als u deze omstandigheden wilt aanpakken, kunt u uw web-apps uitvoeren op Azure app service.To address these circumstances, consider running your web apps on Azure App Service.

In het volgende voor beeld ziet u hoe u een door HTTP geactiveerde functie kunt configureren zonder extra bindingen of uitvoer.The following example demonstrates how to configure an HTTP-triggered function with no additional bindings or outputs. Het scenario dat in dit voor beeld wordt geïmplementeerd, bevat een functie met de naam hello die een GET of accepteert POST .The scenario implemented in this example features a function named hello that accepts a GET or POST .

ImplementatieImplementation

In een map met de naam Hello wordt de functie met http-activering geconfigureerd door het bestand function.js .In a folder named hello, the function.json file configures the HTTP-triggered function.

Hallo/function.jsophello/function.json

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

De functie is geconfigureerd om zowel als-aanvragen te accepteren GET POST en de resultaat waarde wordt opgegeven via een argument met de naam res .The function is configured to accept both GET and POST requests and the result value is provided via an argument named res.

In de hoofdmap van de app is de host.jsin het bestand geconfigureerd om te worden uitgevoerd handler.exe en enableForwardingHttpRequest is ingesteld op true .At the root of the app, the host.json file is configured to run handler.exe and enableForwardingHttpRequest is set to true.

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

Als enableForwardingHttpRequest true dat het geval is, verschilt het gedrag van alleen-HTTP-functies van het standaard gedrag aangepaste handlers op de volgende manieren:When enableForwardingHttpRequest is true, the behavior of HTTP-only functions differs from the default custom handlers behavior in these ways:

  • De HTTP-aanvraag bevat niet de aanvraag lading van de aangepaste handlers.The HTTP request does not contain the custom handlers request payload. In plaats daarvan roept de host functions de handler aan met een kopie van de oorspronkelijke HTTP-aanvraag.Instead, the Functions host invokes the handler with a copy of the original HTTP request.
  • De host functions roept de handler aan met hetzelfde pad als de oorspronkelijke aanvraag, inclusief eventuele query teken reeks parameters.The Functions host invokes the handler with the same path as the original request including any query string parameters.
  • De functie host retourneert een kopie van het HTTP-antwoord van de handler als reactie op de oorspronkelijke aanvraag.The Functions host returns a copy of the handler's HTTP response as the response to the original request.

Hier volgt een POST-aanvraag naar de functions-host.The following is a POST request to the Functions host. De host functions stuurt vervolgens een kopie van de aanvraag naar de aangepaste handler op hetzelfde pad.The Functions host then sends a copy of the request to the custom handler at the same path.

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

{
  "message": "Hello World!"
}

Het bestand handler. go implementeert een webserver en http-functie.The file handler.go file implements a web server and HTTP function.

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

In dit voor beeld maakt de aangepaste handler een webserver voor het afhandelen van HTTP-gebeurtenissen en wordt ingesteld om te Luis teren naar aanvragen via de FUNCTIONS_CUSTOMHANDLER_PORT .In this example, the custom handler creates a web server to handle HTTP events and is set to listen for requests via the FUNCTIONS_CUSTOMHANDLER_PORT.

GET aanvragen worden verwerkt door een teken reeks te retour neren en POST aanvragen hebben toegang tot de hoofd tekst van de aanvraag.GET requests are handled by returning a string, and POST requests have access to the request body.

De route voor de functie order is hier /api/hello hetzelfde als de oorspronkelijke aanvraag.The route for the order function here is /api/hello, same as the original request.

Notitie

De FUNCTIONS_CUSTOMHANDLER_PORT is niet de open bare poort die wordt gebruikt om de functie aan te roepen.The FUNCTIONS_CUSTOMHANDLER_PORT is not the public facing port used to call the function. Deze poort wordt gebruikt door de host functions om de aangepaste handler aan te roepen.This port is used by the Functions host to call the custom handler.

InstalleertDeploying

Een aangepaste handler kan worden geïmplementeerd voor elke Azure Functions Hosting optie.A custom handler can be deployed to every Azure Functions hosting option. Als uw handler afhankelijkheden van het besturings systeem of platform vereist (zoals een taal runtime), moet u mogelijk een aangepaste containergebruiken.If your handler requires operating system or platform dependencies (such as a language runtime), you may need to use a custom container.

Wanneer u een functie-app in azure maakt voor aangepaste handlers, raden we u aan om .NET Core als stack te selecteren.When creating a function app in Azure for custom handlers, we recommend you select .NET Core as the stack. In de toekomst wordt een ' aangepaste ' stack voor aangepaste handlers toegevoegd.A "Custom" stack for custom handlers will be added in the future.

Als u een aangepaste handler-app wilt implementeren met behulp van Azure Functions Core Tools, voert u de volgende opdracht uit.To deploy a custom handler app using Azure Functions Core Tools, run the following command.

func azure functionapp publish $functionAppName

Notitie

Zorg ervoor dat alle bestanden die nodig zijn om uw aangepaste handler uit te voeren, zich in de map bevinden en zijn opgenomen in de-implementatie.Ensure all files required to run your custom handler are in the folder and included in the deployment. Als uw aangepaste handler een binair uitvoerbaar bestand is of platformspecifieke afhankelijkheden heeft, moet u ervoor zorgen dat deze bestanden overeenkomen met het doel implementatie platform.If your custom handler is a binary executable or has platform-specific dependencies, ensure these files match the target deployment platform.

BeperkingenRestrictions

  • De webserver voor de aangepaste handler moet binnen 60 seconden beginnen.The custom handler web server needs to start within 60 seconds.

VoorbeeldenSamples

Raadpleeg de aangepaste handler-voor beelden github opslag plaats voor voor beelden van hoe functies in verschillende talen kunnen worden geïmplementeerd.Refer to the custom handler samples GitHub repo for examples of how to implement functions in a variety of different languages.

Probleem oplossing en ondersteuningTroubleshooting and support

Traceer logboek registratieTrace logging

Als uw aangepaste handler-proces niet kan worden gestart of als er problemen zijn met de communicatie met de functions-host, kunt u het logboek niveau van de functie-app verhogen om Trace meer diagnostische berichten van de host weer te geven.If your custom handler process fails to start up or if it has problems communicating with the Functions host, you can increase the function app's log level to Trace to see more diagnostic messages from the host.

Als u het standaard logboek niveau van de functie-app wilt wijzigen, configureert u de logLevel instelling in de logging sectie van host.jsop.To change the function app's default log level, configure the logLevel setting in the logging section of host.json.

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

Met de functions-host worden extra logboek berichten uitgevoerd, inclusief informatie over het proces van de aangepaste handler.The Functions host outputs extra log messages including information related to the custom handler process. Gebruik de logboeken voor het onderzoeken van problemen bij het starten van uw aangepaste handler-proces of het aanroepen van functies in uw aangepaste handler.Use the logs to investigate problems starting your custom handler process or invoking functions in your custom handler.

Lokaal worden logboeken afgedrukt op de-console.Locally, logs are printed to the console.

Zoek in azure Application Insights traceringen om de logboek berichten weer te geven.In Azure, query Application Insights traces to view the log messages. Als uw app een groot aantal logboeken produceert, worden er alleen een subset van logboek berichten verzonden naar Application Insights.If your app produces a high volume of logs, only a subset of log messages are sent to Application Insights. Schakel steek proeven uit om ervoor te zorgen dat alle berichten worden geregistreerd.Disable sampling to ensure all messages are logged.

Aangepaste handler in isolatie testenTest custom handler in isolation

Aangepaste handler-apps zijn een webserver proces, dus het kan handig zijn om deze te starten met de eigen en test functie aanroepen door het verzenden van HTTP-aanvragen via een hulp programma zoals krul of postman.Custom handler apps are a web server process, so it may be helpful to start it on its own and test function invocations by sending mock HTTP requests using a tool like cURL or Postman.

U kunt deze strategie ook gebruiken in uw CI/CD-pijp lijnen om automatische tests uit te voeren op uw aangepaste handler.You can also use this strategy in your CI/CD pipelines to run automated tests on your custom handler.

Uitvoerings omgevingExecution environment

Aangepaste handlers worden uitgevoerd in dezelfde omgeving als een typische Azure Functions-app.Custom handlers run in the same environment as a typical Azure Functions app. Test uw handler om te controleren of de omgeving alle afhankelijkheden bevat die moeten worden uitgevoerd.Test your handler to ensure the environment contains all the dependencies it needs to run. Voor apps waarvoor extra afhankelijkheden zijn vereist, moet u deze mogelijk uitvoeren met een aangepaste container installatie kopie die wordt gehost op Azure functions Premium-abonnement.For apps that require additional dependencies, you may need to run them using a custom container image hosted on Azure Functions Premium plan.

Ondersteuning krijgenGet support

Als u hulp nodig hebt bij een functie-app met aangepaste handlers, kunt u een aanvraag indienen via reguliere ondersteunings kanalen.If you need help on a function app with custom handlers, you can submit a request through regular support channels. Vanwege de grote verscheidenheid aan mogelijke talen die worden gebruikt voor het bouwen van aangepaste handlers-apps, is ondersteuning niet onbeperkt.However, due to the wide variety of possible languages used to build custom handlers apps, support is not unlimited.

Ondersteuning is beschikbaar als de host functions problemen ondervindt met het starten of communiceren met het aangepaste registratie proces.Support is available if the Functions host has problems starting or communicating with the custom handler process. Voor problemen die betrekking hebben op de interne werking van uw aangepaste handler-proces, zoals problemen met de gekozen taal of het Framework, kan het ondersteunings team geen hulp bieden in deze context.For problems specific to the inner workings of your custom handler process, such as issues with the chosen language or framework, our Support Team is unable to provide assistance in this context.

Volgende stappenNext steps

Aan de slag met het bouwen van een Azure Functions-app in go of roest met de Snelstartgids voor aangepaste handlers.Get started building an Azure Functions app in Go or Rust with the custom handlers quickstart.