发送服务总线消息

适用于：开发人员 |基本 |标准 |奖赏

该 send-service-bus-message 策略将消息发送到 Azure 服务总线队列或主题。你可以选择将 API 请求转发给后端服务。

注释

有关将消息发送到 Azure 服务总线的背景和先决条件，请参阅如何从 Azure API 管理将消息发送到 Azure 服务总线。

注释

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

政策声明

<send-service-bus-message 
    queue-name="service bus queue"
    topic-name="service bus topic"
    namespace="FQDN of service bus namespace"
    client-id="ID of user-assigned managed identity"
    message-id="message ID"
    session-id="session ID"
    time-to-live="message time to live"
    response-variable-name="context variable name"
    ignore-error="false">
        <message-properties>
                <message-property name="property-name">property-value</message-property>
                <!-- if there are multiple properties, then add additional message-property elements -->
        </message-properties>
        <payload>"message content"</payload>
</send-service-bus-message>

特性

Attribute	Description	必选	违约
`queue-name`	指定要向其发送消息的服务总线队列的名称。允许策略表达式和命名值。必须指定或`queue-nametopic-name`必须指定。	否	N/A
`topic-name`	指定要向其发送消息的服务总线主题的名称。允许策略表达式和命名值。必须指定或`queue-nametopic-name`必须指定。	否	N/A
`namespace`	指定服务总线命名空间的完全限定域名。允许策略表达式和命名值。	否	N/A
`client-id`	指定用户分配的托管标识的客户端 ID，以便通过服务总线进行身份验证。必须为标识分配 Azure 服务总线数据发送者角色。允许策略表达式和命名值。如果你没有指定这个属性，系统分配的身份将被使用。	否	N/A
`message-id`	消息标识符。必须是有效的 GUID。允许使用策略表达式。如果省略，API 管理会生成一个 GUID。	否	生成的 GUID
`session-id`	服务总线会话标识符用于分组相关消息。必须是有效的 GUID。允许使用策略表达式。	否	N/A
`time-to-live`	消息在处理期限前还能被处理多久。例如，使用TimeSpan值 `00:10:00`。	否	N/A
`response-variable-name`	一个上下文变量的名称，用于接收关于服务总线发送操作的信息。	否	N/A
`ignore-error`	服务总线发送失败是否应允许策略继续执行。 `true` = 继续; `false` = 调用正常错误处理。	否	`false`

注释

当你指定 response-variable-name时，API 管理会在该上下文变量中存储关于服务总线发送操作的信息。成功时，包含 MessageId、 SessionId和 TimeToLive。在被忽略的发送失败中，它包含 Error.Reason 和 Error.Message。

Elements

元素	Description	必选
`payload`	指定要发送到服务总线的消息有效负载。允许策略表达式和命名值。	是的
`message-properties`	一组 `message-property` 子元素，这些子元素指定要与消息有效负载一起传递的元数据。每个 `message-property` 值对都包含一个名称/值对。允许策略表达式和命名值。	否

Usage

策略部分： 入站、出站、出错
策略范围：全局、产品、API、操作
网关： 经典

使用注意事项

必须预先创建接收消息的 Azure 服务总线队列或主题。
每个策略定义可以多次使用此策略。
如果你省略 message-id了，API 管理会生成一个 GUID。
配置和message-idsession-id值必须是有效的GUID。
当服务总线实体需要会话时使用session-id。
time-to-live使用TimeSpan如的值。00:10:00
ignore-error 适用于发送失败。消息配置无效，如无效的GUID或TTL，仍会导致策略失败。

例子

将消息发送到服务总线队列

在这个例子中，包含请求体的消息被发送到命令队列。请求ID变为消息ID，消息在10分钟后失效，发送信息存储在 serviceBusResult。发送失败会调用API管理错误处理。 API 管理实例使用用户分配的标识进行访问。然后将请求转发到后端服务。

<policies>
    <inbound>
        <send-service-bus-message 
          queue-name="orders"
          namespace="contoso-messaging.servicebus.chinacloudapi.cn"
          message-id="@(context.RequestId.ToString())"
          time-to-live="00:10:00"
          response-variable-name="serviceBusResult"
          ignore-error="false">
          <payload>
            @(context.Request.Body.As<string>(preserveContent: true))
          </payload>
        </send-service-bus-message>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
</policies>

将消息发送到服务总线主题

在这个例子中，你向服务总线主题发送包含请求正体的消息。 API 管理实例使用系统分配的标识进行访问。然后，你将请求转发给后端服务。

<policies>
    <inbound>
        <send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.chinacloudapi.cn">
           <payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
        </send-service-bus-message>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
</policies>

发送消息和元数据

在这个例子中，你向服务总线主题发送包含请求体的消息，并设置消息属性以发送与有效载荷相关的元数据。 API 管理实例使用系统分配的标识进行访问。然后，你将请求转发给后端服务。

<policies>
    <inbound>
        <send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.chinacloudapi.cn">
           <message-properties>
              <message-property name="Customer">Contoso</message-property>
           </message-properties>
           <payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
        </send-service-bus-message>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
</policies>

发送消息并立即返回

在这个例子中，你向服务总线主题发送包含请求正体的消息。 API 管理实例使用系统分配的标识进行访问。然后，你会立即向呼叫者返回 201 一个响应状态代码。

<policies>
    <inbound>
        <send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.chinacloudapi.cn">
           <payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
        </send-service-bus-message>
        <return-response>
            <set-status code="201" reason="Created!" />
        </return-response>
    </inbound>
</policies>

集成和外部通信

若要详细了解如何使用策略，请参阅：

Last updated on 2026-09-11