Node.js创建Service Bus Topic消息时自定义属性过滤失效排查

1. 先确认消息属性的设置位置是否正确 #

Node.js 使用 @azure/service-bus SDK 时，自定义属性必须放在 applicationProperties 对象中，subject 需直接赋值给消息的 subject 属性，写错位置会导致过滤器无法识别：

const { ServiceBusClient, ServiceBusMessage } = require("@azure/service-bus");

async function sendTargetMessage() {
  const sbClient = new ServiceBusClient("你的连接字符串");
  const sender = sbClient.createSender("你的Topic名称");

  // 正确的消息构造方式
  const message = new ServiceBusMessage({
    body: "消息内容",
    subject: "jobCosts", // 若用subject过滤，直接赋值此处
    applicationProperties: {
      eventType: "jobCosts" // 自定义属性必须放在这个对象里
    }
  });

  await sender.sendMessages(message);
  await sender.close();
  await sbClient.close();
}

2. 核对过滤器的匹配规则 #

• 大小写敏感：Azure Service Bus 的属性名和值严格区分大小写，比如过滤器配置的是 EventType，但代码里写的是 eventType，会直接匹配失败。
• 类型匹配：确保过滤器的值类型与消息属性一致，比如过滤器用字符串"jobCosts"，代码里不能传数字或布尔值。

3. 检查 Function App 触发器配置 #

• 确认触发器的 connection 参数对应正确的 Service Bus 命名空间连接字符串，topicName 和 subscriptionName 完全匹配目标订阅。
• 若订阅启用了会话功能，消息必须携带 sessionId，否则会被直接过滤。

4. 查看 Service Bus 与 Function App 的监控日志 #

• 登录 Azure 门户查看目标订阅的死信队列：如果消息被过滤，通常会被转入死信队列，这里能直观看到不匹配原因。
• 查看 Function App 的日志流：排查是否存在触发器初始化失败、权限不足（比如连接字符串权限仅为监听而非发送）等问题。

内容的提问来源于stack exchange，提问作者Octo