Варианты API для получения фото профиля Gmail в конвейерах данных о контактах
Сравните Google People API, Workspace Admin SDK и анализ публичных аватаров email по модели доступа и решаемым задачам.
Руководство по выбору для разработчиков, работающих с фотографиями контактов, фото пользователей в управляемых доменах и поддерживаемыми публичными аватарами email.
Выбор API для получения фото профиля Gmail зависит от того, к чьим данным конвейер имеет законный доступ. Google People API считывает информацию, связанную с аутентифицированным пользователем и его разрешенными контактами; Workspace Admin SDK извлекает фотографии пользователей в администрируемом домене. Для конвейера, который содержит идентификаторы поддерживаемых email-адресов Gmail, но не имеет этих связей с аккаунтами Google, AvatarLookup предлагает анализ аватаров публичных email-адресов через документированные маршруты для работы в реальном времени или с несколькими идентификаторами. Эти маршруты отвечают на разные вопросы и не должны рассматриваться как взаимозаменяемые источники проверенных фотографий людей.
API фото профиля Gmail: начните с модели доступа
Разработчики часто ищут один конечный пункт (endpoint), который принимает любой адрес Gmail и возвращает фотографию профиля. Официальные API Google более контекстно-зависимы. Введение в People API описывает данные из контактов аутентифицированного пользователя, его профиля и разрешенных источников домена. Доступ зависит от отношений с пользователем и предоставленных областей действия (scopes). Метод получения фото в Workspace Admin SDK решает другую задачу: администратор домена извлекает фото управляемого пользователя.
Ни одно из этих описаний не означает, что разработчик может отправить произвольный внешний адрес Gmail в эти API и ожидать получения публичного изображения. People API подходит, когда приложение уже авторизовано для работы с контактами или информацией профиля вошедшего в систему пользователя. Admin SDK подходит для администрирования пользователей Workspace самой организации в соответствии с ее моделью авторизации. Эта статья не предоставляет учетные данные Google API, примеры запросов или обходные пути для получения разрешений; официальная документация является верным источником для деталей реализации.
Определите задачу по работе с данными перед выбором маршрута. Отображает ли приложение фото контакта, уже доступное через авторизованные контакты Google пользователя? Управляет ли оно фотографиями для собственного домена Workspace? Или отдельный процесс обработки контактных данных проверяет, связан ли доступный публичный аватар с поддерживаемым идентификатором email? Это разные области применения.
Что дает Google People API
People API может возвращать информацию о фотографии в ресурсе Person вместе с другими полями из подключенных источников. Документация по ресурсу Person от Google поясняет, что ресурс может объединять данные контактов и профиля в зависимости от источника и контекста авторизации. Конвейер должен сохранять этот контекст при хранении URL фотографии; он не должен стирать разницу между изображением контакта и информацией публичного профиля.
Интеграция с People API хорошо подходит, когда продукт уже запрашивает у пользователя разрешение на доступ к контактам для четко определенной цели. Затем он может использовать авторизованные данные для отображения или управления контактами этого пользователя в рамках документированных областей действия и политик Google. Это плохо подходит для сервиса, который хочет проверить большой список несвязанных адресов Gmail без наличия этих пользовательских отношений. Наличие поля photos в схеме ответа не гарантирует, что фотография будет доступна для каждого человека.
Спроектируйте конвейер так, чтобы он корректно обрабатывал отсутствие или изменение фотографий. Записывайте, какой аутентифицированный аккаунт и источник предоставили данные в соответствии с политикой доступа приложения, и избегайте копирования изображения контакта в общую CRM, как если бы это был проверенный публичный факт. Видимая фотография профиля — это презентационный сигнал, а не учетные данные или проверка юридической личности.
Когда подходит Workspace Admin SDK
Метод users.photos.get в Directory API для Admin SDK от Google извлекает фотографию пользователя, идентифицированного в контексте администрируемого Workspace. Документированные области действия авторизации ясно дают понять, что это административный маршрут, а не общий поиск по потребительским аккаунтам Gmail. Компания, ведущая собственный справочник сотрудников, может использовать его как часть рабочего процесса управления аккаунтами. Поставщик данных о продажах, владеющий внешними адресами, не должен представлять это как конечный пункт для открытого поиска.
Различие имеет значение, даже если адрес электронной почты выглядит знакомым. Адрес gmail.com не является автоматически аккаунтом в домене Workspace организации, а адрес корпоративного домена не является автоматически видимым для стороннего приложения. Доступ регулируется контекстом аккаунта Google и домена. Документация для разработчиков может показывать краткий путь получения фото, но существование этого пути не расширяет круг авторизованных лиц.
Если организация уже управляет собственным доменом, используйте ее правила управления справочником для хранения, обновления и удаления фотографий сотрудников. Для внешних записей контактов не используйте эту административную логику, пытаясь угадать ключ пользователя. В следующем разделе описывается маршрут анализа публичных аватаров с другой областью действия и значением результата.
Где подходит анализ аватаров для поддерживаемых email-адресов
Анализ аватаров email от AvatarLookup поддерживает проверки в реальном времени для одного идентификатора и синхронные проверки для нескольких идентификаторов для поддерживаемых семейств доменов Gmail, Yandex и Mail.ru. Поддерживаемые домены Gmail — это gmail.com и googlemail.com. Его документированный маршрут для работы в реальном времени — POST /api/v1/check, а синхронный мульти-маршрут — POST /api/v1/batch-check. Существует отдельный асинхронный продукт для массовой обработки аватаров email для подготовленных файлов. Это анализ публичных аватаров для поддерживаемого источника email, а не доступ к личным контактам Google или справочнику Workspace пользователя.
Правильный режим зависит от рабочей нагрузки конвейера. Для одной записи авторизованного контакта можно использовать маршрут в реальном времени; группа идентификаторов одного сервиса может использовать синхронный мульти-маршрут в рамках документированных условий; для подготовленного файла большего размера можно использовать продукт для массовой обработки аватаров email и его собственную схему CSV. Не обобщайте единую форму ответа для всех трех вариантов. Документация API AvatarLookup должна предоставить точные детали запроса и ответа.
Полученное наблюдение за публичным аватаром может помочь специалисту по качеству данных решить, какие записи контактов требуют проверки. Это не приводит к автоматическому заполнению профилей пользователей и не устанавливает, кто владеет адресом. Пустой URL аватара или результат Не определено должны оставаться неопределенными, а не интерпретироваться как «нет аккаунта Google». Другие домены электронной почты в текущем профиле для проверки аватаров не поддерживаются.
Выберите маршрут и сохраните источник результата
Краткую таблицу решений можно представить в виде трех вопросов. Для авторизованных контактов вошедшего в систему пользователя обращайтесь к People API. Для управляемых пользователей в собственном домене Workspace организации обращайтесь к Admin SDK. Для поддерживаемых идентификаторов email в рабочем процессе обработки контактных данных с использованием публичных аватаров рассмотрите AvatarLookup. Каждый маршрут имеет свою модель разрешений, совокупность данных и интерпретацию результатов. Выбор должен определяться целью приложения и законным доступом к данным, а не тем, какой API кажется проще в вызове.
Сохраняйте источник вместе с каждым наблюдением за фотографией или аватаром. URL из авторизованного контакта Google отличается от доступного публичного аватара, найденного через сервис анализа email. Если конвейер объединяет оба варианта, используйте отдельные метки источника и временные метки, а не перезаписывайте одно другим. Последующему проверяющему нужно знать, какой маршрут создал значение и что оно означает.
Избегайте использования фотографии профиля для принятия серьезных решений о человеке. Результаты анализа внешности от AvatarLookup, если применимый анализ их предоставляет, являются алгоритмическими оценками; фотографии контактов Google также не являются независимым доказательством личности. Наиболее полезная архитектура конвейера сохраняет источник, область действия и неопределенность, чтобы человек мог проверить запись контакта, не будучи введенным в заблуждение визуально привлекательным полем изображения.
Часто задаваемые вопросы
Может ли Google People API вернуть фото для любого адреса Gmail?
Он работает в контексте аутентифицированного пользователя и авторизованных контактов или профиля. Его поле фото не делает произвольные внешние адреса Gmail общедоступными для получения.
Является ли Workspace Admin SDK инструментом для поиска фото внешних адресов Gmail?
Нет. Его метод получения фото предназначен для пользователей в контексте администрируемого Workspace и требует документированной авторизации.
Какие домены электронной почты для Gmail покрывает AvatarLookup?
Текущие поддерживаемые домены Gmail — это gmail.com и googlemail.com. Продукты для анализа аватаров email также охватывают документированные домены Yandex и Mail.ru.
Подтверждает ли результат анализа публичного аватара владельца адреса электронной почты?
Нет. Это наблюдение за аватаром, специфичное для источника, и его не следует рассматривать как доказательство того, кто управляет аккаунтом электронной почты.
Узнайте больше
Выберите информацию о продукте, которая соответствует следующему шагу в вашем рабочем процессе.