Azure Service Bus 主题

Azure Service Bus 主题发布订阅组件的详细文档

组件格式

要设置 Azure Service Bus 主题发布订阅，请创建类型为 pubsub.azure.servicebus.topics 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南以了解如何创建和应用发布订阅配置。

此组件使用 Azure Service Bus 上的主题；有关主题和队列之间差异，请参阅官方文档。
若要使用队列，请参阅 Azure Service Bus 队列发布订阅组件。

连接字符串身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  # 不使用 Microsoft Entra ID 身份验证时必需
  - name: connectionString
    value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}"
  # - name: consumerID # 可选：默认为应用自身的 ID
  #   value: channel1 
  # - name: timeoutInSec # 可选
  #   value: 60
  # - name: handlerTimeoutInSec # 可选
  #   value: 60
  # - name: disableEntityManagement # 可选
  #   value: "false"
  # - name: maxDeliveryCount # 可选
  #   value: 3
  # - name: lockDurationInSec # 可选
  #   value: 60
  # - name: lockRenewalInSec # 可选
  #   value: 20
  # - name: maxActiveMessages # 可选
  #   value: 10000
  # - name: maxConcurrentHandlers # 可选
  #   value: 10
  # - name: defaultMessageTimeToLiveInSec # 可选
  #   value: 10
  # - name: autoDeleteOnIdleInSec # 可选
  #   value: 3600
  # - name: minConnectionRecoveryInSec # 可选
  #   value: 2
  # - name: maxConnectionRecoveryInSec # 可选
  #   value: 300
  # - name: maxRetriableErrorsPerSec # 可选
  #   value: 10
  # - name: publishMaxRetries # 可选
  #   value: 5
  # - name: publishInitialRetryIntervalInMs # 可选
  #   value: 500

注意： 上述设置在使用此组件的所有主题之间共享。

警告

上述示例使用纯文本字符串作为密钥。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	Service Bus 的共享访问策略连接字符串。除非使用 Microsoft Entra ID 身份验证，否则必需。	参见上面的示例
`namespaceName`	N	用于设置 Service Bus 命名空间地址的参数，为完全限定域名。如果使用 Microsoft Entra ID 身份验证，则为必需。	`"namespace.servicebus.windows.net"`
`consumerID`	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息只由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID（`appID`）值。(`appID`) 值。	可以设置为字符串值（例如上面示例中的 `"channel1"`）或字符串格式值（例如 `"{podName}"` 等）。请参阅您可以在组件元数据中使用的所有模板标签。
`timeoutInSec`	N	发送消息和管理操作的超时时间。默认值：`60`	`30`
`handlerTimeoutInSec`	N	调用应用程序处理程序的超时时间。默认值：`60`	`30`
`lockRenewalInSec`	N	定义缓冲消息锁的续订频率。默认值：`20`。	`20`
`maxActiveMessages`	N	定义一次处理或缓冲的最大消息数。此值应至少等于最大并发处理程序数。默认值：`1000`	`2000`
`maxConcurrentHandlers`	N	定义并发消息处理程序的最大数量。默认值：`0`（无限制）	`10`
`disableEntityManagement`	N	当设置为 true 时，队列和订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
`defaultMessageTimeToLiveInSec`	N	默认消息生存时间（秒）。仅在订阅创建期间使用。	`10`
`autoDeleteOnIdleInSec`	N	自动删除空闲订阅前等待的时间（秒）。仅在订阅创建期间使用。必须为 300 秒或更长。默认值：`0`（禁用）	`3600`
`maxDeliveryCount`	N	定义服务器尝试传递消息的次数。仅在订阅创建期间使用。默认值由服务器设置。	`10`
`lockDurationInSec`	N	定义消息在过期前被锁定的秒数。仅在订阅创建期间使用。默认值由服务器设置。	`30`
`minConnectionRecoveryInSec`	N	在连接失败后尝试重新连接到 Azure Service Bus 之前等待的最小间隔（秒）。默认值：`2`	`5`
`maxConnectionRecoveryInSec`	N	在连接失败后尝试重新连接到 Azure Service Bus 之前等待的最大间隔（秒）。在每次尝试之后，组件在最小值和最大值之间等待一个随机秒数，每次都会增加。默认值：`300`（5 分钟）	`600`
`maxRetriableErrorsPerSec`	N	每秒处理的可重试错误的最大数量。如果消息因可重试错误而处理失败，组件会在开始处理另一条消息之前添加延迟，以避免立即重新处理失败的消息。默认值：`10`	`10`
`publishMaxRetries`	N	当 Azure Service Bus 响应"太忙"以限制消息时的最大重试次数。默认值：`5`	`5`
`publishInitialRetryIntervalInMs`	N	当 Azure Service Bus 限制消息时，初始指数退避的时间（毫秒）。默认值：`500`	`500`

Microsoft Entra ID 身份验证

Azure Service Bus 主题发布订阅组件支持使用所有 Microsoft Entra ID 机制进行身份验证，包括托管标识。有关详细信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的相关组件元数据字段，请参阅Azure 身份验证文档。

配置示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  - name: namespaceName
    # 使用 Azure 身份验证时必需。
    # 必须是完全限定域名
    value: "servicebusnamespace.servicebus.windows.net"
  - name: azureTenantId
    value: "***"
  - name: azureClientId
    value: "***"
  - name: azureClientSecret
    value: "***"

消息元数据

Azure Service Bus 消息使用额外的上下文元数据扩展了 Dapr 消息格式。一些元数据字段由 Azure Service Bus 本身设置（只读），其他字段可以在发布消息时由客户端设置。

发送带有元数据的消息

要在发送消息时设置 Azure Service Bus 元数据，请按照此处的文档在 HTTP 请求上设置查询参数或在 gRPC 元数据中设置。

metadata.MessageId
metadata.CorrelationId
metadata.SessionId
metadata.Label
metadata.ReplyTo
metadata.PartitionKey
metadata.To
metadata.ContentType
metadata.ScheduledEnqueueTimeUtc
metadata.ReplyToSessionId

注意： metadata.MessageId 属性不会设置 Dapr 返回的 cloud event 的 id 属性，应单独处理。

注意： 如果未设置 metadata.SessionId 属性但主题需要会话，则将使用空的会话 ID。

注意： metadata.ScheduledEnqueueTimeUtc 属性支持 RFC1123 和 RFC3339 时间戳格式。

接收带有元数据的消息

当 Dapr 调用您的应用程序时，它会使用 HTTP 头或 gRPC 元数据将 Azure Service Bus 消息元数据附加到请求中。除了上面列出的可设置元数据之外，您还可以访问以下只读消息元数据。

metadata.DeliveryCount
metadata.LockedUntilUtc
metadata.LockToken
metadata.EnqueuedTimeUtc
metadata.SequenceNumber

要了解有关这些元数据属性用途的更多详细信息，请参阅官方 Azure Service Bus 文档。

此外，原始 Azure Service Bus 消息的所有 ApplicationProperties 条目都将作为 metadata.<application property's name> 附加。

注意：所有时间都由服务器填充，不会针对时钟偏差进行调整。

订阅启用会话的主题

要订阅已启用会话的主题，您可以在订阅元数据中提供以下属性。

requireSessions（默认：false）
sessionIdleTimeoutInSec（默认：60）
maxConcurrentSessions（默认：8）

为主题创建 Azure Service Bus 代理

按照此处的说明设置 Azure Service Bus 主题。