Spring Cloud Azure 参考文档（三）

14.1.5. 示例

有关更多详细信息，请参阅azure-spring-boot-samples。

14.2. Azure 服务总线的春季云流绑定器

14.2.1. 关键概念

适用于 Azure 服务总线的 Spring Cloud Stream Binder 提供 Spring Cloud Stream Framework 的绑定实现。 此实现在其基础上使用 Spring 集成服务总线通道适配器。

定时消息

此绑定器支持将消息提交到主题以进行延迟处理。用户可以发送带有标头的计划消息以毫秒为单位表示消息的延迟时间。消息将在毫秒后传递到相应的主题。x-delayx-delay

消费群体

服务总线主题提供与 Apache Kafka 类似的使用者组支持，但逻辑略有不同。 此活页夹依赖于主题来充当使用者组。​​Subscription​​

14.2.2. 依赖设置

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-stream-binder-servicebus</artifactId>
</dependency>

或者，也可以使用 Spring Cloud Azure Stream Service Bus Startter，如以下 Maven 示例所示：

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-stream-servicebus</artifactId>
</dependency>

14.2.3. 配置

绑定程序提供以下 2 个配置选项部分：

连接配置属性

本部分包含用于连接到 Azure 服务总线的配置选项。

如果选择使用安全主体对 Azure Active Directory 进行身份验证和授权以访问 Azure 资源，请参阅使用 Azure AD 授权访问，以确保已向安全主体授予访问 Azure 资源的足够权限。

Table 31. Connection configurable properties of spring-cloud-azure-stream-binder-servicebus

财产	类型	描述
spring.cloud.azure.servicebus.enabled	布尔	是否启用了 Azure 服务总线。
spring.cloud.azure.servicebus.connection-string	字符串	服务总线命名空间连接字符串值。
spring.cloud.azure.servicebus.namespace	字符串	服务总线命名空间值，它是 FQDN 的前缀。FQDN 应由 <命名空间名称>.<域名>组成
spring.cloud.azure.servicebus.domain-name	字符串	Azure 服务总线命名空间值的域名。

常见的 Azure 服务 SDK 配置选项也可以为 Spring Cloud Azure Stream Service Bus 绑定器进行配置。支持的配置选项在“配置”页​中介绍，可以使用统一前缀前缀进行配置。​​spring.cloud.azure.​​​​spring.cloud.azure.servicebus.​​

默认情况下，绑定器还支持Spring Can Azure资源管理器。若要了解如何使用未授予相关角色的安全主体检索连接字符串，请参阅资源管理器示例以了解详细信息。Data

Azure 服务总线绑定配置属性

以下选项分为四个部分：消费者属性、高级消费者 配置、创建者属性和高级创建者配置。

消费者属性

这些属性通过以下方式公开。​​ServiceBusConsumerProperties​​

Table 32. Consumer configurable properties of spring-cloud-azure-stream-binder-servicebus

财产	类型	违约	描述
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.requeue-reject	布尔	假	如果失败的消息被路由到 DLQ。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.max-concurrent-calls	整数	1	服务总线处理器客户端应处理的最大并发消息数。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.max-concurrent-sessions	整数	零	在任何给定时间要处理的最大并发会话数。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.session-enabled	布尔	零	是否启用会话。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.prefetch-count	整数	0	服务总线处理器客户端的预取计数。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.sub-queue	子队列	没有	要连接到的子队列的类型。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.max-auto-lock-renew-duration	期间	5米	继续自动续订锁的时间量。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.receive-mode	ServiceBusReceiveMode	peek_lock	服务总线处理器客户端的接收模式。
spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.auto-complete	布尔	真	是否自动结算邮件。如果设置为 false，则添加邮件头 使开发人员能够手动结算消息。​​Checkpointer​​

高级消费者配置

支持为每个绑定程序使用者自定义上述连接和常见的 Azure SDK 客户端配置，可以使用前缀进行配置。spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.

生产者属性

这些属性通过以下方式公开。​​ServiceBusProducerProperties​​

Table 33. Producer configurable properties of spring-cloud-azure-stream-binder-servicebus

财产	类型	违约	描述
spring.cloud.stream.servicebus.bindings.<binding-name>.producer.sync	布尔	假	开关标志 用于制作人的同步。
spring.cloud.stream.servicebus.bindings.<binding-name>.producer.send-timeout	长	10000	超时 发送生产者的价值。
spring.cloud.stream.servicebus.bindings.<binding-name>.producer.entity-type	服务总线实体类型	零	生成者的服务总线实体类型，绑定生成者需要。

使用绑定生产者时，需要配置属性 of。​​spring.cloud.stream.servicebus.bindings.<binding-name>.producer.entity-type​​

高级生产者配置

支持为每个绑定器生成器自定义上述连接和常见的 Azure SDK 客户端配置，可以使用前缀进行配置。spring.cloud.stream.servicebus.bindings.<binding-name>.producer.

14.2.4. 基本用法

从/向服务总线发送和接收消息

第 1 步。使用凭据信息填充配置选项。

• 对于作为连接字符串的凭据，请在 application.yml 中配置以下属性：

spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${SERVICEBUS_NAMESPACE_CONNECTION_STRING}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${SERVICEBUS_ENTITY_NAME}
          # If you use Service Bus Topic, please add the following configuration
          # group: ${SUBSCRIPTION_NAME}
        supply-out-0:
          destination: ${SERVICEBUS_ENTITY_NAME_SAME_AS_ABOVE}
      servicebus:
        bindings:
          consume-in-0:
            consumer:
              auto-complete: false
          supply-out-0:
            producer:
              entity-type: queue # set as "topic" if you use Service Bus Topic

• 对于作为服务主体的凭据，请在 application.yml 中配置以下属性：

spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${SERVICEBUS_ENTITY_NAME}
          # If you use Service Bus Topic, please add the following configuration
          # group: ${SUBSCRIPTION_NAME}
        supply-out-0:
          destination: ${SERVICEBUS_ENTITY_NAME_SAME_AS_ABOVE}
      servicebus:
        bindings:
          consume-in-0:
            consumer:
              auto-complete: false
          supply-out-0:
            producer:
              entity-type: queue # set as "topic" if you use Service Bus Topic

• 对于作为托管标识的凭据，请在 application.yml 中配置以下属性：

spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${MANAGED_IDENTITY_CLIENT_ID} # Only needed when using a user-assigned managed identity
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${SERVICEBUS_ENTITY_NAME}
          # If you use Service Bus Topic, please add the following configuration
          # group: ${SUBSCRIPTION_NAME}
        supply-out-0:
          destination: ${SERVICEBUS_ENTITY_NAME_SAME_AS_ABOVE}
      servicebus:
        bindings:
          consume-in-0:
            consumer:
              auto-complete: false
          supply-out-0:
            producer:
              entity-type: queue # set as "topic" if you use Service Bus Topic

第 2 步。定义供应商和消费者。

@Bean
public Consumer<Message<String>> consume() {
    return message -> {
        Checkpointer checkpointer = (Checkpointer) message.getHeaders().get(CHECKPOINTER);
        LOGGER.info("New message received: '{}'", message.getPayload());

        checkpointer.success()
                .doOnSuccess(success -> LOGGER.info("Message '{}' successfully checkpointed", message.getPayload()))
                .doOnError(error -> LOGGER.error("Exception found", error))
                .block();
    };
}

@Bean
public Supplier<Message<String>> supply() {
    return () -> {
        LOGGER.info("Sending message, sequence " + i);
        return MessageBuilder.withPayload("Hello world, " + i++).build();
    };
}

分区键支持

绑定程序允许在消息标头中设置分区键和会话 ID，从而支持服务总线分区。本节介绍如何设置消息的分区键。

Spring Cloud Stream 提供分区键 SpEL 表达式属性。例如，将此属性设置为 并添加一个名为 <message-header-key> 的标头。Spring Cloud Stream 在计算上述表达式以分配分区键时将使用此标头的值。下面是一个示例生产者代码：​​spring.cloud.stream.bindings.<binding-name>.producer.partition-key-expression​​​​"'partitionKey-' + headers[<message-header-key>]"​​

@Bean
public Supplier<Message<String>> generate() {
    return () -> {
        String value = “random payload”;
        return MessageBuilder.withPayload(value)
            .setHeader("<message-header-key>", value.length() % 4)
            .build();
    };
}

会话支持

绑定程序支持服务总线的消息会话。 可以通过消息标头设置消息的会话 ID。

@Bean
public Supplier<Message<String>> generate() {
    return () -> {
        String value = “random payload”;
        return MessageBuilder.withPayload(value)
            .setHeader(ServiceBusMessageHeaders.SESSION_ID, "Customize session id")
            .build();
    };
}

根据服务总线分区​，会话 ID 的优先级高于分区键。因此，当设置了两个 ofand（或） 标头时， 会话 ID 的值最终将用于覆盖分区键的值。​​ServiceBusMessageHeaders#SESSION_ID​​​​ServiceBusMessageHeaders#PARTITION_KEY​​​​AzureHeaders#PARTITION_KEY​​

错误通道

• 使用者错误通道

默认情况下，此通道处于打开状态，并且默认的使用者错误通道处理程序用于在启用时将失败的消息发送到死信队列，否则将放弃失败的消息。​​spring.cloud.stream.servicebus.bindings.<binding-name>.consumer.requeue-rejected​​

若要自定义使用者错误通道处理程序，可以通过以下方式将自己的错误处理程序注册到相关的使用者错误通道：

// Replace destination with spring.cloud.stream.bindings.input.destination
// Replace group with spring.cloud.stream.bindings.input.group
@ServiceActivator(inputChannel = "{destination}.{group}.errors")
public void consumerError(Message<?> message) {
    LOGGER.error("Handling customer ERROR: " + message);
}

• 生产者错误通道

默认情况下，此通道不打开。您需要在 application.properties 中添加配置以启用它，如下所示：

spring.cloud.stream.default.producer.errorChannelEnabled=true

您可以通过以下方式处理错误消息：

// Replace destination with spring.cloud.stream.bindings.output.destination
@ServiceActivator(inputChannel = "{destination}.errors")
public void producerError(Message<?> message) {
    LOGGER.error("Handling Producer ERROR: " + message);
}

• 全局默认错误通道

默认情况下，Spring 集成会创建一个名为“errorChannel”的全局错误通道，该通道允许用户为其订阅许多端点。

@ServiceActivator(inputChannel = "errorChannel")
public void producerError(Message<?> message) {
    LOGGER.error("Handling ERROR: " + message);
}

服务总线消息标头

有关支持的基本消息标头，请参阅服务总线消息标头。

设置 partiton 键时，消息头的优先级高于 Spring Cloud 流属性。因此，只有在未配置 ，，的任何标头时才会生效。​​spring.cloud.stream.bindings.<binding-name>.producer.partition-key-expression​​​​ServiceBusMessageHeaders#SESSION_ID​​​​ServiceBusMessageHeaders#PARTITION_KEY​​​​AzureHeaders#PARTITION_KEY​​

多种粘合剂支持

使用多个绑定程序还支持连接到多个服务总线命名空间。此示例以连接字符串为例。还支持服务主体和托管标识的凭据，用户可以在每个绑定程序的环境设置中设置相关属性。

第 1 步。若要使用服务总线的多个绑定程序，我们需要在 application.yml 中配置以下属性

spring:
  cloud:
    stream:
      function:
        definition: consume1;supply1;consume2;supply2
      bindings:
        consume1-in-0:
          destination: ${SERVICEBUS_TOPIC_NAME}
          group: ${SUBSCRIPTION_NAME}
        supply1-out-0:
          destination: ${SERVICEBUS_TOPIC_NAME_SAME_AS_ABOVE}
        consume2-in-0:
          binder: servicebus-2
          destination: ${SERVICEBUS_QUEUE_NAME}
        supply2-out-0:
          binder: servicebus-2
          destination: ${SERVICEBUS_QUEUE_NAME_SAME_AS_ABOVE}
      binders:
        servicebus-1:
          type: servicebus
          default-candidate: true
          environment:
            spring:
              cloud:
                azure:
                  servicebus:
                    connection-string: ${SERVICEBUS_NAMESPACE_01_CONNECTION_STRING}
        servicebus-2:
          type: servicebus
          default-candidate: false
          environment:
            spring:
              cloud:
                azure:
                  servicebus:
                    connection-string: ${SERVICEBUS_NAMESPACE_02_CONNECTION_STRING}
      servicebus:
        bindings:
          consume1-in-0:
            consumer:
              auto-complete: false
          supply1-out-0:
            producer:
              entity-type: topic
          consume2-in-0:
            consumer:
              auto-complete: false
          supply2-out-0:
            producer:
              entity-type: queue
      poller:
        initial-delay: 0
        fixed-delay: 1000

第 2 步。我们需要定义两个供应商和两个消费者

@Bean
public Supplier<Message<String>> supply1() {
    return () -> {
        LOGGER.info("Sending message1, sequence1 " + i);
        return MessageBuilder.withPayload("Hello world1, " + i++).build();
    };
}

@Bean
public Supplier<Message<String>> supply2() {
    return () -> {
        LOGGER.info("Sending message2, sequence2 " + j);
        return MessageBuilder.withPayload("Hello world2, " + j++).build();
    };
}

@Bean
public Consumer<Message<String>> consume1() {
    return message -> {
        Checkpointer checkpointer = (Checkpointer) message.getHeaders().get(CHECKPOINTER);
        LOGGER.info("New message1 received: '{}'", message);
        checkpointer.success()
                .doOnSuccess(s -> LOGGER.info("Message '{}' successfully checkpointed", message.getPayload()))
                .doOnError(e -> LOGGER.error("Error found", e))
                .block();
    };
}

@Bean
public Consumer<Message<String>> consume2() {
    return message -> {
        Checkpointer checkpointer = (Checkpointer) message.getHeaders().get(CHECKPOINTER);
        LOGGER.info("New message2 received: '{}'", message);
        checkpointer.success()
                .doOnSuccess(s -> LOGGER.info("Message '{}' successfully checkpointed", message.getPayload()))
                .doOnError(e -> LOGGER.error("Error found", e))
                .block();
    };

}

资源提供

服务总线绑定程序支持预配队列、主题和订阅，用户可以使用以下属性来启用预配。

spring:
  cloud:
    azure:
      credential:
        tenant-id: ${AZURE_TENANT_ID}
      profile:
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      servicebus:
        resource:
          resource-group: ${AZURE_SERVICEBUS_RESOURECE_GROUP}
    stream:
      servicebus:
        bindings:
          <binding-name>:
            consumer:
              entity-type: ${SERVICEBUS_CONSUMER_ENTITY_TYPE}

14.2.5. 示例

有关更多详细信息，请参阅azure-spring-boot-samples。

15. 春季 JMS 支持

通过集成到 Spring JMS 框架中的 JMS API 使用 Azure 服务总线。 必须提供 Azure 服务总线连接字符串，该字符串将解析为 AMQP 代理的登录用户名、密码和远程 URI。

15.1. 依赖设置

如果要迁移 Spring JMS 应用程序以使用 Azure 服务总线，请添加以下依赖项。

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-servicebus-jms</artifactId>
</dependency>

15.2. 配置

Table 34. Configurable properties when using Spring JMS support

财产	描述
spring.jms.servicebus.connection-string	Azure 服务总线连接字符串。当想要直接提供连接字符串时，应提供。
spring.jms.servicebus.topic-client-id	JMS 客户机标识。仅适用于 topicJmsListenerContainerFactory 的 bean。
spring.jms.servicebus.idle-timeout	空闲的持续时间。
spring.jms.servicebus.pricing-tier	Azure 服务总线价格层。
spring.jms.servicebus.listener.reply-pub-sub-domain	回复目标类型是否为主题。
spring.jms.servicebus.listener.phase	指定应在其中启动和停止此容器的阶段。
spring.jms.servicebus.listener.reply-qos-settings	配置发送答复时要使用的 Qos设置。
spring.jms.servicebus.listener.subscription-durable	是否使订阅持久。仅适用于 topicJmsListenerContainerFactory 的 bean。
spring.jms.servicebus.listener.subscription-shared	是否共享订阅。仅适用于 topicJmsListenerContainerFactory 的 bean。
spring.jms.servicebus.password	AMQP经纪商的登录密码
spring.jms.servicebus.pool.block-if-full	在请求连接且池已满时是否阻止。
spring.jms.servicebus.pool.block-if-full-timeout	如果池仍已满，则引发异常之前的阻塞期。
spring.jms.servicebus.pool.enabled	是否应该创建 JmsPoolConnectionFactory，而不是常规的连接工厂。
spring.jms.servicebus.pool.idle-timeout	连接空闲超时。
spring.jms.servicebus.pool.max-connections	池连接的最大数量。
spring.jms.servicebus.pool.max-sessions-per-connection	池中每个连接的最大池会话数。
spring.jms.servicebus.pool.time-between-expiration-check	空闲连接逐出线程运行之间的睡眠时间。
spring.jms.servicebus.pool.use-anonymous-producer	是否只使用一个匿名的“消息生产者”实例。
spring.jms.servicebus.prefetch-policy.all	此服务总线命名空间中预提取选项的回退值。
spring.jms.servicebus.prefetch-policy.durable-topic-prefetch	持久主题的预取数。
spring.jms.servicebus.prefetch-policy.queue-browser-prefetch	队列浏览器的预取数。
spring.jms.servicebus.prefetch-policy.queue-prefetch	队列的预取数。
spring.jms.servicebus.prefetch-policy.topic-prefetch	主题的预取数。
spring.jms.servicebus.remote-url	AMQP 代理的网址。
spring.jms.servicebus.username	AMQP 代理的登录用户。

Spring JMS 常规配置简称省略。 有关更多详细信息，请参阅Spring JMS 文档。

15.3. 基本用法

15.3.1. 使用服务总线连接字符串

连接到 Spring JMS 应用程序服务总线的最简单方法是使用连接字符串。

添加以下属性，您就可以开始了。

spring:
  jms:
    servicebus:
      connection-string: ${AZURE_SERVICEBUS_CONNECTION_STRING}
      pricing-tier: ${PRICING_TIER}

默认启用是添加会话缓存以及消息生产者缓存。如果要激活 JmsPoolConnectionFactory 之一的连接池，则应指定属性 。您可以从上面的配置部分找到其他池配置​选项（带前缀的属性）。​​ConnectionFactory​​​​CachingConnectionFactory​​​​spring.jms.servicebus.pool.enabled​​​​true​​​​spring.jms.servicebus.pool.​​

15.4. 示例

有关更多详细信息，请参阅azure-spring-boot-samples。

16. 春季原生支持

16.1. 春季原生

Spring Native 支持使用GraalVM​ 本机映像编译器将 Spring Boot 应用程序编译为本机​可执行文件。本机映像将带来许多优势，例如即时启动、即时峰值性能和减少内存消耗。一些Spring Cloud Azure功能也可以从Spring Native支持中受益，目标是Spring Cloud Azure应用程序可以构建为本机映像，而无需任何代码修改。有关更多信息，请参阅Spring Native 文档。

16.2. 支持

Spring Cloud Azure已经过GraalVM和Spring Native的验证，并提供测试版支持。如果项目使用这些受支持的依赖项，则可以在项目上尝试它，并在Spring Cloud Azure上出现问题时引发错误​或贡献拉取请求​。有关更多信息，请参阅Spring 本机支持以获取更多详细信息。

16.2.1. 春季原生

Spring CloudAzure 4.4.1已针对 Spring Native 和 GraalVM 进行了测试。0.11.422.0.0

16.2.2. 春季云 Azure 原生

Spring Native 已针对 Spring Cloud Azure Native Configuration 进行了测试。​​0.11.4​​​​4.0.0-beta.1​​

Spring Cloud Azure 提供了一个依赖项，它是 Spring Cloud Azure 库的 Spring Native 配置的扩展。Spring Native AOT 插件将把构建应用程序合并到原生可执行文件中。除了添加依赖项之外，不需要对使用 Spring Cloud Azure 库的代码进行任何额外的修改，该依赖项仅适用于 Spring Cloud Azure 库中的代码。​​spring-cloud-azure-native-configuration​​​​spring-native-configuration​​​​spring-cloud-azure-native-configuration​​

支持以下功能：

• ​​Azure App Configuration clients auto-configuration​​
• ​​Azure Event Hubs clients auto-configuration​​
• ​​Azure Key Vault Certificates clients auto-configuration​​
• ​​Azure Key Vault Secrets clients auto-configuration​​
• ​​Azure Storage Blob clients auto-configuration​​
• ​​Azure Storage File Share clients auto-configuration​​
• ​​Azure Storage Queue clients auto-configuration​​
• ​​Spring Integration for Azure Event Hubs​​
• ​​Spring Integration for Azure Storage Queue​​

16.2.3. 限制

Spring Cloud Azure 对 Spring Native 的支持仍处于早期阶段，并将继续更新。尚不支持以下功能：

• ​​Azure Cosmos clients auto-configuration​​
• ​​Azure Service Bus clients auto-configuration​​
• ​​Spring Data for Azure Cache for Redis​​
• ​​Spring Data for Azure Cosmos​​
• ​​Spring Cloud Stream for Azure Event Hubs​​
• ​​Spring Cloud Stream for Azure Service Bus​​
• ​​Spring Kafka for Azure Event Hubs​​
• ​​Spring Integration for Azure Service Bus​​

Spring Native 并非支持所有本机映像选项。有关更多信息，请参阅 Spring 本机文档的本机映像选项部分。

Spring Cloud Azure4.4.1未经过验证，无法基于 Gradle Kotlin 构建本机可执行文件。

16.3. 项目设置

Spring Cloud Azure 应用程序可以按照 Spring Native 文档的入门部分中的说明启用 Spring Native 支持。唯一需要的附加处理是将以下依赖项添加到 POM 文件。

依赖项未在中管理。​​com.azure.spring:spring-cloud-azure-native-configuration​​​​com.azure.spring:spring-cloud-azure-dependencies​​

马文

格拉德尔·格鲁维

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-native-configuration</artifactId>
    <version>4.0.0-beta.1</version>
  </dependency>

16.4. 构建原生应用程序

以下部分介绍了使用 Spring Cloud Azure 库构建 Spring Boot 本机应用程序的两种主要方法。

16.4.1. 使用构建包构建

本机应用程序可以按如下方式构建：

马文

格拉德尔·格鲁维

mvn spring-boot:build-image

有关更多信息，请参阅 Spring Native 文档中的构建包入门部分。

16.4.2. 使用原生构建工具构建

可以使用以下命令生成本机应用程序：

马文

格拉德尔·格鲁维

mvn -Pnative -DskipTests package

有关更多信息，请参阅 Spring 原生文档的原生构建工具入门部分。

16.5. 运行本机应用程序

以下各节介绍运行本机可执行文件的两种主要方法。

假设项目工件 ID 为，项目版本为，则可以通过以下方式之一指定自定义映像名称： 如果您使用的是云原生构建包​，请使用 Spring 启动插件中的→'name'→'custom-image-name' 配置元素。如果您使用的是GraalVM 本机构建工具​，请使用 Spring Boot 插件中的→'自定义映像名称'配置元素。​​spring-cloud-azure-sample​​​​0.0.1-SNAPSHOT​​​​image​​​​imageName​​

16.5.1. 使用构建包运行

若要运行应用程序，可以使用以下示例中所示的常用方式：​​docker​​

docker run --rm -p 8080:8080 spring-cloud-azure-sample:0.0.1-SNAPSHOT

16.5.2. 使用本机构建工具运行

若要运行应用程序，请使用以下命令：

使用 Maven 构建

使用 Gradle 构建

target\spring-cloud-azure-sample

16.6. 示例

有关详细信息，请参阅 GitHub 上的存储 blob-native。

下面是支持 Spring Native 的其他经过验证的示例。有关更多信息，请参阅 GitHub 上的Spring Cloud Azure 示例。

Table 35. Supported Spring Cloud Azure Samples

库工件 ID	支持的示例项目
spring-cloud-azure-starter-appconfiguration	应用程序配置客户端
春季-云-Azure-启动器-事件中心	事件中心客户端
春季-云-Azure-启动器-集成-事件中心	事件中心集成
春天-云-Azure-启动器-集成-存储-队列	存储队列集成​，存储队列操作
弹簧-云-Azure-启动器-密钥保管库-机密	属性源​，机密客户端
spring-cloud-azure-starter-storage-blob	存储 blob 示例
弹簧-云-Azure-启动器-存储-文件共享	存储文件示例
弹簧-云-Azure-启动器-存储-队列	存储队列客户端

17. 卡夫卡支持

从版本 4.3.0 开始，Spring Cloud Azure for Kafka 支持各种类型的凭据进行身份验证并连接到 Azure 事件中心。

17.1. 支持的卡夫卡版本

当前版本的启动器应与使用 Java 8 或更高版本的 Apache Kafka Clients 2.0.0 兼容。

17.2. 支持的认证类型

支持以下身份验证类型：

• 普通连接字符串身份验证

• 直接连接字符串身份验证
• 基于 ARM 的连接字符串身份验证

• OAuth 凭据身份验证

• 托管标识身份验证
• 用户名/密码身份验证
• 服务主体身份验证
• DefautlAzureCredential authentication

17.3. 工作原理

17.3.1. OAuth 凭证认证

本节介绍Spring Cloud Azure OAuth身份验证的整体工作流程。

Spring Cloud Azure 将首先根据应用程序身份验证配置构建以下类型的凭据之一：

• ​​ClientSecretCredential​​
• ​​ClientCertificateCredential​​
• ​​UsernamePasswordCredential​​
• ​​ManagedIdentityCredential​​

如果未找到这些类型的凭据，则将使用凭据链 via 从应用程序属性、环境变量、托管标识或 IDE 获取凭据。有关详细信息，请参阅身份验证部分。DefaultAzureTokenCredential

17.3.2. 纯连接字符串认证

对于连接字符串身份验证模式，可以直接使用连接字符串身份验证，也可以使用 Azure 资源管理器检索连接字符串。有关用法的详细信息，请参阅连接字符串身份验证的基本用法部分。

从版本 4.3.0 开始，不推荐使用连接字符串身份验证，转而使用 OAuth 身份验证。

17.4. 配置

17.4.1. 将 Kafka 支持与 OAuth 身份验证结合使用时的可配置属性

Spring Cloud Azure for Kafka 支持以下两个级别的配置选项：

1. Spring Cloud Azure for Event Hubs Kafka properties.
2. 的全局身份验证配置选项 和前缀。credentialprofilespring.cloud.azure
3. 特定于 Kafka 的级别配置。Kafka 级别的配置也可用于 Spring Boot 和 Spring Cloud Stream 绑定器，用于,,, orscope，它们具有不同的前缀。commonconsumerproduceradmin

全局属性通过以下方式公开。特定于 Kafka 的属性通过 （Spring Boot） 和 （Spring Cloud Stream binder） 公开。​​com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties​​​​org.springframework.boot.autoconfigure.kafka.KafkaProperties​​​​org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties​​

以下列表显示了所有受支持的配置选项。

• Spring Cloud Azure 全局身份验证配置选项

• 前缀：spring.cloud.azure
• 支持的选项：，​spring.cloud.azure.profile.​spring.cloud.azure.credential.​

有关全局配置选项的完整列表，请参阅全局属性部分。

• 弹簧启动卡夫卡常用配置

• 前缀：spring.kafka.properties.azure
• 示例：.凭据。spring.kafka.properties.azure

• Spring Kafka 消费者配置选项

• 前缀：spring.kafka.consumer.properties.azure
• 示例：.凭据。spring.kafka.consumer.properties.azure

• 春季卡夫卡生产者配置选项

• 前缀：spring.kafka.producer.properties.azure
• 示例：.凭据。spring.kafka.producer.properties.azure

• Spring Kafka 管理员配置选项

• 前缀：spring.kafka.admin.properties.azure
• 示例：.凭据。spring.kafka.admin.properties.azure

• 春云流卡夫卡活页夹常用配置

• 前缀：spring.cloud.stream.kafka.binder.configuration.azure
• 示例：.凭据。spring.cloud.stream.kafka.binder.configuration.azure

• 春云流卡夫卡绑定器消费者配置

• 前缀：spring.cloud.stream.kafka.binder.consumer-properties.azure
• 示例：.凭据。spring.cloud.stream.kafka.binder.consumer-properties.azure

• 春云流卡夫卡活页夹生产者配置

• 前缀：spring.cloud.stream.kafka.binder.producer-properties.azure
• 示例：.凭据。spring.cloud.stream.kafka.binder.producer-properties.azure

• Spring Cloud Stream Kafka Binder 管理员配置

• 前缀：不支持，应使用 Spring Boot Kafka 通用或管理员配置。

Table 36. Spring Boot Kafka common configuration options

财产	描述
spring.kafka.properties.azure.credential.client-certificate-password	证书文件的密码。
spring.kafka.properties.azure.credential.client-certificate-path	使用 Azure 执行服务主体身份验证时要使用的 PEM 证书文件的路径。
spring.kafka.properties.azure.credential.client-id	使用 Azure 执行服务主体身份验证时要使用的客户端 ID。这是一个旧属性。
spring.kafka.properties.azure.credential.client-secret	使用 Azure 执行服务主体身份验证时要使用的客户端密码。这是一个旧属性。
spring.kafka.properties.azure.credential.managed-identity-enabled	是否启用托管标识以向 Azure 进行身份验证。如果设置为true并且设置了客户端 ID，则将使用客户端 ID 作为用户分配的托管标识客户端 ID。默认值为false。​​client-id​​
spring.kafka.properties.azure.credential.password	使用 Azure 执行用户名/密码身份验证时使用的密码。
spring.kafka.properties.azure.credential.username	使用 Azure 执行用户名/密码身份验证时要使用的用户名。
spring.kafka.properties.azure.profile.environment.active-directory-endpoint	要连接到的 Azure Active Directory 终结点。
spring.kafka.properties.azure.profile.tenant-id	Azure 资源的租户 ID。

不同级别的配置选项应用以下规则。更具体的配置选项比常见配置选项具有更高的优先级。例如： Spring Kafka 通用配置选项取代了全局选项。 Spring Kafka 消费者配置选项取代了通用选项。 Spring Kafka 生产者配置选项取代了通用选项。 Spring Kafka 管理员配置选项取代了通用选项。 Spring Cloud Stream Kafka Binder 选项与上述选项类似。

17.4.2. 使用 Kafka 支持和普通连接字符串身份验证时的可配置属性

Table 37. Spring Boot Event Hubs for Kafka common configuration options

财产	描述
spring.cloud.azure.eventhubs.kafka.enabled	是否启用 Azure 事件中心 Kafka 支持。默认值为true。
spring.cloud.azure.eventhubs.connection-string	Azure 事件中心连接字符串。如果要直接提供连接字符串，请提供此值。
spring.cloud.azure.eventhubs.namespace	Azure 事件中心命名空间。如果要通过 Azure 资源管理器检索连接信息，请提供此值。
spring.cloud.azure.eventhubs.resource.resource-group	Azure 事件中心命名空间的资源组。如果要通过 Azure 资源管理器检索连接信息，请提供此值。
spring.cloud.azure.profile.subscription-id	订阅 ID。 如果要通过 Azure 资源管理器检索连接信息，请提供此值。

17.5. 依赖设置

将以下依赖项添加到项目中。这将自动将依赖项传递地包含在项目中。​​spring-boot-starter​​

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

请记住将 BOM 与上述依赖项一起添加。有关详细信息，请参阅入门​部分。​​spring-cloud-azure-dependencies​​

17.6. 基本用法

以下各节显示了经典的 Spring 引导应用程序使用场景。

17.6.1. 使用 OAuth 认证

当您使用 Spring Cloud Azure for Kafka 提供的 OAuth 身份验证时，您可以使用上述配置配置特定凭据。或者，您可以选择不配置任何有关凭据的内容，在这种情况下，Spring Cloud Azure 将从环境中加载凭据。本部分介绍从 Azure CLI 环境或 Azure Spring 应用托管环境加载凭据的用法。

如果选择使用安全主体对 Azure Active Directory 进行身份验证和授权以访问 Azure 资源，请参阅授权访问 Azure Active Directory 部分，以确保已向安全主体授予访问 Azure资源的足够权限。

以下部分描述了使用具有OAuth身份验证的不同Spring生态系统库的场景。

春季卡夫卡应用支持

本节描述了使用 Spring Kafka 或 Spring Integration Kafka 库的 Spring 引导应用程序的使用场景。

依赖项设置

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<!-- Using Spring Kafka library only-->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:2.8.6-->
</dependency>
<!-- Using Spring Integration library only -->
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:5.5.12-->
</dependency>

配置更新

若要使用 OAuth 身份验证，只需指定事件中心终结点，如以下示例所示：

spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093

春云流活页夹卡夫卡应用支持

本节介绍使用 Spring Cloud Stream binder Kafka 库的 Spring 引导应用程序的使用场景。

依赖项设置

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-stream-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:3.2.3-->
</dependency>

配置

若要使用 OAuth 身份验证，只需指定事件中心终结点，如以下示例所示：​​com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration​​

spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093
spring.cloud.stream.binders.kafka.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration

如果您使用的是版本，请不要忘记设置属性以启用整个 OAuth 身份验证工作流，其中默认情况下在单个 Kafka 绑定器应用程序中。该配置指定 的 OAuth 安全参数，这些参数用于启用 Azure 标识。对于之后的版本，此属性将自动添加到每个 Kafka 绑定程序环境，因此无需手动添加它。​​4.3.0​​​​spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration​​​​kafka-binder-name​​​​kafka​​​​AzureKafkaSpringCloudStreamConfiguration​​​​KafkaBinderConfigurationProperties​​​​KafkaOAuth2AuthenticateCallbackHandler​​​​4.4.0​​

样品

请参阅 GitHub 上的azure-spring-boot-samples存储库。

17.6.2. 使用连接字符串身份验证

可以直接使用连接字符串身份验证，也可以使用 Azure 资源管理器检索连接字符串。

从版本 4.3.0 开始，不推荐使用连接字符串身份验证，转而使用 OAuth 身份验证。从 4.4.1 版本开始，将连接字符串身份验证与 Spring Cloud Stream 框架一起使用时，需要以下属性来确保连接字符串可以生效，其中 ​​<kafka-binder-name>​​占位符的值默认为 of。​​kafka​​​​spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration​​

依赖项设置

如果要迁移 Apache Kafka 应用程序以使用适用于 Kafka 的 Azure 事件中心，请添加以下依赖项。

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

如果要使用 Azure 资源管理器检索连接字符串，请添加以下依赖项：

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>

配置

直接使用事件中心连接字符串

连接到 Kafka 事件中心的最简单方法是使用连接字符串。只需添加以下属性。

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

使用 Azure 资源管理器检索连接字符串

如果不想在应用程序中配置连接字符串，可以使用 Azure 资源管理器检索连接字符串。若要使用 Azure 资源管理器进行身份验证，还可以使用存储在 Azure CLI 或其他本地开发工具（如 Visual Studio Code 或 Intellij IDEA）中的凭据。或者，如果应用程序部署到 Azure 云，则可以使用托管标识。只需确保主体具有足够的权限来读取资源元数据。

如果选择使用安全主体对 Azure Active Directory 进行身份验证和授权以访问 Azure 资源，请参阅授权访问 Azure Active Directory 部分，以确保已向安全主体授予访问 Azure资源的足够权限。

若要使用 Azure 资源管理器检索连接字符串，只需添加以下属性。

spring:
  cloud:
    azure:
      profile:
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${AZURE_EVENTHUBS_NAMESPACE}
        resource:
          resource-group: ${AZURE_EVENTHUBS_RESOURCE_GROUP}

17.7. 示例

请参阅 GitHub 上的azure-spring-boot-samples存储库。

18. 红地思支持

使用 Spring Redis 库连接到适用于 Redis 的 Azure 缓存。通过向应用程序添加和，可以通过 Azure 资源管理器读取适用于 Redis 的 Azure 缓存连接信息，并自动配置 Redis 属性。spring-cloud-azure-starterspring-cloud-azure-resourcemanager

18.1. 依赖设置

如果要使用 Redis 将 Spring Cloud Azure Redis 支持用于 Spring Boot 应用程序，请添加以下依赖项。

<dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter</artifactId>
    </dependency>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-resourcemanager</artifactId>
    </dependency>
</dependencies>

18.2. 配置

如果选择使用安全主体通过 Azure Active Directory 进行身份验证和授权以访问 Azure 资源，请参阅通过 AzureAD 授权访问，以确保已向安全主体授予访问 Azure 资源的足够权限。

Table 38. Configurable properties when using Redis support

财产	描述	默认值	必填
spring.cloud.azure.redis.enabled	指示是否启用了适用于 Redis 的 Azure 缓存的值。	真	不
spring.cloud.azure.redis.name	Azure Cache for Redis 实例名称。		是的
spring.cloud.azure.redis.resource.resource-group	适用于 Redis 的 Azure 缓存的资源组。		是的
spring.cloud.azure.profile.subscription-id	订阅 ID。		是的

对 Azure 资源管理器进行身份验证还需要身份验证信息。资源管理器的凭据相关配置应在前缀下配置。有关详细信息，请参阅身份验证​部分。​​spring.cloud.azure​​

18.3. 基本用法

添加以下属性，您就可以开始了。

spring.cloud.azure.redis.name=${AZURE_CACHE_REDIS_NAME}
spring.cloud.azure.redis.resource.resource-group=${AZURE_CACHE_REDIS_RESOURCE_GROUP}

18.4. 示例

有关更多详细信息，请参阅azure-spring-boot-samples。

19. Azure 资源管理器

Azure 资源管理器 （ARM） 是 Azure 的部署和管理服务。它提供了一个管理层，使你能够在 Azure 帐户中创建、更新和删除资源。Spring Cloud Azure 资源管理器可以帮助预配资源或检索资源元数据。

19.1. 依赖设置

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>

19.2. 配置

如果选择使用安全主体通过 Azure Active Directory 进行身份验证和授权以访问 Azure 资源，请参阅通过 AzureAD 授权访问，以确保已向安全主体授予访问 Azure 资源的足够权限。

Table 39. Configurable properties of spring-cloud-azure-resourcemanager

财产	描述
spring.cloud.azure.resource-manager.enabled	是否启用了资源管理器。默认值为 true。
spring.cloud.azure.credential.client-id	使用 Azure 执行服务主体身份验证时要使用的客户端 ID。
spring.cloud.azure.credential.client-secret	使用 Azure 执行服务主体身份验证时要使用的客户端密码。
spring.cloud.azure.credential.client-certificate-path	使用 Azure 执行服务主体身份验证时要使用的 PEM 证书文件的路径。
spring.cloud.azure.credential.client-certificate-password	证书文件的密码。
spring.cloud.azure.credential.username	使用 Azure 执行用户名/密码身份验证时要使用的用户名。
spring.cloud.azure.credential.password	执行用户名/密码身份验证时使用的密码。
spring.cloud.azure.credential.managed-identity-enabled	是否启用托管标识。
spring.cloud.azure.profile.cloud-type	要连接到的 Azure 云的名称。
spring.cloud.azure.profile.environment.active-directory-endpoint	要连接到以进行身份验证的 Azure 活动目录终结点。
spring.cloud.azure.profile.subscription-id	连接到 Azure 资源时要使用的订阅 ID。
spring.cloud.azure.profile.tenant-id	Azure 资源的租户 ID。
spring.cloud.azure.<azure-service>.namespace	用于预配资源的 Azure 服务的命名空间。
spring.cloud.azure.<azure-service>.resource.resource-group	保存 Azure 服务资源的资源组。

19.3. 基本用法

Spring Cloud Azure 资源管理器可以与特定的 Spring Cloud Azure 初学者一起工作，检索连接信息（如连接字符串）以连接到 Azure 服务。它还可以与第三方库一起使用，以检索用户名/密码等元数据，并完成身份验证，有关更多信息，请参阅Kafka支持和Redis 支持部分。spring-cloud-azure-starter

例如，若要检索 Azure 服务的连接字符串，开发人员可以使用服务主体作为凭据来对连接字符串进行身份验证和检索。配置列出如下。提供的服务主体应 至少为关联的命名空间分配角色。请参阅使用 Azure AD 授予访问权限，确保主体已被授予访问 Azure 资源的足够权限。Contributor

spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      <azure-service>:
        namespace: ${SERVICEBUS_NAMESPACE}
        resource:
          resource-group: ${RESOURCE_GROUP}

19.4. 示例

有关更多详细信息，请参阅azure-spring-boot-samples。

20. 配置属性

要查看所有与Spring Cloud Azure相关的配置属性的列表，请查看附录页面。