使用CRM WEB API调用RetrieveDuplicates时带括号名称报错问题

问题复现 #

调用Dynamics CRM WEB API的RetrieveDuplicates接口查询account实体重复记录时：

• 普通名称（如ACME Corp）调用正常；
• 名称含括号且括号后带文本（如ACME (USA)Corp）返回Bad Request - Error in query syntax；
• 名称含括号但括号后无文本（如ACME (USA)）调用正常。
  尝试直接用括号、单斜杠转义、双斜杠转义+URL编码均未解决问题。

解决方法 #

1. 对特殊字符进行URL编码 #

括号()属于OData查询的保留语法字符，直接传入会被解析为查询结构的一部分，需先对其进行URL编码：

• (编码为%28
• )编码为%29
  处理后ACME (USA)Corp变为ACME %28USA%29Corp，将该值作为name参数传入接口。

2. 用单引号包裹名称值 #

将名称值用单引号包裹，让OData将整个内容视为字符串常量，避免解析括号为语法符号：

• 原始名称：ACME (USA)Corp
• 包裹后：'ACME (USA)Corp'
• 若需URL编码，可直接对包裹后的字符串编码，或仅编码括号部分。

3. 确保请求体格式正确 #

示例正确的请求JSON结构（编码后的名称）：

{
  "Entity": {
    "name": "ACME %28USA%29Corp"
  },
  "MatchingEntityName": "account",
  "PagingInfo": {
    "PageNumber": 1,
    "Count": 50
  }
}

若使用单引号包裹，请求体中name字段值应为："name": "'ACME (USA)Corp'"

额外排查点 #

• 确认针对account实体name字段的重复检测规则处于激活状态，且规则的匹配逻辑覆盖带括号的场景；
• 先在Dynamics CRM界面手动验证该名称存在重复记录，再对比接口调用结果。

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