如何通过Confluence API利用邮箱地址查询用户用户名？

问题分析 #

你调用https://confluence.example.com/rest/api/user?username=someone@example.com返回404错误，错误信息如下：

{"statusCode":404,"data":{"authorized":false,"valid":true,"allowedInReadOnlyMode":true,"errors":[],"successful":false},"message":"No user found with key : null","reason":"Not Found"}

出现这个问题的核心原因是：该接口的username参数仅支持通过用户名查询用户，而非邮箱地址。直接传入邮箱作为username参数，系统无法匹配到对应用户，因此返回404。

正确的API调用方式 #

要通过邮箱查询Confluence用户名，需使用用户搜索接口/rest/api/user/search，结合CQL语句精准匹配邮箱：

1. 构造请求URL：

https://confluence.example.com/rest/api/user/search?cql=email="someone@example.com"

2. 请求方法：GET
3. 权限要求：调用接口的账号需具备浏览用户的基础权限（普通用户权限通常即可，具体以你的Confluence权限配置为准）

返回结果示例 #

请求成功后，会返回包含目标用户信息的JSON数组，其中username字段即为你需要的用户名：

[
  {
    "username": "jdoe",
    "displayName": "John Doe",
    "email": "someone@example.com",
    "type": "known"
  }
]

注意事项 #

• 若返回空数组，说明该邮箱未在Confluence中注册，或调用账号无权限查看该用户信息
• CQL语法需严格遵循要求，邮箱地址必须用双引号包裹
• 内部部署的Data Center实例API路径与云版本一致，无需额外调整

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