Azure 服务总线 中的 HTTP message headers and properties

服务总线 消息包含正文、代理属性和应用定义属性。 当你使用 REST 消息 API 时,这些值会映射到 HTTP 正文和头部。 本文描述了这种映射。 关于协议无关的消息模型,请参见 消息、有效载荷和序列化。

Note

SBMP及其 WindowsAzure.ServiceBus 消息库于2026年9月30日退役。 本文中对 BrokeredMessage SBMP的引用描述的是遗留属性映射和消息格式,而非支持的客户端或协议选择。 对于新的 .NET 应用,请使用 Azure.Messaging.ServiceBus。 关于现有应用,请参见 迁移指南。

代理属性

对于单个消息, BrokerProperties HTTP 头包含代理属性作为 JSON 对象。 对于批量发送,每个消息在 JSON 请求主体中包含一个 BrokerProperties 对象。 关于请求格式,请参见 发送消息 和 发送消息批处理。

属性可以按任意顺序出现。 该服务对遗漏的属性使用默认值,忽略无法识别的代理属性。 代理项-属性映射不依赖 api-version 查询参数,消息请求也不需要该参数。

如果你同时设置 SessionId 和 PartitionKey,则将两者设置为相同的值。

例如,发送方可以设置消息标识符、主题、相关标识符以及90秒的生存时间:

BrokerProperties: {"MessageId":"order-123","Label":"OrderCreated","CorrelationId":"request-456","TimeToLive":90}

下表将遗留 BrokeredMessage 属性名称映射到其HTTP表示。 请求属性可以由发送方写入。 仅响应属性描述了收到的消息。

遗留属性 类型 HTTP 表示形式 Direction
ContentType string Content-Type 页眉 请求和响应
CorrelationId string BrokerProperties.CorrelationId 请求和响应
SessionId string BrokerProperties.SessionId 请求和响应
DeliveryCount int BrokerProperties.DeliveryCount Response
LockedUntilUtc DateTime BrokerProperties.LockedUntilUtc Response
LockToken Guid BrokerProperties.LockToken Response
MessageId string BrokerProperties.MessageId 请求和响应
Label string BrokerProperties.Label 请求和响应
ReplyTo string BrokerProperties.ReplyTo 请求和响应
EnqueuedTimeUtc DateTime BrokerProperties.EnqueuedTimeUtc;也可由 Date 标头表示 Response
SequenceNumber long BrokerProperties.SequenceNumber Response
TimeToLive TimeSpan BrokerProperties.TimeToLive(以秒为单位) 请求和响应
To string BrokerProperties.To 请求和响应
ScheduledEnqueueTimeUtc DateTime BrokerProperties.ScheduledEnqueueTimeUtc 请求和响应
ReplyToSessionId string BrokerProperties.ReplyToSessionId 请求和响应
PartitionKey string BrokerProperties.PartitionKey 请求和响应

日期-时间值使用HTTP日期格式,例如 Sun, 06 Nov 1994 08:49:37 GMT。 该 TimeToLive 数值为持续时间的总秒数。 该 ExpiresAtUtc 属性没有单独的HTTP头;它可从enqueue时间和存活时间中推导出来。

该服务在发送请求中忽略仅响应的属性。 格式错误的值会产生HTTP错误响应。 有关已接收属性的示例,请参见 Peek-lock message。

历史发送属性默认值

遗留的 send-property 参考列出了 CorrelationId、Label、MessageId、ScheduledEnqueueTimeUtc、PartitionKey、ReplyToSessionId、ViaPartitionKey、ReplyTo、SessionId、TimeToLive 和 To 的空默认值。 它列出了 ForcePersistence 的 false。 这些条目是历史 BrokeredMessage 映射,而非当前 HTTP 应用的功能支持矩阵。 关于当前属性语义和实体级默认值(如消息过期),请参见 消息、有效载荷与序列化 以及 消息过期。

自定义消息属性

对于单个消息,每个自定义属性映射到其自己的HTTP头部。 对于批量发送,可以在 JSON 正文中每条消息的 UserProperties 对象内放置自定义属性。 批量请求的自定义头部不会应用到该批次的消息上。

对于HTTP头部,服务总线推断出值类型:

标头值 解释型类型
HTTP 日期格式中的双引号值 DateTime
其他双引号值 string,去掉两侧的引号
不带引号的小写 true 或 false bool
未加引号的整数 Int64
未加引号的浮点数 double
其他值 该信息被拒绝。

例如:

product: "Example product"
price: 299.98
order-time: "Fri, 04 Mar 2011 08:49:37 GMT"

使用与保留HTTP头(如 Connection 和 Expect)分开的自定义头部名称。 保留的头部不会作为自定义属性存储。 字面头值 null 也会被丢弃。 请查看 发送消息中的注释。

遗留属性转换

在已退役的 SBMP 客户端中,message.Properties 中的自定义属性可具有以下类型:byte、Uri、ulong、long、float、Guid、bool、string、decimal、DateTime、DateTimeOffset、char、ushort、TimeSpan、short、int、uint、double 和 sbyte。

当这些遗留消息通过 HTTP 表示时,标头中不包含 Uri 和 DateTimeOffset 值。 Guid 值变为字符串, TimeSpan 值将变为总秒数。 这些转换会失去原始类型保真度。

邮件正文

服务总线 在消息跨越 HTTP 及其他消息协议时,会保留消息正文的字节和 Content-Type 头部。 选择发送方和接收方都能理解的序列化格式。 例如,发送带有 Content-Type: application/json的 JSON 字节。

由未使用自定义 XML 序列化器的已弃用 SBMP 客户端创建的消息,其内容类型可以为 application/msbin1。 读取这些现有消息的应用程序负责反序列化二进制XML主体。 传统的 WCF 服务总线 绑定使用消息编码器的内容类型,例如,对于文本编码器,为 application/soap+xml。

关于当前序列化指导,请参见 消息、有效载荷和序列化。

后续步骤