用于联系人数据管道的 Gmail 头像 API 选项

一份关于联系人照片、受管域用户照片以及受支持公共邮箱头像的开发者决策指南。

选择哪种 Gmail 头像 API 取决于您的数据管道能够合法访问哪些数据。Google 的 People API 用于读取与已认证用户及其授权联系人相关的信息；Workspace Admin SDK 用于检索受管域内用户的照片。对于持有受支持 Gmail 邮箱标识符但没有上述 Google 账户关联的数据管道，AvatarLookup 通过已记录的实时或多标识符路由提供邮箱头像解析。这些路由解决的问题各不相同，不应被视为可互换的已验证个人照片来源。

Gmail 头像 API：从访问模型开始

开发者通常会寻找一个能够接收任意 Gmail 地址并返回头像的单一端点。然而，Google 的官方 API 具有更强的上下文关联性。People API 简介描述了来自已认证用户的联系人、个人资料及受许可域来源的数据。访问权限取决于与用户的关系以及所授予的范围。Workspace Admin SDK 照片方法则针对另一种情况：域管理员检索受管用户的照片。

上述说明并不意味着开发者可以向这些 API 提交任意外部 Gmail 地址并期望获得公开图像。当应用程序已获得授权，能够处理已登录用户的联系人或个人资料信息时，People API 是合适的选择。Admin SDK 则适用于管理组织自身的 Workspace 用户，并受其授权模型约束。本文不提供 Google API 凭据、请求示例或权限绕过方法；官方文档是获取实现细节的正确来源。

在选择路由之前，请先明确数据需求。应用程序是要显示用户已授权的 Google 联系人中现有的照片吗？是要管理自身 Workspace 域的照片吗？还是一个独立的联系人数据处理流程，需要查询某个受支持的邮箱标识符是否关联了可用的公共头像？这些属于不同的范畴。

Google People API 的作用

People API 可以在 Person 资源中返回照片信息，以及来自关联来源的其他字段。Google 的 Person 资源文档解释说，该资源可能会根据其来源和授权上下文合并联系人和个人资料数据。数据管道在存储照片 URL 时应保留该上下文；不应抹除联系人图像与公共个人资料信息之间的差异。

当产品已要求用户出于明确目的授权联系人访问权限时，集成 People API 是一个不错的选择。随后，它可以使用授权数据，在 Google 记录的范围和政策下显示或管理该用户的联系人。对于那些希望在没有用户关联的情况下检查大量无关 Gmail 地址的服务，这在概念上并不匹配。响应模式中存在照片字段并不保证每个人都有可用照片。

在设计管道时，应考虑到照片缺失或更改的情况。请根据应用程序的访问策略记录是哪个已认证账户和来源提供了数据，并避免将联系人图像复制到共享 CRM 中，将其视为已验证的公共事实。可见的头像是一种展示信号，而非凭据或法律意义上的身份核验。

Workspace Admin SDK 的适用场景

Google 的 Admin SDK Directory users.photos.get 方法用于检索受管 Workspace 上下文中用户的照片。其记录的授权范围明确表明这是一种管理路由，而非通用的消费者 Gmail 查询。维护自身员工名录的公司可以将其作为受管账户工作流的一部分使用。持有外部地址的销售数据提供商不应将其作为开放搜索端点进行展示。

即使邮箱地址看起来很熟悉，这种区别依然重要。一个 gmail.com 地址并不自动成为组织 Workspace 域中的账户，而公司域地址也不会自动对无关的应用程序可见。访问权限由 Google 账户和域上下文决定。开发者文档可能会展示简洁的照片检索路径，但路径的存在并不会扩大授权范围。

如果组织已管理自己的域，请使用其目录治理规则来存储、更新和删除员工照片。对于外部联系人记录，请勿通过猜测用户密钥来复用该管理逻辑。下一节将介绍一种具有不同范围和结果含义的公共头像解析路由。

受支持邮箱头像解析的适用场景

AvatarLookup 的邮箱头像解析支持针对受支持的 Gmail、Yandex 和 Mail.ru 域系列的实时单次检查和同步多标识符检查。受支持的 Gmail 域为 gmail.com 和 googlemail.com。其记录的实时路由为 POST /api/v1/check，同步多标识符路由为 POST /api/v1/batch-check。针对准备好的文件，另有异步邮箱头像批量产品。这是针对受支持邮箱来源的公共头像解析，而非对个人私有 Google 联系人或 Workspace 目录的访问。

正确的模式取决于管道的工作负载。单个已授权联系人记录可以使用实时路由；同一服务的一组标识符可以在其记录的条件下使用同步多路由；准备好的大型文件可以使用邮箱头像批量产品及其对应的 CSV 模式。请勿将单一响应格式推广到所有三种情况。AvatarLookup API 文档应提供确切的请求和响应细节。

由此产生的公共头像观察结果可以帮助数据质量审核员决定哪些联系人记录需要检查。它不会自动填充用户个人资料，也不会确定谁拥有该地址。空的头像 URL 或无法判定结果应保持不确定状态，而不应被改写为“无 Google 账户”。目前，其他邮箱域不支持头像检查。

选择路由并保留结果来源

决策表可以概括为三个问题。对于已登录用户的授权联系人，请查阅 People API。对于组织自身 Workspace 域中的受管用户，请查阅 Admin SDK。对于公共头像联系人数据工作流中的受支持邮箱标识符，请考虑 AvatarLookup。每种路由都有不同的权限模型、适用人群和结果解读。选择应由应用程序的目的和合法的数据访问权限驱动，而不是由哪个 API 调用起来最简单决定。

请为每张照片或头像观察结果存储来源。来自已授权 Google 联系人的 URL 与通过邮箱解析服务找到的可用公共头像不同。如果管道结合了两者，请使用单独的来源标签和时间戳，而不是用一个覆盖另一个。后续的审核员需要知道是哪种路由产生了该值及其含义。

避免使用头像对个人做出重大判断。在适用解析的情况下，AvatarLookup 的外观输出仅为算法估算；Google 联系人照片也不是独立的身份证明。最实用的管道设计应保留来源、范围和不确定性，以便人工在审核联系人记录时不会被美观的图像字段所误导。

常见问题解答

Google People API 能返回任何 Gmail 地址的照片吗？

它在已认证用户以及已授权联系人或个人资料的上下文中运行。其照片字段并不能使任意外部 Gmail 地址实现普遍可检索。

Workspace Admin SDK 是外部 Gmail 照片查询工具吗？

不是。其照片方法仅适用于受管 Workspace 上下文中的用户，并需要相应的授权。

AvatarLookup 涵盖哪些 Gmail 邮箱域？

目前支持的 Gmail 域为 gmail.com 和 googlemail.com。其邮箱头像产品还涵盖了已记录的 Yandex 和 Mail.ru 域。

公共头像结果能验证邮箱地址的所有者吗？

不能。这是一种特定于来源的头像观察结果，不应被视为谁控制该邮箱账户的证明。

了解更多

选择适合您工作流下一步的产品信息。

• 访问产品网站 →