发送服务总线消息

2025-10-15

可用性

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。

该 send-service-bus-message 策略将消息发送到 Azure 服务总线队列或主题。

注释

此策略目前为预览版。
有关将消息发送到 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-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

Elements

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

Usage

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

使用注意事项

必须预先创建接收消息的 Azure 服务总线队列或主题。
每个策略定义可以多次使用此策略。

例子

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

在此示例中，包含请求正文的消息将发送到服务总线队列。 API 管理实例使用用户分配的标识进行访问。然后将请求转发到后端服务。

<policies>
    <inbound>
        <send-service-bus-message queue-name="orders" client-id="00001111-aaaa-2222-bbbb-3333cccc4444" 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">
           <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>

集成和外部通信

后续步骤

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

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例