채팅 앱을 다른 서비스 및 도구와 연결하기

이 페이지에서는 Google Chat 앱을 Google Chat 외부의 서비스 또는 도구와 연결하는 방법을 설명합니다. Chat 앱은 자체적으로도 강력하지만 다른 시스템과 함께 작동하는 경우가 많으며 계정을 연결하거나, 데이터 액세스를 승인하거나, 추가 데이터를 표시하거나, 사용자 환경설정을 구성하려면 동반 애플리케이션이 필요합니다.

서드 파티 서비스 또는 OAuth 흐름으로 사용자를 인증하려면 Chat 앱에서 다음 단계를 실행합니다.

  1. 승인 또는 구성이 필요한 경우 감지
  2. 사용자에게 로그인하거나 서비스를 구성하라는 메시지를 표시하는 기본 승인 카드를 반환합니다.
  3. 사용자가 승인을 완료한 후 Google Chat이 원래 상호작용을 자동으로 다시 시도하도록 완료 URI로 리디렉션합니다.

Google Chat 앱이 서드 파티 서비스로 인증하는 방식의 아키텍처

기본 요건

HTTP

사용자 상호작용을 수신하고 이에 응답하는 Google Chat 앱 하나를 빌드하려면 HTTP 빠른 시작을 완료하세요.

Apps Script

사용자 상호작용을 수신하고 이에 응답하는 Google Chat 앱 하나를 빌드하려면 Apps Script 빠른 시작을 완료하세요.

승인이 필요한지 감지

사용자가 채팅 앱과 상호작용할 때 다음과 같은 다양한 이유로 보호된 리소스에 액세스할 권한이 없을 수 있습니다.

  • 서드 파티 서비스에 연결할 액세스 토큰이 아직 생성되지 않았거나 만료되었습니다.
  • 액세스 토큰이 요청된 리소스를 포함하지 않습니다.
  • 액세스 토큰이 요청에 필요한 범위를 포함하지 않습니다.

사용자가 로그인하고 서비스에 대한 액세스를 승인할 수 있도록 채팅 앱에서 이러한 사례를 감지해야 합니다.

Apps Script에서 빌드하는 경우 Google Apps Script용 OAuth2 라이브러리(또는 OAuth1 버전)를 사용할 수 있습니다. 여기서 hasAccess 함수는 사용자가 서비스에 대한 액세스를 승인했는지 확인합니다. 또는 UrlFetchApp.fetch 요청을 사용하는 경우 muteHttpExceptions 매개변수를 true로 설정하여 반환된 HttpResponse 객체의 응답 코드와 콘텐츠를 검사할 수 있습니다.

기본 승인 카드로 사용자에게 메시지 표시

Chat 앱에서 승인 또는 구성이 필요하다고 감지하면 AuthorizationError 응답을 반환하여 사용자에게 비공개 기본 승인 카드를 표시합니다.

다음 이미지는 Google의 기본 승인 카드의 예를 보여줍니다.

예시 계정의 기본 승인 프롬프트
그림 1: Example Account의 기본 승인 메시지 프롬프트에는 Chat 앱이 추가 정보를 표시하려고 하지만 계정에 액세스하려면 사용자의 승인이 필요하다고 표시됩니다.

기본 승인 카드를 사용하여 사용자에게 메시지를 표시하려면 AuthorizationError 객체를 반환하세요.

HTTP

다음 JSON 응답을 반환합니다.

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

다음을 바꿉니다.

  • AUTHORIZATION_URL: 인증, 승인 또는 구성을 처리하는 웹 앱의 HTTPS URL입니다.
  • RESOURCE_DISPLAY_NAME: 보호된 리소스 또는 서비스의 표시 이름입니다. 이 이름은 승인 메시지에 사용자에게 표시됩니다. 예를 들어 RESOURCE_DISPLAY_NAME이 Example Account인 경우 앱이 Example Account에 액세스하려면 승인이 필요하다는 메시지가 표시됩니다.

구성 요청 완료

Chat에서 사용자는 승인 프로세스를 완료할 수 있으며 Chat에서 수동 새로고침 없이 원래 상호작용을 자동으로 다시 시도합니다. 트리거가 메시지, 스페이스에 추가됨 또는 앱 명령어인 경우 채팅은 자동 재시도를 지원합니다.

이러한 트리거의 경우 Chat 앱은 이벤트 페이로드에서 완료 리디렉션 URI (configCompleteRedirectUri / completeRedirectUri)를 수신합니다.

  • 메시지: chat.messagePayload.configCompleteRedirectUri
  • 스페이스에 추가됨: chat.addedToSpacePayload.configCompleteRedirectUri
  • 앱 명령어: chat.appCommandPayload.configCompleteRedirectUri

이 리디렉션 URI를 <var>AUTHORIZATION_URL</var>에 인코딩하고 승인 흐름이 완료된 후 사용자의 브라우저를 이 URI로 리디렉션해야 합니다. 이 URL로 리디렉션하면 승인 또는 구성 요청이 처리되었음을 Google Chat에 알립니다.

사용자가 원래 이벤트 페이로드에 제공된 완료 리디렉션 URI로 리디렉션되면 Google Chat은 다음 단계를 실행합니다.

  1. 시작 사용자에게 표시되는 비공개 승인 프롬프트를 삭제합니다.
  2. 원본 메시지를 공개로 변환하여 스페이스의 다른 회원에게 표시합니다.
  3. 원래 이벤트 객체를 Chat 앱에 두 번째로 전송합니다.

완료 리디렉션 URI로 리디렉션하지 않으면 사용자가 승인 흐름을 완료할 수 있지만 Google Chat에서 이전 실행을 자동으로 다시 시도하지 않으며 사용자가 Chat 앱을 수동으로 다시 호출해야 합니다.

완료 리디렉션 URI를 방문하면 단일 사용자 상호작용에만 영향을 미칩니다. 사용자가 채팅 앱에 여러 번 메시지를 보내고 여러 메시지를 받은 경우 하나의 메시지에 대한 인증 및 구성 프로세스를 완료하면 해당 특정 상호작용만 다시 시도됩니다.

Chat 외부에서 Chat 사용자 인증

Chat 외부의 URL (예: OAuth 웹 콜백)에 연결할 때는 외부 웹 세션을 Chat의 사용자 ID와 상호 연관시켜야 하는 경우가 많습니다. Google 로그인으로 대상 웹 앱을 보호하는 것이 좋습니다.

로그인 중에 발급된 ID 토큰을 사용하여 사용자 ID를 가져옵니다. sub 클레임에는 사용자의 고유한 Google ID가 포함되어 있으며 Google Chat의 사용자 리소스 이름 (chat.user.name)과 상관관계를 설정할 수 있습니다.

sub 클레임을 Google Chat users/{user} 리소스 이름과 연관시키려면 sub 클레임 값 앞에 users/를 추가합니다. 예를 들어 123의 sub 클레임 값은 Chat 앱에 전송된 이벤트 객체의 users/123에 해당합니다.

코드 샘플

다음 코드 샘플은 Chat 앱이 기본 승인 카드를 사용하여 오프라인 OAuth2 사용자 인증 정보를 요청하고, 데이터베이스에 저장하고, 완료 URI로 리디렉션하고, 사용자 인증으로 API를 호출하는 방법을 보여줍니다.

부가기능이 아닌 채팅 앱: 채팅 앱을 다른 서비스 및 도구와 연결

Google Workspace 부가기능이 아닌 채팅 앱을 유지관리하는 경우 채팅 앱은 REQUEST_CONFIG 유형의 actionResponse를 사용하여 구성을 요청하고 최상위 Event 객체에서 configCompleteRedirectUrl를 읽습니다.

부가기능이 아닌 채팅 앱을 Google Workspace 부가기능 프레임워크로 업그레이드하려면 Google Chat 앱을 Google Workspace 부가기능으로 변환을 참고하세요.

부가기능이 아닌 채팅 앱의 사용자에게 구성 요청

부가기능이 아닌 Chat 앱에서는 다음 형식으로 구성 URL을 사용자에게 반환합니다.

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

이렇게 하면 Google Chat에 사용자에게 비공개 프롬프트를 표시하도록 지시합니다. 여기서 CONFIGURATION_URL는 사용자가 추가 인증, 승인 또는 구성을 위해 방문할 수 있는 링크입니다. REQUEST_CONFIG 응답은 일반 응답 메시지와 상호 배타적입니다. 텍스트, 카드 또는 기타 속성은 무시됩니다.

부가기능이 아닌 Chat 앱에서 구성 요청 완료

부가기능이 아닌 Chat 앱이 수신하는 모든 MESSAGE, ADDED_TO_SPACE, APP_COMMAND 상호작용 Event에는 최상위 필드 configCompleteRedirectUrl이 포함됩니다. 구성 URL에서 이 URL을 인코딩하고 완료 시 사용자에게 리디렉션하여 Google Chat이 프롬프트를 삭제하고, 원본 메시지를 공개로 변환하고, 원본 상호작용 이벤트를 Chat 앱에 다시 전송하도록 합니다.

샘플 구현은 GitHub의 Node.js 연결 앱 샘플 및 Python MyProfile 인증 앱 샘플을 참고하세요.