Google Chat 사용자 식별 및 지정하기

이 페이지에서는 Google Chat 앱과 개발자가 Chat 사용자를 식별하고 지정하는 방법을 설명합니다.

다음 작업을 실행하려면 Chat 앱 또는 개발자가 사용자를 지정해야 합니다.

Chat에서 사용자를 식별하는 방법

Google Chat API는 Chat을 사용하는 각 사용자 및 앱에 대해 User 리소스를 생성합니다. User 리소스에는 다음 필드가 포함됩니다.

  • name: 리소스 이름으로, users/{user} 형식입니다. 여기서 {user}는 고유하고 안정적인 식별자를 나타냅니다. users/app을 호출하는 Chat 앱의 별칭으로 사용할 수 있습니다.
  • displayName: 출력 전용. 사용자의 표시 이름입니다.
  • avatarUrl: 출력 전용. 사용자의 아바타 이미지 URL입니다.
  • email: 출력 전용. 사용자의 이메일 주소
  • domainId: 사용자 Google Workspace 도메인의 고유 식별자입니다.
  • type: 사용자 유형입니다. 사용자가 채팅 앱 (BOT)인지 개인 (HUMAN)인지를 나타냅니다.
  • isAnonymous: 출력 전용. true는 사용자가 삭제되었거나 프로필이 표시되지 않음을 나타냅니다.

사용자 프로필 세부정보 및 공개 상태 규칙

사용자 인증을 사용하여 Messages 및 Memberships API를 호출하면 Google Chat API가 프로필 세부정보로 User 리소스를 채웁니다. API는 내부 사용자 (Google Workspace 조직에 있음)와 외부 사용자 (외부 조직 또는 개인 Google 계정에 있음) 모두에 대해 displayName, email, avatarUrl를 채웁니다.

API가 사용자 프로필을 채우는 위치의 예는 다음과 같습니다.

  • Message의 sender입니다.
  • 메일 annotations 내의 사용자(예: 사용자 @mentions)입니다.
  • Membership 리소스 내의 member입니다.

공개 범위 및 공개 상태 규칙

사용자 개인 정보를 보호하기 위해 Google Chat API는 사용자 프로필 세부정보를 채울지 여부를 결정할 때 다음과 같은 특정 공개 상태 규칙을 적용합니다.

  • 프로필이 채워짐: 사용자가 스페이스 초대를 수락했거나 (스페이스의 구성원임) 호출 사용자와 이전 친밀도 (예: 채팅 메시지 상호작용 기록)가 있는 경우 API가 프로필 세부정보 (displayName, email, avatarUrl가 있고 isAnonymous가 false임)를 채웁니다.
  • 익명 프로필: 사용자가 스페이스에서 언급되었지만 회원도 아니고 호출하는 사용자와 사전 선호도도 없는 경우 프로필이 익명으로 유지됩니다. 익명 사용자의 경우 isAnonymous은 true이며 displayName, email, avatarUrl과 같은 세부정보는 생략됩니다. 하지만 앱 인증으로 이루어진 API 요청의 경우 displayName 필드가 항상 채워집니다.

다음 JSON 예는 API 응답 또는 상호작용 이벤트에서 반환된 프로필 세부정보가 채워진 User 리소스를 보여줍니다.

{
  "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
}

Google Chat API 호출에서 사용자 지정

사용자를 지정하려면 {user} 값에 다음 값을 사용하세요.

  • Google Workspace 조직의 사용자의 경우 다음 방법 중 하나를 사용하세요.

    • Chat API의 User 리소스에 있는 name입니다(예: users/123456789).
    • People API에서 Person 리소스의 이름에 대한 {person_id}입니다. 여기서 resourceName은 people/{person_id}입니다. 예를 들어 Chat API의 users/123456789는 People API의 people/123456789와 동일한 사람을 나타냅니다.
    • Directory API의 User 리소스에 대한 id입니다. 예를 들어 Chat API의 users/123456789는 Directory API의 users/123456789와 동일한 사람을 나타냅니다.
    • 사용자 인증으로 이루어진 API 요청의 경우 사용자의 이메일 주소가 별칭으로 사용됩니다(예: users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com).

  • 외부 Google Workspace 조직의 사용자 또는 Google 계정을 사용하는 사용자의 경우 다음 중 하나를 사용하세요.

    • 이메일 별칭(예: users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com 또는 users/EMAIL_USERNAME@gmail.com)
    • 이전 API 호출 또는 상호작용 이벤트에서 가져온 User 리소스 (예: users/12345678901234567890)의 표준 name입니다.

API 응답 또는 상호작용 이벤트에서 사용자 식별

API 호출 또는 수신 이벤트에서 반환된 사용자를 다음과 같은 여러 방법으로 식별할 수 있습니다.

Google Chat API는 사용자 인증을 사용할 때 내부 및 외부 사용자의 프로필을 채우므로 개발자는 Directory API를 호출하여 구성원 및 메시지 발신자의 이름이나 이메일을 확인할 필요가 없습니다.