대화형 Google Chat 앱을 Google Workspace 부가기능으로 변환

Google Chat 앱 빠른 시작을 기반으로 하는 앱과 같이 Google Chat API 상호작용 이벤트를 사용하는 Google Chat 앱을 빌드하고 게시한 경우 이 페이지에서는 Google Chat을 확장하는 Google Workspace 부가기능으로 변환하는 방법을 보여줍니다.

변환하면 Google Chat 앱에서 Google Workspace 부가기능 프레임워크를 사용하여 Google Chat 내에서 그리고 Google Workspace 전반에서 통합 및 기능을 위한 새로운 가능성을 열 수 있습니다. 예를 들어 Google Chat 앱 하나와 Google Workspace 부가기능 하나 등 두 가지 배포 대신 Google Workspace Marketplace를 통해 단일 Google Workspace 부가기능을 배포하여 Gmail, Calendar, Docs와 같은 다른 Google Workspace 호스트 애플리케이션과 함께 Chat 앱을 확장할 수 있습니다.

제한사항

변환을 시작하기 전에 Google Chat을 확장하는 Google Workspace 부가기능의 제한사항을 검토하여 필수 기능을 손실하지 않고 Google Chat 앱을 변환할 수 있는지 확인하세요.

1단계: 기존 Google Chat 앱 코드 복사

변환 프로세스에는 코드 변경이 필요합니다. 실제 Google Chat 앱에 영향을 주지 않으려면 코드 사본을 만들어 작업하세요.

Apps Script

  1. 기존 Google Chat 앱 Google Apps Script 프로젝트를 엽니다.
  2. 왼쪽에서 개요 를 클릭합니다.
  3. 오른쪽에서 사본 만들기 를 클릭합니다.
  4. 왼쪽에서 프로젝트 설정 을 클릭합니다.
  5. Google Cloud 프로젝트에서 프로젝트 변경을 클릭합니다.
  6. 기존 Google Chat 앱 프로젝트와 연결된 동일한 프로젝트 번호를 입력합니다.
  7. 프로젝트 설정을 클릭합니다.

HTTP

기존 코드베이스의 포크 또는 사본을 만들고 이를 라이브 Google Chat 앱과 별도의 새 서비스로 배포합니다.

앱이 Google Cloud에 배포되고 Google Cloud 프로젝트에 연결된 기능 (예: 기본 App Engine ID)을 사용하는 경우 새 코드는 기존 Google Chat 앱 프로젝트와 연결된 서비스에 배포해야 합니다.

2단계: 복사된 코드 수정

Google Chat 사용을 확장하는 Google Workspace 부가기능은 Chat API 상호작용 이벤트로 빌드된 Google Chat 앱과 비교하여 다른 요청 및 응답 구조를 사용합니다. 요청 및 응답에 Google Chat API의 Event 대신 Google Workspace 부가기능 EventObject을 사용하도록 코드를 업데이트해야 합니다. 코드 변환 가이드를 사용하여 코드를 수정합니다.

3단계: 테스트 사용자를 위해 Google Workspace 부가기능 구성 사용 설정하기

Google Cloud 콘솔을 사용하여 Google Chat 앱의 Google Workspace 부가기능 설정을 구성합니다.

  1. Google Cloud 콘솔에서 Google Chat API 구성 페이지로 이동합니다.

    Google Chat API 구성 페이지로 이동

  2. 대화형 기능에서 부가기능으로 변환을 클릭합니다.

  3. 부가기능 구성 설정 사용 설정을 사용 설정합니다.

  4. 공개 상태 섹션에 테스트 사용자의 이메일 주소를 추가합니다.

  5. 필요한 경우 2단계에서 복사하고 수정한 Google Chat 앱 코드의 배포 엔드포인트 URL 또는 Apps Script 배포 ID로 연결 설정을 업데이트합니다.

  6. 저장 및 테스트를 클릭합니다.

4단계: 변환된 앱 테스트

3단계에서 구성한 테스트 사용자 계정을 사용하여 Google Workspace 부가기능 기능을 철저히 테스트합니다. 모든 기능과 상호작용을 확인합니다.

5단계: 모든 사용자의 전환 완료

변환된 Google Workspace 부가기능이 올바르게 작동하는지 확인한 후 모든 사용자가 사용할 수 있도록 설정할 수 있습니다.

  1. Google Cloud 콘솔에서 Google Chat API 구성 페이지로 이동합니다.

    Google Chat API 구성 페이지로 이동

  2. 대화형 기능에서 부가기능으로 변환을 클릭합니다. 측면 패널이 열립니다.

  3. 측면 패널에서 부가기능으로 변환을 클릭합니다.

  4. 프로젝트 ID를 입력하고 변환을 클릭합니다.

이제 Google Chat 앱이 Google Chat을 확장하는 Google Workspace 부가기능이 되었습니다.

선택사항: 사용하지 않는 Google Cloud 리소스 정리 또는 해제

선택적으로 Google Chat 앱을 Google Workspace 부가기능으로 변환한 후 더 이상 사용하지 않는 Google Chat 앱에서 사용하는 리소스에 대해 Google Cloud 계정에 요금이 청구되지 않도록 하려면 해당 리소스를 사용 중지하는 것이 좋습니다.

코드 변환 가이드

이 섹션에서는 Google Chat API 상호작용 Event 형식과 Google Workspace 부가기능 EventObject 형식 간의 매핑을 자세히 설명합니다.

매핑 요청

다음 표는 Google Chat API Event의 필드가 Google Workspace 부가기능 EventObject의 상응하는 필드에 매핑되는 방식을 보여줍니다.

Google Chat API 상호작용 Event 필드 Google Workspace 부가기능 EventObject 필드 참고
action.actionMethodName 해당 사항 없음 카드 상호작용의 경우 메서드 이름을 commonEventObject.parameters의 매개변수로 전달할 수 있습니다. 초기 대화상자 열기를 참고하세요.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 이벤트 유형에 따라 다양한 페이로드에서 사용할 수 있습니다.
token 해당 사항 없음 인증은 다르게 처리됩니다. HTTP 앱 인증 요청을 참고하세요.
type 해당 사항 없음 이벤트 유형은 트리거에서 추론할 수 있습니다.
user chat.user

사용 사례별 요청 매핑

다음 표에서는 Chat API 상호작용 이벤트로 빌드된 Google Chat 앱과 Google Chat을 확장하는 Google Workspace 부가기능 간의 일반적인 사용 사례에 대한 요청 페이로드의 차이점을 보여줍니다.

사용 사례 Chat API 상호작용 Event 페이로드 Google Workspace 부가기능 EventObject 페이로드
스페이스에 앱이 추가됨 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
스페이스에서 앱 삭제 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
사용자가 앱을 @멘션함 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
사용자가 앱을 @멘션하여 스페이스에 추가합니다. Google Chat의 요청 하나를 처리해야 합니다.
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Google Chat의 두 가지 요청을 처리해야 합니다.

첫 번째 요청:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

두 번째 요청:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
슬래시 명령어 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
스페이스에 앱을 추가하는 슬래시 명령어 Google Chat의 요청 하나를 처리해야 합니다.
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Google Chat의 두 가지 요청을 처리해야 합니다.

첫 번째 요청:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

두 번째 요청:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
사용자가 카드 또는 대화상자에서 버튼을 클릭함 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

대화상자 이벤트의 경우 common.formInputs에 위젯 값이 포함됩니다. Google Apps Script 예:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

대화상자 이벤트의 경우 commonEventObject.formInputs에 위젯 값이 포함됩니다. Google Apps Script 예:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
사용자가 앱 홈 카드에 정보를 제출함 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
사용자가 빠른 명령어를 사용하여 앱 명령어를 호출합니다. 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
링크 미리보기 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
사용자가 카드 메시지 또는 대화상자에서 위젯을 업데이트함 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

사용 사례별 응답 매핑

Google Chat을 확장하는 Google Workspace 부가기능은 Message 객체 대신 작업을 반환합니다. 다음 표에서는 Google Chat API Message 응답 유형을 상응하는 Google Workspace 부가기능 작업과 매핑합니다.

사용 사례 Google Chat API Message 응답 Google Workspace 부가기능 채팅 작업 응답
호출된 스페이스에서 메시지 만들기 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse는 선택사항입니다. 자세한 내용은 슬래시 명령어에 응답하기를 참고하세요.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

자세한 내용은 메시지 보내기를 참고하세요.
메시지 업데이트 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

자세한 내용은 메시지 업데이트 (Chat)를 참고하세요.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

자세한 내용은 메시지 업데이트 (부가기능)를 참고하세요.
링크 미리보기 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

자세한 내용은 링크 미리보기 (Chat)를 참고하세요.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

자세한 내용은 링크 미리보기(부가기능)를 참고하세요.
초기 대화상자 열기 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

자세한 내용은 대화상자 열기 (Chat)를 참고하세요.

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
푸시하는 카드에는 onClick 작업이 있는 위젯이 포함될 수 있습니다. HTTP Google Workspace 부가기능의 경우 함수 엔드포인트를 호출하도록 다음 작업을 구성합니다. 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

자세한 내용은 대화상자 열기 (부가기능)를 참고하세요.
대화상자 닫기 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

자세한 내용은 대화상자 닫기 (Chat)를 참고하세요.

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

자세한 내용은 대화상자 닫기 (부가기능)를 참고하세요.
외부 시스템에 연결 (구성 요청) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

자세한 내용은 외부 시스템에 연결을 참고하세요.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

자세한 내용은 Google Workspace 부가기능을 서드 파티 서비스에 연결하기를 참고하세요.
대화형 위젯의 자동 완성 항목 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

자세한 내용은 다중 선택 메뉴 추가를 참고하세요.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

자세한 내용은 Google Chat 사용자로부터 정보 수집 및 처리하기를 참고하세요.

전환 전에 생성된 메시지에서 카드 상호작용 처리

HTTP Google Chat 앱을 Google Workspace 부가기능으로 변환할 때 변환 전에 생성된 메시지의 카드 상호작용에는 특별한 처리가 필요합니다. Google Workspace 부가기능은 카드의 action.function에 전체 HTTP URL을 사용하는 반면, Google Chat API 상호작용 이벤트로 빌드된 Google Chat 앱은 함수 이름을 사용합니다. 다음 표에는 이러한 차이점이 요약되어 있습니다.

Google Chat API 상호작용 이벤트로 빌드된 Google Chat 앱 Google Chat을 확장하는 Google Workspace 부가기능
구성 Google Cloud 콘솔에서 모든 이벤트에 대해 단일 엔드포인트를 구성합니다. 카드 상호작용을 구현할 때 카드의 action에는 실행할 함수의 이름만 포함됩니다. 일반 HTTP 엔드포인트는 카드 클릭 이벤트에 대해 호출됩니다.

자세한 내용은 대화상자 열기 (Chat)를 참고하세요.



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Google Cloud 콘솔에서 이벤트별 엔드포인트를 선택적으로 구성할 수 있지만 카드 클릭 이벤트는 포함되지 않습니다. 카드 상호작용을 구현할 때 카드의 action에는 호출할 HTTP 엔드포인트의 전체 URL이 포함되어야 합니다. 버튼별로 고유한 HTTP 엔드포인트를 설정하거나 공통 엔드포인트를 사용하고 action.parameters에서 작업을 매개변수로 전달할 수 있습니다.

자세한 내용은 대화상자 열기 (부가기능)를 참고하세요.



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

변환 전에 생성된 메시지에서 카드 상호작용이 작동하도록 하려면 Google Chat API 구성 페이지에서 카드 상호작용 URL을 구성하세요.

이 URL은 앱을 변환하기 전에 생성된 메시지에서의 상호작용에만 사용됩니다. 사용자가 이러한 메시지 중 하나와 상호작용하면 원래 action.function 값이 __action_method_name__이라는 매개변수로 전달됩니다.

예: 카드 클릭

카드 상호작용 URL을 https://.../card-interaction-handler로 구성한 경우 사용자가 다음 작업으로 이전 메시지의 카드를 클릭합니다.

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

이벤트는 다음과 같은 형식으로 구성된 카드 상호작용 URL에 전송됩니다.

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

예: 다중 선택 메뉴

사용자가 외부 데이터 소스가 있는 다중 선택 메뉴와 상호작용하는 경우:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

이벤트는 다음과 같은 형식으로 구성된 카드 상호작용 URL에 전송됩니다.

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

HTTP 트리거에 대해 모든 트리거에 공통 HTTP 엔드포인트 URL 사용을 사용 설정하면 버튼 클릭됨 이벤트에도 공통 URL이 사용됩니다.

채팅을 확장하는 HTTP Google Workspace 부가기능의 요청 확인

HTTP 기반 Google Chat 앱의 경우 Google Workspace 부가기능으로 변환할 때 요청이 Google에서 시작되었는지 확인하는 로직을 업데이트해야 합니다.

요청 확인의 주요 차이점은 다음과 같습니다.

앱 유형 지원되는 잠재고객 서비스 계정 이메일
Google Chat API 상호작용 이벤트로 빌드된 Google Chat 앱 프로젝트 번호 chat@system.gserviceaccount.com
Google Chat을 확장하는 Google Workspace 부가기능 HTTP 엔드포인트만 프로젝트별 서비스 계정 이메일

Google Workspace 부가기능의 고유한 서비스 계정 이메일은 Google Cloud 콘솔의 Google Chat API 구성 페이지에 있는 Google Workspace 부가기능으로 변환 섹션에서 확인할 수 있습니다.

업그레이드된 Google Workspace 부가기능에서 요청을 확인하려면 다음 단계를 따르세요.

  1. Cloud Run 함수를 사용하는 경우 애드온별 서비스 계정에 roles/cloudfunctions.invoker 역할을 부여합니다. IAM으로 액세스 승인을 참고하세요.
  2. Google Workspace 부가기능 서비스 계정 이메일을 사용하여 Bearer 토큰의 서명을 확인하도록 토큰 확인 코드를 업데이트합니다. Google의 요청 유효성 검사를 참고하세요.