SharePoint Online API getByEmail偶发“用户未找到”错误求助

问题背景 #

我们使用以下SharePoint Online API端点获取用户ID：

https://my_company.sharepoint.com/_api/web/SiteUsers/getByEmail('xxx@my_company.com')/Id

该接口90%的场景下可正常返回用户ID，但部分场景会返回如下错误：

<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"><m:code>-2130575276, Microsoft.SharePoint.SPException</m:code><m:message xml:lang="en-US">User cannot be found.</m:message></m:error>

报错用户的账号及邮箱均为公司正常在用账号，且未对该账号进行任何手动操作。但间隔几天或几周后再次测试，接口又能正常返回ID，推测可能是用户登录系统等操作触发了某些自动设置。

可能原因 #

• 用户信息未同步到目标站点的用户信息列表：SharePoint的SiteUsers接口依赖站点的用户信息列表（User Information List），新用户或长期未访问站点的用户，其信息可能未被写入该列表。只有当用户首次访问站点、被添加到站点权限组，或系统触发定期同步时，才会完成信息同步。
• Entra ID与SharePoint的同步延迟：用户在Entra ID中状态正常，但账号激活、属性变更后，Entra ID到SharePoint的同步可能存在窗口延迟，导致短期内API无法检索到用户。
• 许可证/权限临时异常：用户的SharePoint相关许可证曾短暂失效（比如批量更新时的间隙），或站点权限被临时移除后恢复，会导致API在异常时段无法找到用户。
• 缓存机制影响：SharePoint或API层的缓存未及时更新用户状态，旧的“用户不存在”状态被缓存，直到缓存过期或用户操作触发刷新。

解决办法 #

• 主动触发用户信息同步：
  • 调用API将用户添加到站点权限组（即使已有权限，重复操作也会触发同步）：

    POST https://my_company.sharepoint.com/_api/web/sitegroups/getbyname('GroupName')/users/adduser
    请求体: {'logonName': 'i:0#.f|membership|xxx@my_company.com'}
    

  • 让用户手动访问目标站点一次，触发系统自动同步用户信息到站点列表。
• 替换API端点：改用Microsoft Graph API先获取用户ID，再结合SharePoint操作，绕过站点用户列表的同步限制：

  GET https://graph.microsoft.com/v1.0/users/xxx@my_company.com?$select=id,userPrincipalName
  

• 排查Entra ID与权限状态：按补充要求检查用户的Entra ID账号状态（确保未禁用、属性正常）、SharePoint许可证有效性、所属群组是否包含站点权限相关组，确认无临时异常。
• 添加重试逻辑：调用API时加入重试机制，遇到-2130575276错误时，间隔一段时间后重试（比如3次，每次间隔5分钟），覆盖同步延迟或缓存过期场景。

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