你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

消息标头和属性

  • 项目

本部分介绍消息标头和属性。

消息标头

发送消息时，你可以指定以下消息属性。 如果发送或接收了单个消息，则这些属性将包含在采用 JSON 编码格式的 BrokerProperties HTTP 标头中。 如果发送了一批消息，则这些属性将包含在 JSON 编码的 HTTP 正文中。 有关详细信息，请参阅 发送消息 和 发送消息批处理。

下表列出了 Microsoft.ServiceBus.Messaging.BrokeredMessage 属性。 这些属性可按任意顺序显示。 如果未指定属性，服务总线将使用该属性的默认值。 表中未列出的代理属性将被忽略。 接受的属性与指定 api-version 的值无关。 HTTP 请求中不需要 api-version 说明符。

如果同时设置 SessionId 和 PartitionKey 属性，则必须将它们设置为相同的值。

一个名为 BrokerProperties 的 HTTP 标头包含所有 BrokeredMessage 标头。 这些属性为 JSON 格式。 这样更易于扩展 BrokeredMessage 属性。 此外，它还利用 Web 友好 JSON 格式根据 Web 编程模型进行调整。 这样更易于在使用较少字符串解析的情况下生成和使用消息属性。 以下是 BrokeredMessage 标头的示例：

BrokerProperties:  { “SessionId”: “{27729E1-B37B-4D29-AA0A-E367906C206E}”, “MessageId”: “{701332E1-B37B-4D29-AA0A-E367906C206E}”, “TimeToLive” : 90, “CorrelationId”: “{701332F3-B37B-4D29-AA0A-E367906C206E}”, “SequenceNumber“ : 12345, “DeliveryCount“ : 2, “To“ : "http://contoso.com“, “ReplyTo“ : "http://fabrikam.com“,  "EnqueuedTimeUtc“ : " Sun, 06 Nov 1994 08:49:37 GMT“, "ScheduledEnqueueTimeUtc“ : " Sun, 06 Nov 1994 08:49:37 GMT“}

下表说明了如何将 BrokeredMessage 属性映射到 HTTP 标头。

BrokeredMessage (SBMP) 部分 类型 HTTP 标头 可访问性 HTTP 请求/响应
ContentType 字符串 Content-Type get、set 请求、响应
CorrelationId 字符串 BrokerProperties{CorrelationId} get、set 请求、响应
SessionID 字符串 BrokerProperties {SessionId} get、set 请求、响应
DeliveryCount int BrokerProperties {DeliveryCount } get 响应
LockedUntilUtc DateTime BrokerProperties{LockedUntil} get 响应
LockToken Guid BrokerProperties{LockToken} get 响应
MessageId 字符串 BrokerProperties{MessageId} get、set 响应
Label 字符串 BrokerProperties {Label} get、set 请求、响应
ReplyTo 字符串 BrokerProperties {ReplyTo} get、set 请求、响应
EnqueuedTimeUtc DateTime 日期 get 响应
SequenceNumber long BrokerProperties {SequenceNumber} get 响应
TimeToLive TimeSpan BrokerProperties collection {TimeToLive} get、set 请求、响应
功能 字符串 BrokerProperties {To} get、set 请求、响应
ScheduledEnqueueTimeUtc DateTime BrokerProperties {ScheduledEnqueueTimeUtc} get、set 请求、响应
ReplyToSessionId 字符串 BrokerProperties {ReplyToSessionId} get、set 请求、响应
PartitionKey 字符串 BrokerProperties {PartitionKey} get、set 请求、响应

除了这些属性外，你还可以指定自定义属性。 如果发送或接收了单个消息，则会将每个自定义属性放置在其自身的 HTTP 标头中。 如果发送了一批消息，则会将自定义属性包含在 JSON 编码的 HTTP 正文中。 有关详细信息，请参阅 发送消息 和 发送消息批处理。

说明

  • DateTime 标头的格式由 RFC2616 定义： https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3。 例如，“Sun, 06 Nov 1994 08:49:37 GMT”。

  • BrokerProperties {TimeToLive} 是 TimeSpan (double) 的秒数。

  • ExpiresAtUtc 没有相应的 HTTP 标头，因为该标头可以从 Date 和 BrokerProperties {TimeToLive} 派生。

  • 具有 get 取值函数的消息标头只能出现在 HTTP 响应（例如，收到的消息）中。 当 HTTP 请求（即发送的消息）中存在这些标头时，系统会在不提示的情况下将其忽略。 无法识别的 HTTP 标头也会在无提示的情况下被忽略。

  • 如果值的格式不正确，则会将相应的 HTTP 状态代码返回客户端。

消息属性

消息属性是包含在 message.Properties 中的用户定义的键值对。 对于 SBMP 胖客户端，值仅限于 byte、sbyte、char、short、ushort、int、uint、long、ulong、float、double、decimal、bool、Guid、string、Uri、DateTime、DateTimeOffset 和 TimeSpan。

对于 REST/HTTP，则不支持 Uri 和 DateTimeOffset（如果它们在 BrokeredMessage 中，则不会将它们包含在 HTTP 标头中）。 GUID 类型将转换为字符串，而 TimeSpan 类型将转换为“总秒数”。 由于存在这些转换，将失去类型保真度。 此外，还将排除与受限制 HTTP 标头（例如，Connection、Expect，等等）对应的任何属性名称。

中的每个 message.Properties 键值对都将映射到采用以下格式的 HTTP 标头。 prop 是键名称， value 是值的字符串表示形式：

prop_name: value

可推断出值的类型。 如果将其用双引号括起来，则：

  • 如果内容为 RFC2616 日期时间格式，则代理会将其视为 System.DateTime。

  • 否则，代理会删除引号并将内容视为 System.String。

如果没有将其用双引号括起来，则：

  1. 如果内容为 true 或 false（区分大小写！），则代理会将其视为具有对应值的 System.Boolean。

  2. 如果内容可以解析为整数，则代理会将其视为 System.Int64。

  3. 如果内容可以解析为浮点数，则代理会将其视为 System.Double。

  4. 否则，代理会拒绝该消息。

例如：

product: Windows 7 Ultimate  
price: 299.98  
order-time: Fri, 04 Mar 2011 08:49:37 GMT

邮件正文

HTTP 请求/响应正文流和 BrokerMessage.BodyStream 之间不进行任何转换。 另外，HTTP 请求的 Content-Type 标头将保留并返回给消息接收方，这样才能让应用程序正确解释正文中的字节信息。

如果使用 SBMP 胖客户端创建消息时没有使用自定义 xml 对象序列化程序，则内容类型将默认为“application/msbin1”（即 DataContractBinarySerializer），除非在创建消息后应用程序显式更改它（例如，message.ContectType=”application/mytype”）。 此内容类型值将返回给 HTTP 使用者。 由应用程序负责决定如何反序列化正文中的字节。

WCF 服务总线绑定将 ContentType 设置为消息编码器的 ContentType。 例如，如果使用文本消息编码器，则 Content-Type 应为 “application/soap+xml”。

消息转换

HTTP 请求/响应和消息之间的转换在 HTTP 消息传送运行时提供程序中执行。 将增强转换方法，使之包括本节前面介绍的表中的标头/属性映射，以便保留消息的内容类型。