Microsoft Azure Functions
适用于 Spring Cloud Function 应用程序作为本机 Azure Java 函数的 Azure 函数适配器。
Azure function adapter for deploying Spring Cloud Function
applications as native Azure Java Functions.
Azure 函数编程模型广泛依赖 Java 注释,用于定义函数的处理程序方法及其输入和输出类型。在编译时,已提供 Azure Maven/Gradle 插件来处理带注释的类,以生成必要的 Azure 函数绑定文件、配置和包工件。Azure 注释只是一种类型安全的方式,用于将您的 Java 函数配置为被识别为 Azure 函数。
The Azure Functions
programming model relays, extensively, on Java annotations for defining the function’s handler methods and their input and output types.
At compile time the annotated classes are processed by the provided Azure Maven/Gradle plugins to generate the necessary Azure Function binding files, configurations and package artifacts.
The Azure annotations are just a type-safe way to configure your java function to be recognized as Azure function.
spring-cloud-function-adapter-azure 扩展了基本编程模型,以提供 Spring 和 Spring Cloud Function 支持。借助此适配器,您可以使用依赖注入功能构建 Spring Cloud Function 应用程序,然后将必要的服务自动注入 Azure 处理程序方法。
The spring-cloud-function-adapter-azure extends the basic programming model to provide Spring and Spring Cloud Function support. With the adapter you can build your Spring Cloud Function application using dependency injections and then auto-wire the necessary services into your Azure handler methods. image::{github-raw}/docs/src/main/asciidoc/images/scf-azure-adapter.svg[]
对于基于 Web 的函数应用程序,您可以使用专门的 spring-cloud-function-adapter-azure-web 替换通用的 |
For Web-based function applications, you can replace the generic |
Azure Adapter
为 Azure 函数提供 Spring 和 Spring Cloud Function 集成。
Provides Spring
& Spring Cloud Function
integration for Azure Functions.
Dependencies
为了启用 Azure 函数集成,请将 Azure 适配器依赖项添加到 pom.xml
或 build.gradle
文件中:
In order to enable the Azure Function integration add the azure adapter dependency to your pom.xml
or build.gradle
files:
-
Maven
-
Gradle
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-function-adapter-azure</artifactId>
</dependency>
</dependencies>
dependencies {
implementation 'org.springframework.cloud:spring-cloud-function-adapter-azure'
}
|
version |
Development Guidelines
使用 @Component
(或 @Service
)注释将任何退出的 Azure Function 类(例如使用 @FunctionName
处理程序)转换为 Spring 组件。然后,您可以自动装配所需的依赖项(或 Spring Cloud Function 组合的 Function Catalog),并在 Azure 函数处理程序中使用它们。
Use the @Component
(or @Service
) annotation to turn any exiting Azure Function class (e.g. with @FunctionName
handlers) into a Spring component.
Then you can auto-wire the required dependencies (or the Function Catalog for Spring Cloud Function composition) and use those inside the Azure function handlers.
@Component (1)
public class MyAzureFunction {
// Plain Spring bean - not a Spring Cloud Functions!
@Autowired private Function<String, String> uppercase; (2)
// The FunctionCatalog leverages the Spring Cloud Function framework.
@Autowired private FunctionCatalog functionCatalog; (2)
@FunctionName("spring") (3)
public String plainBean( (4)
@HttpTrigger(name = "req",
methods = { HttpMethod.POST },
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
ExecutionContext context) {
return this.uppercase.apply(request.getBody().get());
}
@FunctionName("scf") (3)
public String springCloudFunction( (5)
@HttpTrigger(name = "req",
methods = { HttpMethod.POST },
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
ExecutionContext context) {
// Use SCF composition. Composed functions are not just spring beans but SCF such.
Function composed = this.functionCatalog.lookup("reverse|uppercase"); (6)
return (String) composed.apply(request.getBody().get());
}
}
1 | Indicates that the MyAzureFunction class is a "component" to be considered by the Spring Framework as a candidate for auto-detection and classpath scanning. |
2 | Auto-wire the uppercase and functionCatalog beans defined in the HttpTriggerDemoApplication (below). |
3 | The @FunctionName annotation identifies the designated Azure function handlers.
When invoked by a trigger (such as @HttpTrigger ), functions process that trigger, and any other inputs, to produce one or more outputs. |
4 | The plainBean method handler is mapped to an Azure function that uses of the auto-wired uppercase spring bean to compute the result.
It demonstrates how to use "plain" Spring components in your Azure handlers. |
5 | The springCloudFunction method handler is mapped to another Azure function, that uses the auto-wired FunctionCatalog instance to compute the result. |
6 | Shows how to leverage the Spring Cloud Function Function Catalog composition API. |
使用 com.microsoft.azure.functions.annotation.* 包中包含的 Java 注解将输入和输出绑定到您的方法。 |
Use the Java annotations included in the com.microsoft.azure.functions.annotation.* package to bind input and outputs to your methods. |
在 Azure 处理程序中使用的业务逻辑的实现看起来像一个通用的 Spring 应用程序:
The implementation of the business logic used inside the Azure handlers looks like a common Spring application:
@SpringBootApplication (1)
public class HttpTriggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(HttpTriggerDemoApplication.class, args);
}
@Bean
public Function<String, String> uppercase() { (2)
return payload -> payload.toUpperCase();
}
@Bean
public Function<String, String> reverse() { (2)
return payload -> new StringBuilder(payload).reverse().toString();
}
}
1 | The @SpringBootApplication annotated class is used as a Main-Class as explained in main class configuration. |
2 | Functions auto-wired and used in the Azure function handlers. |
Function Catalog
Spring Cloud Function 支持一系列用户定义函数的类型签名,同时提供一致的执行模型。为此,它使用 Function Catalog 将所有用户定义的函数转换成规范表示形式。
The Spring Cloud Function supports a range of type signatures for user-defined functions, while providing a consistent execution model. For this it uses the Function Catalog to transform all user defined functions into a canonical representation.
Azure 适配器可以自动连接任何 Spring 组件,例如上面的 uppercase
。不过这些组件被视为普通 Java 类实例,而不是规范的 Spring Cloud Functions!
The Azure adapter can auto-wire any Spring component, such as the uppercase
above.
But those are treated as plain Java class instances, not as a canonical Spring Cloud Functions!
若要利用 Spring Cloud Function 并访问规范化的函数表示,您需要自动连接 FunctionCatalog
并将其用在处理程序中,例如上面 springCloudFunction()
处理程序中的 functionCatalog
实例。
To leverage Spring Cloud Function and have access to the canonical function representations, you need to auto-wire the FunctionCatalog
and use it in your handler, like the functionCatalog
instance the springCloudFunction()
handler above.
Accessing Azure ExecutionContext
有时需要以 com.microsoft.azure.functions.ExecutionContext
的形式访问 Azure 运行时提供的目标执行上下文。例如,这些需求之一便是日志记录,以便在 Azure 控制台中显示。
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.
为此,AzureFunctionUtil.enhanceInputIfNecessary
允许您添加 ExecutionContext
的实例作为消息头,以便您可以通过 executionContext
键检索该实例。
For that purpose the AzureFunctionUtil.enhanceInputIfNecessary
allow you to add an instance of the ExecutionContext
as a Message header so you can retrieve it via executionContext
key.
@FunctionName("myfunction")
public String execute(
@HttpTrigger(name = "req",
methods = { HttpMethod.POST },
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
ExecutionContext context) {
Message message =
(Message) AzureFunctionUtil.enhanceInputIfNecessary(request.getBody().get(), context); (1)
return this.uppercase.apply(message);
}
1 | Leverages the AzureFunctionUtil utility to inline the context as message header using the AzureFunctionUtil.EXECUTION_CONTEXT header key. |
现在,您可以从消息头中检索 ExecutionContext:
Now you can retrieve the ExecutionContext from message headers:
@Bean
public Function<Message<String>, String> uppercase(JsonMapper mapper) {
return message -> {
String value = message.getPayload();
ExecutionContext context =
(ExecutionContext) message.getHeaders().get(AzureFunctionUtil.EXECUTION_CONTEXT); (1)
. . .
}
}
1 | Retrieve the ExecutionContext instance from the header. |
Configuration
若要在 Microsoft Azure 上运行函数应用程序,您必须提供必要的配置,例如 function.json
和 host.json
,并遵照必需的格式打包。
To run your function applications on Microsoft Azure, you have to provide the necessary configurations, such as function.json
and host.json
, and adhere to the compulsory packaging format.
通常,Azure Maven(或 Gradle)插件用于从带注释的类生成必要的配置并生成所需的 package 格式。
Usually the Azure Maven (or Gradle) plugins are used to generate the necessary configurations from the annotated classes and to produce the required package format.
Azure packaging format 与默认的 Spring Boot 包装(例如 uber jar
)不兼容。下面的 Disable Spring Boot Plugin 部分说明如何处理此问题。
The Azure packaging format is not compatible with the default Spring Boot packaging (e.g. uber jar
).
The Disable Spring Boot Plugin section below explains how to handle this.
[[azure-maven/gradle-plugins]]=== Azure Maven/Gradle 插件
[[azure-maven/gradle-plugins]] === Azure Maven/Gradle Plugins
Azure 提供的 maven 及 gradle 插件用于处理带注释的类、生成必要的配置以及生成预期的 package 布局。插件用于设置平台、运行时和应用程序设置属性,如下所示:
Azure provides Maven and Gradle plugins to process the annotated classes, generate the necessary configurations and produce the expected package layout. Plugins are used to set the platform, runtime and app-settings properties like this:
-
Maven
-
Gradle
<plugin>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-functions-maven-plugin</artifactId>
<version>1.22.0 or higher</version>
<configuration>
<appName>YOUR-AZURE-FUNCTION-APP-NAME</appName>
<resourceGroup>YOUR-AZURE-FUNCTION-RESOURCE-GROUP</resourceGroup>
<region>YOUR-AZURE-FUNCTION-APP-REGION</region>
<appServicePlanName>YOUR-AZURE-FUNCTION-APP-SERVICE-PLANE-NAME</appServicePlanName>
<pricingTier>YOUR-AZURE-FUNCTION-PRICING-TIER</pricingTier>
<hostJson>${project.basedir}/src/main/resources/host.json</hostJson>
<runtime>
<os>linux</os>
<javaVersion>11</javaVersion>
</runtime>
<appSettings>
<property>
<name>FUNCTIONS_EXTENSION_VERSION</name>
<value>~4</value>
</property>
</appSettings>
</configuration>
<executions>
<execution>
<id>package-functions</id>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
plugins {
id "com.microsoft.azure.azurefunctions" version "1.11.0"
// ...
}
apply plugin: "com.microsoft.azure.azurefunctions"
azurefunctions {
appName = 'YOUR-AZURE-FUNCTION-APP-NAME'
resourceGroup = 'YOUR-AZURE-FUNCTION-RESOURCE-GROUP'
region = 'YOUR-AZURE-FUNCTION-APP-REGION'
appServicePlanName = 'YOUR-AZURE-FUNCTION-APP-SERVICE-PLANE-NAME'
pricingTier = 'YOUR-AZURE-FUNCTION-APP-SERVICE-PLANE-NAME'
runtime {
os = 'linux'
javaVersion = '11'
}
auth {
type = 'azure_cli'
}
appSettings {
FUNCTIONS_EXTENSION_VERSION = '~4'
}
// Uncomment to enable local debug
// localDebug = "transport=dt_socket,server=y,suspend=n,address=5005"
}
有关运行时配置的更多信息:Java 版本,部署的操作系统。
More information about the runtime configurations: Java Versions, Deployment OS.
Disable Spring Boot Plugin
可以预料,Azure 函数在 Azure 执行运行时内部运行,而不是在 Spring Boot 运行时内部运行!此外,Azure 期望 Azure Maven/Gradle 插件生成的特定打包格式与默认的 Spring Boot 打包不兼容。
Expectedly, the Azure Functions run inside the Azure execution runtime, not inside the SpringBoot runtime! Furthermore, Azure expects a specific packaging format, generated by the Azure Maven/Gradle plugins, that is not compatible with the default Spring Boot packaging.
您必须禁用 Spring Boot Maven/Gradle 插件或按照以下 Maven 片段中的说明使用 Spring Boot Thin Launcher:
You have to either disable the SpringBoot Maven/Gradle plugin or use the Spring Boot Thin Launcher as shown in this Maven snippet:
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework.boot.experimental</groupId>
<artifactId>spring-boot-thin-layout</artifactId>
</dependency>
</dependencies>
</plugin>
Main-Class Configuration
指定 Main-Class
/Start-Class
指向 Spring 应用程序入口点,例如上面示例中的 HttpTriggerDemoApplication 类。
Specify the Main-Class
/Start-Class
to point to your Spring application entry point, such as the HttpTriggerDemoApplication class in the example above.
您可以使用 Maven 的 start-class
属性或设置 MANIFEST/META-INFO
的 Main-Class
属性:
You can use the Maven start-class
property or set the Main-Class
attribute of your MANIFEST/META-INFO
:
-
Maven
-
Gradle
<properties>
<start-class>YOUR APP MAIN CLASS</start-class>
...
</properties>
jar {
manifest {
attributes(
"Main-Class": "YOUR-APP-MAIN-CLASS"
)
}
}
或者,您可以使用 |
Alternatively you can use the |
如果没有设置 MAIN_CLASS
变量,Azure 适配器将从在类路径上找到的 jar 中查找 MANIFEST/META-INFO
属性,并选择第一个通过 @SpringBootApplication
或 @SpringBootConfiguration
注释标记的 Main-Class:
。
If the MAIN_CLASS
variable is not set, the Azure adapter lookups the MANIFEST/META-INFO
attributes from the jars found on the classpath and selects the first Main-Class:
annotated with either a @SpringBootApplication
or @SpringBootConfiguration
annotation.
Metadata Configuration
您可以使用共享的 host.json 文件来配置函数应用程序。
You can use a shared host.json file to configure the function app.
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
host.json 元数据文件包含影响函数应用程序实例中所有函数的配置选项。
The host.json metadata file contains configuration options that affect all functions in a function app instance.
如果文件不在项目顶级文件夹中,则需要相应地配置你的插件(如 |
If the file is not in the project top folder you need to configure your plugins accordingly (like |
Samples
以下是您可以探索的各种 Spring Cloud Function Azure 适配器示例:
Here is a list of various Spring Cloud Function Azure Adapter samples you can explore:
Azure Web Adapter
对于纯粹基于 Web 的函数应用程序,您可以用专门的 spring-cloud-function-adapter-azure-web 替换通用的 adapter-azure
。Azure Web 适配器可以使用 HttpTrigger 在内部部署任何 Spring Web 应用程序作为本机 Azure 函数。它隐藏了 Azure 注释的复杂性,而是依赖于熟悉的 Spring Web 编程模型。
For, pure, Web-based function applications, you can replace the generic adapter-azure
with the specialized spring-cloud-function-adapter-azure-web.
The Azure Web Adapter can deploy any Spring Web application as a native Azure function, using the HttpTrigger internally.
It hides the Azure annotations complexity and relies on the familiar Spring Web programming model instead.
若要启用 Azure Web 适配器,请向您的 pom.xml
或 build.gradle
文件中添加适配器依赖项:
To enable the Azure Web Adapter, add the adapter dependency to your pom.xml
or build.gradle
files:
-
Maven
-
Gradle
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-function-adapter-azure-web</artifactId>
</dependency>
</dependencies>
dependencies {
implementation 'org.springframework.cloud:spring-cloud-function-adapter-azure-web'
}
相同的 Configuration 和 Usage 指令也适用于 Azure Web Adapter
。
The same Configuration and Usage instructions apply to the Azure Web Adapter
as well.
Azure Samples
有关详细信息,请探索以下内容(Azure Web 适配器)示例:
For further information, explore the following, Azure Web Adapter, sample:
Usage
用于构建和部署“Azure 适配器”和“Azure Web 适配器”类型应用程序的通用说明。
Common instructions for building and deploying both, Azure Adapter
and Azure Web Adapter
type of applications.
Running locally
若要在 `Azure Functions`之上本地运行并部署到您的实时 Azure 环境,您需要安装 `Azure Functions Core Tools`以及 Azure CLI(见 here)。对于某些配置,您还需要 Azurite emulator。
To run locally on top of Azure Functions
, and to deploy to your live Azure environment, you will need Azure Functions Core Tools
installed along with the Azure CLI (see here).
For some configuration you would need the Azurite emulator as well.
然后运行示例:
Then run the sample:
-
Maven
-
Gradle
./mvnw azure-functions:run
./gradlew azureFunctionsRun
Running on Azure
确保您已登录您的 Azure 帐户。
Make sure you are logged in your Azure account.
az login
并部署
and deploy
-
Maven
-
Gradle
./mvnw azure-functions:deploy
./gradlew azureFunctionsDeploy
Debug locally
在调试模式下运行函数。
Run the function in debug mode.
-
Maven
-
Gradle
./mvnw azure-functions:run -DenableDebug
// If you want to debug your functions, please add the following line
// to the azurefunctions section of your build.gradle.
azurefunctions {
...
localDebug = "transport=dt_socket,server=y,suspend=n,address=5005"
}
或者,将 JAVA_OPTS
值设为 local.settings.json
,如下所示:
Alternatively and the JAVA_OPTS
value to your local.settings.json
like this:
{
"IsEncrypted": false,
"Values": {
...
"FUNCTIONS_WORKER_RUNTIME": "java",
"JAVA_OPTS": "-Djava.net.preferIPv4Stack=true -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=127.0.0.1:5005"
}
}
以下是 VSCode
远程调试配置的代码片段:
Here is snippet for a VSCode
remote debugging configuration:
{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Attach to Remote Program",
"request": "attach",
"hostName": "localhost",
"port": "5005"
},
]
}
FunctionInvoker (deprecated)
旧的 FunctionInvoker
编程模型已弃用,并且将来将不受支持。
The legacy FunctionInvoker
programming model is deprecated and will not be supported going forward.
有关函数集成方法的其他文档和示例,请按照 azure-sample中的自述文件和代码进行操作。
For additional documentation and samples about the Function Integration approach follow the azure-sample README and code.