HttpTrigger Interface

  • Reference
Package:
com.microsoft.azure.functions.annotation
Maven Artifact:
com.microsoft.azure.functions:azure-functions-java-library:1.3.1

Implements

java.lang.annotation.Annotation

public interface HttpTrigger
implements java.lang.annotation.Annotation

The HttpTrigger annotation is applied to Azure functions that will be triggered by a call to the HTTP endpoint that the function is located at. The HttpTrigger annotation should be applied to a method parameter of one of the following types:

  • HttpRequestMessage<T>
  • Any native Java types such as int, String, byte[]
  • Nullable values using Optional
  • Any POJO type

For example:

@FunctionName("hello")
  public HttpResponseMessage<String> helloFunction(
    @HttpTrigger(name = "req",
                  methods = {HttpMethod.GET},
                  authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request
  ) {
     ....
  }

In this code snippet you will observe that we have a function annotated with @FunctionName("hello"), which indicates that this function will be available at the endpoint /api/hello. The name of the method itself, in this case helloFunction is irrelevant for all intents and purposes related to Azure Functions. Note however that the method return type is HttpResponseMessage, and that the first argument into the function is an HttpRequestMessage<T> with generic type Optional. This indicates that the body of the request will potentially contain a String value.

Most important of all however is the @HttpTrigger annotation that has been applied to this argument. In this annotation you'll note that it has been given a name, as well as told what type of requests it supports (in this case, only HTTP GET requests), and that the AuthorizationLevel is anonymous, allowing access to anyone who can call the endpoint.

The HttpTrigger can be further customised by providing a custom route(), which allows for custom endpoints to be specified, and for these endpoints to be parameterized with arguments being bound to arguments provided to the function at runtime.

The following example shows a Java function that looks for a name parameter either in the query string (HTTP GET) or the body (HTTP POST) of the HTTP request. Notice that the return value is used for the output binding, but a return value attribute isn't required.

@FunctionName("readHttpName")
  public String readName(
    @HttpTrigger(name = "req", 
          methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
          final HttpRequestMessage<Optional<String>> request) {
       String name = request.getBody().orElseGet(() -> request.getQueryParameters().get("name"));
       return name == null ?
              "Please pass a name on the query string or in the request body" :
              "Hello " + name;
  }

Method Summary

Modifier and Type Method and Description
abstract AuthorizationLevel authLevel()

Determines what keys, if any, need to be present on the request in order to invoke the function.
abstract java.lang.String dataType()

Defines how Functions runtime should treat the parameter value.
abstract HttpMethod[] methods()

An array of the HTTP methods to which the function responds.
abstract java.lang.String name()

The variable name used in function code for the request or request body.
abstract java.lang.String route()

Defines the route template, controlling which request URLs your function will respond to.

Method Details

authLevel

public abstract AuthorizationLevel authLevel()

Determines what keys, if any, need to be present on the request in order to invoke the function. The authorization level can be one of the following values:

  • anonymous: No API key is required.
  • function: A function-specific API key is required. This is the default value if none is provided.
  • admin: The master key is required.

For more information, see the documentation about authorization keys.

Returns:

An AuthorizationLevel value representing the level required to access the function.

dataType

public abstract String dataType()

Defines how Functions runtime should treat the parameter value. Possible values are:

  • "": get the value as a string, and try to deserialize to actual parameter type like POJO
  • string: always get the value as a string
  • binary: get the value as a binary data, and try to deserialize to actual parameter type byte[]

Returns:

The dataType which will be used by the Functions runtime.

methods

public abstract HttpMethod[] methods()

An array of the HTTP methods to which the function responds. If not specified, the function responds to all HTTP methods.

Returns:

An array containing all valid HTTP methods.

name

public abstract String name()

The variable name used in function code for the request or request body.

Returns:

The variable name used in function code for the request or request body.

route

public abstract String route()

Defines the route template, controlling which request URLs your function will respond to. The default value if no route is provided is the function name specified in the FunctionName annotation, applied to each Azure Function.

By default when you create a function for an HTTP trigger, or WebHook, the function is addressable with a route of the form http://<yourapp>.azurewebsites.net/api/<funcname>. You can customize this route using this route property. For example, a route of "products/{category:alpha}/{id:int}" would mean that the function is now addressable with the following route instead of the original route: http://<yourapp>.azurewebsites.net/api/products/electronics/357, which allows the function code to support two parameters in the address: category and id. By specifying the route in this way, developers can then add the additional route arguments as arguments into the function by using the BindingName annotation. For example:

@FunctionName("routeTest")
  public HttpResponseMessage<String> routeTest(
      @HttpTrigger(name = "req",
                    methods = {HttpMethod.GET},
                    authLevel = AuthorizationLevel.ANONYMOUS,
                    route = "products/{category:alpha}/{id:int}") 
                    HttpRequestMessage<Optional<String>> request,
      @BindingName("category") String category,
      @BindingName("id") int id,
       final ExecutionContext context
  ) {
           ....
           context.getLogger().info("We have " + category + " with id " + id);
           ....
  }

For more details on the route syntax, refer to the online documentation.

Returns:

The route template to use for the annotated function.

Applies to