调用Google people.searchDirectoryPeople接口部分联系人无姓名返回问题

问题根因 #

• 域用户资料可见性限制：Google Workspace域管理员可自定义用户资料字段的可见范围，若部分用户的姓名字段被设置为仅本人/指定部门可见，你调用API使用的身份没有对应查看权限，就会出现返回结果中姓名字段缺失的情况。
• 多源查询的字段合并异常：你在请求中同时指定了DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT（域联系人）和DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE（域用户档案）两个数据源，API默认会自动合并两个源的字段，若某用户在域联系人数据源中没有存储姓名数据，合并逻辑可能会覆盖掉域用户档案中已有的姓名数据，导致字段缺失。
• 姓名字段存储格式问题：部分用户的姓名可能仅存储了names[].unstructuredName非结构化姓名字段，没有拆分填充firstName、lastName结构化字段，仅检索结构化字段时会误认为数据缺失。

解决方案 #

• 排查域权限配置：联系你的Google Workspace超级管理员，确认缺失姓名的用户的资料字段可见性配置，确保你调用API使用的OAuth身份或服务账号有对应字段的查看权限；如果是服务账号调用，确认已开启全域权限委派，且委派的身份属于有权限查看全量用户资料的用户组。
• 调整API请求参数：若你的业务不需要查询域联系人数据，可删除DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT数据源参数，仅查询域用户档案；也可以添加mergeSources=false参数关闭多源自动合并逻辑，分别提取两个数据源的字段内容，避免合并覆盖导致的数据丢失。
• 优化字段解析逻辑：解析返回结果时遍历names数组的所有条目，不要仅读取第一条数据，同时增加对unstructuredName字段的兼容逻辑，在结构化姓名字段缺失时可从非结构化字段中提取所需内容。

你当前的请求配置本身没有语法错误，readMask的配置是正确的，不需要调整字段列表：

{
    "method": "GET",
    "headers": {
        "Authorization": "Bearer access_token",
        "Content-Type": "application/json"
    },
    "uri": "https://people.googleapis.com/v1/people:searchDirectoryPeople?query=ajay&readMask=names,nicknames,addresses,calendarUrls,emailAddresses,organizations,phoneNumbers,photos,relations&sources=DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT&sources=DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE"
}

注：该API整体调用正常、可返回正确结果，仅部分联系人的返回结果中缺失姓名（firstName、lastName）相关数据。

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