|
Warning
|
The legacy FunctionInvoker programming model is deprecated and will not be supported going forward.
For up to date samples, aligned with the dependency-injections Azure Adapter, check the: Blob Trigger, HTTP Trigger, Timer Trigger, Kafka Trigger & Output Binding.
For a Gradle project example check the HTTP Trigger with Gradle.
|
The Azure adapter bootstraps a Spring Cloud Function context and channels function calls from the Azure
framework into the user functions, using Spring Boot configuration where necessary. Azure Functions has quite a unique and
invasive programming model, involving annotations in user code that are specific to the Azure platform.
However, it is important to understand that because of the style of integration provided by Spring Cloud Function, specifically org.springframework.cloud.function.adapter.azure.FunctionInvoker, this annotation-based programming model is simply a type-safe way to configure
your simple java function (function that has no awareness of Azure) to be recognized as Azure function.
All you need to do is create a handler that extends FunctionInvoker, define and configure your function handler method and
make a callback to handleRequest(..) method. This handler method provides input and output types as annotated method parameters
(enabling Azure to inspect the class and create JSON bindings).
public class UppercaseHandler extends FunctionInvoker<Message<String>, String> {
@FunctionName("uppercase")
public String execute(@HttpTrigger(name = "req", methods = {HttpMethod.GET,
HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
ExecutionContext context) {
Message<String> message = MessageBuilder.withPayload(request.getBody().get()).copyHeaders(request.getHeaders()).build();
return handleRequest(message, context);
}
}Note that aside form providing configuration via Azure annotation we create an instance of Message inside the body of this handler method and make a callback to handleRequest(..) method returning its result.
The actual user function you’re delegating to looks like this
@Bean
public Function<String, String> uppercase() {
return payload -> payload.toUpperCase();
}
OR
@Bean
public Function<Message<String>, String> uppercase() {
return message -> message.getPayload().toUpperCase();
}Note that when creating a Message you can copy HTTP headers effectively making them available to you if necessary.
The org.springframework.cloud.function.adapter.azure.FunctionInvoker class has two useful
methods (handleRequest and handleOutput) to which you can delegate the actual function call, so mostly the function will only ever have one line.
The function name (definition) will be retrieved from Azure’s ExecutionContext.getFunctionName() method, effectively supporting multiple function in the application context.
Some time there is a need to access the target execution context provided by the Azure runtime in the form of com.microsoft.azure.functions.ExecutionContext.
For example one of such needs is logging, so it can appear in the Azure console.
For that purpose the FunctionInvoker will add an instance of the ExecutionContext as a Message header so you can retrieve it via executionContext key.
@Bean
public Function<Message<String>, String> uppercase(JsonMapper mapper) {
return message -> {
String value = message.getPayload();
ExecutionContext context = (ExecutionContext) message.getHeaders().get("executionContext");
. . .
}
}You don’t need the Spring Cloud Function Web at runtime in Azure, so you can exclude this before you create the JAR you deploy to Azure, but it won’t be used if you include it, so it doesn’t hurt to leave it in. A function application on Azure is an archive generated by the Maven plugin. The function lives in the JAR file generated by this project. The sample creates it as an executable jar, using the thin layout, so that Azure can find the handler classes. If you prefer you can just use a regular flat JAR file. The dependencies should not be included.
In order to run Spring Cloud Function applications on Microsoft Azure, you can leverage the Maven plugin offered by the cloud platform provider.
In order to use the adapter plugin for Maven, add the plugin dependency to your pom.xml
file:
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-function-adapter-azure</artifactId>
</dependency>
</dependencies>Then, configure the plugin. You will need to provide Azure-specific configuration for your
application, specifying the resourceGroup, appName and other optional properties, and
add the package goal execution so that the function.json file required by Azure is
generated for you. Full plugin documentation can be found in the plugin repository.
<plugin>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-functions-maven-plugin</artifactId>
<configuration>
<resourceGroup>${functionResourceGroup}</resourceGroup>
<appName>${functionAppName}</appName>
</configuration>
<executions>
<execution>
<id>package-functions</id>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>You will also have to ensure that the files to be scanned by the plugin can be found in the Azure functions staging directory (see the plugin repository for more details on the staging directory and it’s default location).
You can find the entire sample pom.xml file for deploying Spring Cloud Function
applications to Microsoft Azure with Maven here.
|
Note
|
As of yet, only Maven plugin is available. Gradle plugin has not been created by the cloud platform provider. |
You can run the sample locally, just like the other Spring Cloud Function samples:
and curl -H "Content-Type: text/plain" localhost:8080/api/uppercase -d '{"value": "hello foobar"}'.
You will need the az CLI app (see https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven for more detail). To deploy the function on Azure runtime:
$ az login $ mvn azure-functions:deploy
On another terminal try this: curl https://<azure-function-url-from-the-log>/api/uppercase -d '{"value": "hello foobar!"}'. Please ensure that you use the right URL for the function above. Alternatively you can test the function in the Azure Dashboard UI (click on the function name, go to the right hand side and click "Test" and to the bottom right, "Run").
The input type for the function in the Azure sample is a Foo with a single property called "value". So you need this to test it with something like below:
{
"value": "foobar"
}
|
Note
|
The Azure sample app is written in the "non-functional" style (using @Bean). The functional style (with just Function or ApplicationContextInitializer) is much faster on startup in Azure than the traditional @Bean style, so if you don’t need @Beans (or @EnableAutoConfiguration) it’s a good choice. Warm starts are not affected.
|
You can run this Azure function locally, similar to other Spring Cloud Function samples, however this time by using the Azure Maven plugin, as the Microsoft Azure functions execution context must be available.
|
Note
|
To run locally on top of Azure Functions, and to deploy to your live Azure environment, you will need the Azure Functions Core Tools installed along with the Azure CLI (see here for details). |
../../mvnw clean package
../../mvnw azure-functions:run[INFO] Azure Function App's staging directory found at: /Users/cbono/repos/spring-cloud-function/spring-cloud-function-samples/function-sample-azure/target/azure-functions/spring-cloud-function-samples
4.0.3971
[INFO] Azure Functions Core Tools found.
Azure Functions Core Tools
Core Tools Version: 4.0.3971 Commit hash: d0775d487c93ebd49e9c1166d5c3c01f3c76eaaf (64-bit)
Function Runtime Version: 4.0.1.16815
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 POST http://127.0.0.1:53836/AzureFunctionsRpcMessages.FunctionRpc/EventStream application/grpc -
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'gRPC - /AzureFunctionsRpcMessages.FunctionRpc/EventStream'
[2022-04-11T03:04:05.143Z] OpenJDK 64-Bit Server VM warning: Options -Xverify:none and -noverify were deprecated in JDK 13 and will likely be removed in a future release.
[2022-04-11T03:04:05.247Z] Worker process started and initialized.
Functions:
echo: [GET,POST] http://localhost:7071/api/echo
echoStream: [GET,POST] http://localhost:7071/api/echoStream
uppercase: [GET,POST] http://localhost:7071/api/uppercase
uppercaseReactive: [GET,POST] http://localhost:7071/api/uppercaseReactive
For detailed output, run func with --verbose flag.
[2022-04-11T03:04:10.163Z] Host lock lease acquired by instance ID '000000000000000000000000BEFE21CF'.curl -H "Content-Type: application/json" localhost:7071/api/uppercase -d '{"greeting": "hello", "name": "foo"}'{
"greeting": "HELLO",
"name": "FOO"
}Notice that the URL is of the format <function-base-url>/api/<function-name>).
The uppercase function signature is Function<Message<String>, String> uppercase(). The implementation of UppercaseHandler (which extends FunctionInvoker) copies the HTTP headers of the incoming request into the input message’s MessageHeaders which makes them accessible to the function if needed.
|
Note
|
Implementation of FunctionInvoker (your handler), should contain the least amount of code. It is really a type-safe way to define
and configure function to be recognized as Azure Function.
Everything else should be delegated to the base FunctionInvoker via handleRequest(..) callback which will invoke your function, taking care of
necessary type conversion, transformation etc. One exception to this rule is when custom result handling is required. In that case, the proper post-process method can be overridden as well in order to take control of the results processing.
|
@FunctionName("uppercase")
public String execute(
@HttpTrigger(
name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
ExecutionContext context
) {
Message<String> message = MessageBuilder.withPayload(request.getBody().get())
.copyHeaders(request.getHeaders()).build();
return handleRequest(message, context);
}The echo function does the same as the uppercase less the actual uppercasing. However, the important difference to notice is that function itself
takes primitive String as its input (i.e., public Function<String, String> echo()) while the actual handler passes instance of Message the same way as with uppercase. The framework recognizes that you only care about the payload and extracts it from the Message before calling the function.
There is also a reactive version of uppercase (named uppercaseReactive) which will produce the same result, but demonstrates and validates the ability to use reactive functions with Azure.
|
Note
|
The Azure Java functions runtime does not yet support Java 17 but Spring Cloud Function 4.x requires it. To get around this limitation we deploy to Azure in a custom Docker container. Once Azure supports Java 17 we can move back to using non-Docker deployments. |
The steps below describe the process to create a custom Docker image which is suitable for deployment on Azure and contains the 4.x Azure Functions runtime, the MS Java 17 JVM, and the sample functions in this repo.
Pick an image name for the Docker container (eg. onobc/function-sample-azure-java17:1.0.0) and update the pom.xml functionDockerImageName property with the image name.
|
Tip
|
By default it is expected that the image name is a publicly accessible image on Docker Hub. However, other registries and credentials can be configured as described here. |
../../mvnw clean packagedocker build -t <image-name> .Test the Docker image locally by starting the container and issuing a request.
docker run -p 8080:80 <image-name>cbono@cbono-a01 function-sample-azure % docker run -p 8080:80 onobc/function-sample-azure-java17:1.0.0
info: Host.Triggers.Warmup[0]
Initializing Warmup Extension.
info: Host.Startup[503]
Initializing Host. OperationId: 'e7317c18-4daa-4d69-bf38-beaa51e1a012'.
info: Host.Startup[504]
Host initialization: ConsecutiveErrors=0, StartupCount=1, OperationId=e7317c18-4daa-4d69-bf38-beaa51e1a012
info: Microsoft.Azure.WebJobs.Hosting.OptionsLoggingService[0]
LoggerFilterOptions
{
"MinLevel": "None",
"Rules": [
{
"ProviderName": null,
"CategoryName": null,
"LogLevel": null,
"Filter": "<AddFilter>b__0"
},
{
"ProviderName": "Microsoft.Azure.WebJobs.Script.WebHost.Diagnostics.SystemLoggerProvider",
"CategoryName": null,
"LogLevel": "None",
"Filter": null
},
{
"ProviderName": "Microsoft.Azure.WebJobs.Script.WebHost.Diagnostics.SystemLoggerProvider",
"CategoryName": null,
"LogLevel": null,
"Filter": "<AddFilter>b__0"
}
]
}
...
...
...
info: Microsoft.Azure.WebJobs.Script.WebHost.WebScriptHostHttpRoutesManager[0]
Initializing function HTTP routes
Mapped function route 'api/echo' [GET,POST] to 'echo'
Mapped function route 'api/echoStream' [GET,POST] to 'echoStream'
Mapped function route 'api/uppercase' [GET,POST] to 'uppercase'
Mapped function route 'api/uppercaseReactive' [GET,POST] to 'uppercaseReactive'
info: Host.Startup[412]
Host initialized (65ms)
info: Host.Startup[413]
Host started (81ms)
info: Host.Startup[0]
Job host started
Hosting environment: Production
Content root path: /azure-functions-host
Now listening on: http://[::]:80
Application started. Press Ctrl+C to shut down.
info: Microsoft.Azure.WebJobs.Script.Workers.Rpc.RpcFunctionInvocationDispatcher[0]
Worker process started and initialized.
info: Host.General[337]
Host lock lease acquired by instance ID '000000000000000000000000C4043012'.curl -H "Content-Type: application/json" localhost:8080/api/uppercase -d '{"greeting": "hello", "name": "foo"}'{
"greeting": "HELLO",
"name": "FOO"
}docker push <image-name>At this point the custom image has been created and pushed to the configured Docker registry.
To deploy the functions to your live Azure environment, including automatic provisioning of an HTTPTrigger for each function, do the following.
az login../../mvnw azure-functions:deploy[INFO] ---------------< io.spring.sample:function-sample-azure >---------------
[INFO] Building function-sample-azure 4.0.0.RELEASE
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- azure-functions-maven-plugin:1.16.0:deploy (default-cli) @ function-sample-azure ---
Auth type: AZURE_CLI
Default subscription: SCDF-Azure(b80d18******)
Username: cbono@vmware.com
[INFO] Subscription: SCDF-Azure(*******)
[INFO] Reflections took 123 ms to scan 6 urls, producing 24 keys and 486 values
[INFO] Start creating Resource Group(java-functions-group) in region (West US)...
[INFO] Resource Group(java-functions-group) is successfully created.
[INFO] Reflections took 1 ms to scan 3 urls, producing 12 keys and 12 values
[INFO] Creating app service plan java-functions-app-service-plan...
[INFO] Successfully created app service plan java-functions-app-service-plan.
[INFO] Start creating Application Insight (spring-cloud-function-samples)...
[INFO] Application Insight (spring-cloud-function-samples) is successfully created. You can visit https://ms.portal.azure.com/********providers/Microsoft.Insights/components/spring-cloud-function-samples to view your Application Insights component.
[INFO] Creating function app spring-cloud-function-samples...
[INFO] Set function worker runtime to java.
[INFO] Ignoring decoding of null or empty value to:com.azure.resourcemanager.storage.fluent.models.StorageAccountInner
[INFO] Successfully created function app spring-cloud-function-samples.
[INFO] Skip deployment for docker app service
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:30 min
[INFO] Finished at: 2022-04-04T19:06:24-05:00
[INFO] ------------------------------------------------------------------------|
Tip
|
When deployed as a Docker container the function urls are not written to the console. You will need to inspect the functions in the Azure Portal to find the urls. |
Navigate to the Function App dashboard in the Azure portal and then:
-
click on your function app (
"spring-cloud-function-samples"by default) -
click the left nav
"Functions"link -
click the
"uppercase"function
-
click on the left nav
"Code and Test" -
click on
"Test/Run"at top of page -
enter the following input json in the
"Body"section on the right-hand side:
{
"greeting": "hello",
"name": "foo"
}-
click "Run" and the output should look like:
{
"greeting": "HELLO",
"name": "FOO"
}Armed w/ the function url from above, issue the following curl command in another terminal:
curl -H "Content-Type: application/json" https://spring-cloud-function-samples.azurewebsites.net/api/uppercase -d '{"greeting": "hello", "name": "foo"}'{
"greeting": "HELLO",
"name": "FOO"
}|
Tip
|
The Azure dashboard provides a plethora of information about your functions, including but not limited to execution count, memory consumption and execution time. |
As noted above, the implementation of FunctionInvoker (your handler), should contain the least amount of code possible. However, if custom result handling needs to occur there is a set of methods (named postProcess**) that can be overridden in FunctionInvoker.java.
One such example can be seen in ReactiveEchoCustomResultHandler.java.
Once the function is deployed it can be tested using curl:
curl -H "Content-Type: application/json" localhost:7071/api/echoStream -d '["hello","peepz"]'Kicked off job for [hello, peepz]The custom result handling takes the Flux returned from the echoStream function and adds logging, uppercase mapping, and then subscribes to the publisher. The Azure logs output the following:
[2022-03-01T01:36:57.439Z] 2022-02-28 19:36:57.439 INFO 20587 --- [pool-2-thread-2] o.s.boot.SpringApplication : Started application in 0.466 seconds (JVM running for 57.906)
[2022-03-01T01:36:57.462Z] BEGIN echo post-processing work ...
[2022-03-01T01:36:57.462Z] HELLO
[2022-03-01T01:36:57.462Z] PEEPZ
[2022-03-01T01:36:57.463Z] END echo post-processing work
[2022-03-01T01:36:57.463Z] Function "echoStream" (Id: 678cff0b-d958-4fab-967b-e19e0d5d67e8) invoked by Java Worker