Определите и укажите пользователей Google Chat

На этой странице объясняется, как приложения Google Chat и разработчики могут идентифицировать и указывать пользователей чата.

Для выполнения любого из следующих действий разработчику или создателю чат-приложения необходимо указать пользователя:

Как чат идентифицирует пользователей

API Google Chat генерирует ресурс User для каждого пользователя и приложения, использующего чат. Ресурс User содержит следующие поля:

  • name : Имя ресурса в формате users/{user} , где {user} представляет собой уникальный и стабильный идентификатор. Вы можете использовать users/app в качестве псевдонима для вызывающего приложения чата.
  • displayName : Только вывод. Отображаемое имя пользователя.
  • avatarUrl : Только для вывода. URL изображения аватара пользователя.
  • email : Только вывод. Адрес электронной почты пользователя.
  • domainId : Уникальный идентификатор домена Google Workspace пользователя.
  • type : Тип пользователя. Указывает, является ли пользователь чат-приложением ( BOT ) или человеком ( HUMAN ).
  • isAnonymous : Только вывод. Если true , означает, что пользователь удален или его профиль не виден.

Сведения о профиле пользователя и правила видимости

При вызове API сообщений и членства с использованием аутентификации пользователя , API Google Chat заполняет ресурс User данными профиля. API заполняет поля displayName , email и avatarUrl как для внутренних пользователей (в вашей организации Google Workspace), так и для внешних пользователей (во внешних организациях или личных учетных записях Google).

Примерами мест, где API заполняет профили пользователей, являются следующие:

  • sender Message .
  • Пользователи в annotations сообщений, например, упоминания пользователей @mentions .
  • member в рамках ресурса Membership .

Правила конфиденциальности и видимости

Для защиты конфиденциальности пользователей API Google Chat применяет определенные правила видимости при определении того, следует ли заполнять данные профиля пользователя:

  • Заполненный профиль : API заполняет данные профиля (присутствуют displayName , email и avatarUrl , а isAnonymous имеет значение false ), если пользователь принял приглашение в пространство (является участником пространства) или имеет предыдущую связь (например, историю личных сообщений) с вызывающим пользователем.
  • Анонимный профиль : Если пользователь упоминается в пространстве, не являясь его участником и не имея предварительной связи с вызывающим пользователем, его профиль остается анонимным. Для анонимного пользователя isAnonymous равно true , и такие данные, как displayName , email и avatarUrl , опускаются. Однако для запросов API, выполняемых с использованием аутентификации приложения , поле displayName всегда заполняется.

В следующем примере JSON показан ресурс User с заполненными данными профиля, возвращенными в ответе API или в результате взаимодействия:

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

В следующем примере JSON показан анонимный ресурс User , где сведения о профиле пользователя не видны вызывающей стороне:

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

Укажите пользователя в запросе к API Google Чата

Для указания пользователя используйте следующие значения для параметра {user} :

  • Для пользователей вашей организации Google Workspace используйте один из следующих подходов:

    • name ресурса User в Chat API, например users/123456789 .
    • В API для работы с людьми имя ресурса " Person " имеет вид {person_id} , где resourceName — people/{person_id} — например, users/123456789 в API чата представляет того же человека, что и people/123456789 в API для работы с людьми.
    • id ресурса User в API каталога — например, users/123456789 в API чата — обозначает того же человека, что и users/123456789 в API каталога.
    • Для запросов к API, выполняемых с использованием аутентификации пользователя , адрес электронной почты пользователя используется в качестве псевдонима — например, users/ EMAIL_USERNAME @ WORKSPACE_DOMAIN .com

  • Для пользователя, входящего во внешнюю организацию Google Workspace, или для пользователя, использующего учетную запись Google, воспользуйтесь одним из следующих вариантов:

    • Псевдоним электронной почты — например users/ EMAIL_USERNAME @ WORKSPACE_DOMAIN .com или users/ EMAIL_USERNAME @gmail.com .
    • Каноническое name ресурса User (например, users/12345678901234567890 ), полученное в результате предыдущего вызова API или события взаимодействия.

Идентификация пользователя на основе ответа API или события взаимодействия.

Идентифицировать пользователей, возвращаемых из API-запросов или входящих событий, можно несколькими способами:

  • API сообщений : Получите идентификатор отправителя из Message.sender или упомянутых пользователей из Message.annotations[].userMention.user .
  • API для работы с членством : Получение идентификатора участника из Membership.member .
  • События взаимодействия : Когда пользователь взаимодействует с приложением чата, чат отправляет событие взаимодействия , содержащее идентификатор пользователя в Event.user .

Поскольку API Google Chat заполняет профили как внутренних, так и внешних пользователей при использовании аутентификации пользователей, разработчикам не нужно обращаться к API каталога для получения имен или адресов электронной почты участников и отправителей сообщений.