1. 소개
Google Chat 앱은 사용자가 정보를 얻고 대화를 나가지 않아도 실행할 수 있는 서비스와 리소스를 Chat으로 바로 가져옵니다.
이 Codelab에서는 Gmail에서 부재중 자동응답을 설정하고 Google Calendar에서 회의를 예약하는 채팅 앱('Attendance Bot')을 만드는 방법을 알아봅니다. Google Apps Script에서 Attendance Bot을 빌드하면 드라이브, Gmail, 캘린더, 문서, 스프레드시트 등과 같은 다른 Google 서비스에 쉽게 액세스할 수 있습니다.
학습할 내용
- Chat에서 발생한 이벤트에 핸들러를 추가하는 방법
- Chat에서 보낸 이벤트 객체를 파싱하는 방법
- 카드 형식 응답으로 Chat에 다시 응답하는 방법
- 카드에서 버튼 클릭에 대한 맞춤 액션을 정의하고 반응하는 방법
필요한 항목
- 인터넷 및 웹브라우저 액세스
- Google Chat에 액세스할 수 있는 Google Workspace 계정
- 기본 자바스크립트 기술—Google Apps Script는 자바스크립트만 지원
2. 샘플 코드 가져오기
ZIP 파일을 다운로드하거나 GitHub 저장소를 클론하여 이 샘플의 각 단계에 대한 코드를 볼 수 있습니다.
step-NN 폴더에는 Codelab의 각 단계에서 도달하고자 하는 최종 상태가 포함되어 있으며, 참고용으로 제공됩니다.
코드 다운로드
이 Codelab의 코드를 다운로드하려면 다음 버튼을 클릭하세요.
다운로드한 ZIP 파일의 압축을 해제합니다. 그러면 이 Codelab의 단계별로 폴더 하나씩 포함된 루트 폴더(hangouts-chat-apps-script-codelab)가 압축 해제됩니다.
GitHub 저장소 클론
이 Codelab의 GitHub 저장소를 클론하려면 다음 명령어를 실행합니다.
git clone https://github.com/googleworkspace/hangouts-chat-apps-script-codelab
3. Google Chat 이벤트용 핸들러 만들기
Apps Script 프로젝트 만들기
Apps Script 프로젝트를 만들려면 다음 단계를 수행합니다.
- script.new로 이동합니다.
- 제목 없는 프로젝트를 클릭합니다.
- 이 스크립트 Attendance Bot의 이름을 바꾸고 이름 바꾸기를 클릭합니다.
Google Chat의 이벤트
Chat과 대부분의 Apps Script 상호작용은 이벤트 기반입니다. 사용자, 채팅 앱, Chat 간의 상호작용은 일반적으로 다음 순서를 따릅니다.
- 사용자가 채팅 앱을 스페이스에 추가하거나, 채팅 앱으로 DM(채팅 메시지)을 시작하거나, 스페이스에서 채팅 앱을 삭제하는 등의 작업을 시작합니다.
- 이 작업은 Chat의 채팅 앱을 대상으로 하는 이벤트를 발생시킵니다.
- Chat은 채팅 앱의 스크립트에 정의된 해당 이벤트 핸들러를 호출합니다.
Chat은 앱이 수신 대기할 수 있는 4가지 이벤트를 발생시킵니다.
ADDED_TO_SPACE: 이 이벤트는 인간 사용자가 채팅 앱을 스페이스 또는 채팅 메시지(DM)에 추가할 때 발생합니다. Apps Script에서 해당 이벤트를 처리하기 위해onAddToSpace()함수를 정의합니다.REMOVED_FROM_SPACE: 이 이벤트는 사용자가 스페이스 또는 DM에서 채팅 앱을 삭제할 때 발생합니다. 해당 이벤트는 Chat에 다시 응답을 게시하지 않습니다. Apps Script에서 이 이벤트를 처리하기 위해onRemoveFromSpace()함수를 정의합니다.MESSAGE: 이 이벤트는 사용자가 DM에서 직접 수행하거나 스페이스에서 @mention으로 채팅 앱에 메시지를 보낼 때 발생합니다. Apps Script에서 이 이벤트에 응답하는onMessage()함수를 정의합니다.CARD_CLICKED: 이 이벤트는 사용자가 맞춤 액션이 지정된 버튼을 클릭할 때 발생합니다. Apps Script에서 이 이벤트에 응답하는onCardClick()함수를 정의합니다.
Code.gs 파일의 내용을 ADDED_TO_SPACE 및 REMOVE_FROM_SPACE 이벤트에 대한 핸들러를 정의하는 다음 코드로 바꿉니다. (이 Codelab의 뒷부분에서 MESSAGE 및 CARD_CLICKED 이벤트에 대한 핸들러를 추가합니다.)
Code.gs
/**
* Responds to an ADDED_TO_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/chat/api/guides/message-formats/events
*/
function onAddToSpace(event) {
console.info(event);
var message = 'Thank you for adding me to ';
if (event.space.type === 'DM') {
message += 'a DM, ' + event.user.displayName + '!';
} else {
message += event.space.displayName;
}
return { text: message };
}
/**
* Responds to a REMOVED_FROM_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @see https://developers.google.com/chat/api/guides/message-formats/events
*/
function onRemoveFromSpace(event) {
console.info(event);
console.log('Chat app removed from ', event.space.name);
}
4. 채팅 앱 게시 및 테스트
스크립트 매니페스트 파일 업데이트
Chat에 앱을 게시하려면 먼저 스크립트 매니페스트를 업데이트해야 합니다.
- 프로젝트 설정
을 클릭합니다. - 편집기에 'appsscript.json' 매니페스트 파일 표시 체크박스를 선택합니다.
- 편집기
를 클릭합니다. appsscript.json파일을 클릭합니다.- 매니페스트 파일에
"chat": {}줄을 추가합니다.
매니페스트 파일은 다음 예시와 비슷하게 표시됩니다.
appsscript.json
{
"timeZone": "America/Los_Angeles",
"dependencies": {
},
"chat": {}
}
Google Cloud 프로젝트 만들기
채팅 앱을 실행하고 테스트하려면 먼저 Google Cloud 프로젝트를 만들고 Chat API를 사용 설정 및 구성하고 Google Workspace 조직에 채팅 앱을 게시해야 합니다.
- Google Cloud 콘솔에서 메뉴
> IAM 및 관리자 > 프로젝트 만들기로 이동합니다. - 프로젝트 이름에 설명이 포함된 이름을 입력합니다.
- 메시지가 표시되면 조직 및 결제 계정을 선택합니다.
- 만들기를 클릭합니다.
- 프로젝트 생성이 완료되면 페이지 우측 상단에 알림이 나타납니다. 프로젝트 만들기: <Project name> 항목을 클릭하여 프로젝트를 엽니다.
- 메뉴 > API 및 서비스 > 사용자 인증 정보를 클릭합니다.
- OAuth 동의 화면을 클릭합니다.
- 앱 이름에 Attendance Bot을 입력합니다.
- 메시지가 표시되면 사용자 지원 이메일 및 개발자 연락처 정보를 입력합니다.
- 저장하고 계속하기를 클릭합니다.
- 설정 및 유틸리티
> 프로젝트 설정을 클릭합니다. - 프로젝트 번호를 복사합니다.
- App Script 편집기로 돌아가서 프로젝트 설정 을 클릭합니다.
- Google Cloud Platform(GCP) 프로젝트에서 프로젝트 변경을 클릭합니다.
- GCP 프로젝트 번호를 클릭하고 프로젝트 번호를 입력합니다.
- 프로젝트 설정을 클릭합니다.
Chat에 앱 게시
채팅 앱을 Google Chat에 게시하려면 다음을 수행합니다.
- Apps Script 편집기에서 배포 > 새 배포를 클릭합니다.
- 유형 선택 옆에 있는 배포 유형 사용 설정 을 클릭합니다.
- 부가기능을 선택하고 배포를 클릭합니다.
- 배포 ID를 복사하고 완료를 클릭합니다.
- Google Cloud 콘솔에서 메뉴 > API 및 서비스 > 라이브러리로 이동합니다.
- Google Chat API를 검색합니다. 결과 목록에서 API를 선택합니다.
- Google Chat API 페이지에서 사용 설정을 클릭합니다.
- API를 사용 설정한 후 구성을 클릭합니다. 사용자 인증 정보를 만들라는 메시지는 무시합니다.
- 구성 페이지에서 다음을 수행합니다.
- 앱 이름에 Attendance Bot을 입력합니다.
- 아바타 URL에 https://goo.gl/kv2ENA를 입력합니다.
- 설명에 Apps Script Codelab Chat app을 입력합니다.
- 기능에서 1:1 메시지 수신을 선택합니다.
- 연결 설정에서 Apps Script 프로젝트를 선택하고 스크립트의 배포 ID를 텍스트 상자에 붙여넣습니다.
- 권한에서 내 도메인의 특정 사용자 및 그룹을 선택합니다. 드롭다운 메뉴 아래의 텍스트 상자에 Google Workspace 조직과 연결된 이메일 주소를 입력합니다.
- 저장을 클릭합니다.
변경 사항을 저장한 후 Google Chat API 페이지의 상태에 앱 상태가 활성 - 사용 가능으로 표시되는지 확인합니다.
채팅 앱 테스트
Google Chat에서 앱을 테스트하려면 다음을 수행합니다.
- Google Chat을 엽니다.
- 채팅 시작
> 앱 찾기를 클릭하여 새 채팅 메시지를 채팅 앱으로 전송합니다. - 앱 찾기 페이지에서 Attendance Bot을 검색합니다.
- Attendance Bot 옆에 있는 추가 > 채팅을 클릭합니다.
채팅 메시지 대화목록이 열리면 다음 이미지와 같이 채팅 앱에서 DM에 추가해 주셔서 감사하다는 메시지가 표시됩니다.
5. 카드 형식의 응답 정의
이전 단계에서 앱은 간단한 텍스트 응답으로 Google Chat 이벤트에 응답했습니다. 이 단계에서는 카드로 응답하도록 앱을 업데이트합니다.
카드 응답
Google Chat은 응답에 카드 사용을 지원합니다. 카드는 사용자 인터페이스 위젯 집합을 함께 그룹화할 수 있는 시각적 컨테이너입니다. 카드는 헤더, 텍스트 단락, 버튼 집합, 이미지 및 키/값 텍스트를 표시할 수 있습니다. 앱은 Google Chat에 대한 JSON 응답에서 하나 이상의 카드를 정의할 수 있으며, 그러면 응답이 해당 UI 요소로 변환됩니다.
다음 이미지는 헤더, 키/값 위젯, 이미지 위젯 및 텍스트 버튼을 포함하는 3개의 섹션이 있는 카드 응답을 보여줍니다.
카드 응답으로 사용자 메시지에 응답하려면 채팅 앱의 Code.gs 파일에 다음 코드를 추가합니다.
Code.gs
var DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
var HEADER = {
header: {
title : 'Attendance Bot',
subtitle : 'Log your vacation time',
imageUrl : DEFAULT_IMAGE_URL
}
};
/**
* Creates a card-formatted response.
* @param {object} widgets the UI components to send
* @return {object} JSON-formatted response
*/
function createCardResponse(widgets) {
return {
cards: [HEADER, {
sections: [{
widgets: widgets
}]
}]
};
}
/**
* Responds to a MESSAGE event triggered
* in Google Chat.
*
* @param event the event object from Google Chat
* @return JSON-formatted response
*/
function onMessage(event) {
var userMessage = event.message.text;
var widgets = [{
"textParagraph": {
"text": "You said: " + userMessage
}
}];
return createCardResponse(widgets);
}
이 단계에서 추가된 onMessage() 함수는 사용자의 원래 메시지를 읽고 간단한 TextParagragh 위젯으로 응답을 구성합니다. 그 다음 onMessage() 함수는 단일 카드의 섹션 내에 TextParagraph 위젯을 배치하는 createCardResponse()를 호출합니다. 봇은 카드 응답으로 구성된 자바스크립트 객체를 Google Chat에 다시 반환합니다.
채팅 앱 테스트
이 앱을 테스트하려면 Google Chat에서 앱을 사용한 채팅 메시지로 돌아가서 메시지를 입력합니다(모든 메시지 가능).
onMessage() 이벤트 핸들러는 Google Chat에서 전달한 이벤트 객체를 파싱하여 사용자의 원본 메시지를 추출합니다. 이벤트를 시작한 사용자의 이름, 이메일 주소, 이벤트가 발생한 스페이스의 이름 등 이벤트에 대한 다른 유형의 정보도 얻을 수 있습니다.
Google Chat에서 보낸 이벤트 객체의 구조에 대한 자세한 내용은 이벤트 형식 참조를 확인하세요.
6. 카드에서 버튼 클릭에 대한 반응
이전 단계에서 채팅 앱은 TextParagragh 위젯이 포함된 간단한 카드로 사용자의 MESSAGE 이벤트에 응답했습니다. 이 단계에서는 버튼이 포함된 응답을 생성하며, 각 버튼에는 정의된 맞춤 액션이 있습니다.
양방향 카드
카드 응답에는 텍스트 전용 버튼을 표시하는 TextButton 위젯과 간단한 아이콘이나 텍스트가 없는 이미지로 버튼을 표시하는 ImageButton 위젯 이 두 가지 유형의 버튼 중 하나가 포함될 수 있습니다. TextButton 위젯과 ImageButton 위젯은 모두 두 가지 onClick 동작(Google Chat으로 다시 전송된 JSON 응답에 정의됨)인 openLink 또는 action 중 하나를 지원합니다. 이름에서 알 수 있듯이 openLink는 새 브라우저 탭에서 지정된 링크를 엽니다.
action 객체는 버튼에서 수행할 맞춤 액션을 지정합니다. 고유 actionMethodName 및 키/값 매개변수 쌍 집합을 포함한 작업 객체에서 여러 임의의 값을 지정할 수 있습니다.
버튼의 action 객체를 지정하면 양방향 카드가 생성됩니다. 사용자가 메시지의 버튼을 클릭하면 Google Chat은 CARD_CLICKED 이벤트를 발생시키고 원본 메시지를 보낸 앱으로 다시 요청을 보냅니다. 그 다음 앱은 Google Chat에서 발생한 이벤트를 처리하고 스페이스에 다시 응답을 반환해야 합니다.
Code.gs의 onMessage() 함수를 코드를 다음 코드로 바꿉니다. 이 코드는 Google Chat으로 전송되는 카드에 Gmail에서 휴가 설정 버튼과 캘린더에서 사용 불가능한 날짜 버튼 등 2개의 버튼을 생성합니다.
Code.gs
var REASON = {
SICK: 'Out sick',
OTHER: 'Out of office'
};
/**
* Responds to a MESSAGE event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
*/
function onMessage(event) {
console.info(event);
var reason = REASON.OTHER;
var name = event.user.displayName;
var userMessage = event.message.text;
// If the user said that they were 'sick', adjust the image in the
// header sent in response.
if (userMessage.indexOf('sick') > -1) {
// Hospital material icon
HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
reason = REASON.SICK;
} else if (userMessage.indexOf('vacation') > -1) {
// Spa material icon
HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
}
var widgets = [{
textParagraph: {
text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
}
}, {
buttons: [{
textButton: {
text: 'Set vacation in Gmail',
onClick: {
action: {
actionMethodName: 'turnOnAutoResponder',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}, {
textButton: {
text: 'Block out day in Calendar',
onClick: {
action: {
actionMethodName: 'blockOutCalendar',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}]
}];
return createCardResponse(widgets);
}
CARD_CLICKED 이벤트를 처리하려면 채팅 앱의 스크립트에 onCardClick() 함수를 추가해야 합니다. onCardClick() 함수 Code.gs를 정의하는 다음 코드를 추가합니다.
Code.gs
/**
* Responds to a CARD_CLICKED event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/chat/api/guides/message-formats/events
*/
function onCardClick(event) {
console.info(event);
var message = '';
var reason = event.action.parameters[0].value;
if (event.action.actionMethodName == 'turnOnAutoResponder') {
turnOnAutoResponder(reason);
message = 'Turned on vacation settings.';
} else if (event.action.actionMethodName == 'blockOutCalendar') {
blockOutCalendar(reason);
message = 'Blocked out your calendar for the day.';
} else {
message = "I'm sorry; I'm not sure which button you clicked.";
}
return { text: message };
}
사용자 클릭에 응답할 때 이제 채팅 앱은 두 가지 작업 중 하나를 수행합니다. Gmail에서 사용자의 부재중 자동응답을 '부재중' 자동 답장으로 설정하거나 사용자의 캘린더에서 종일 회의 일정을 잡습니다. 이러한 작업을 수행하기 위해 해당 앱은 Gmail 고급 서비스 및 캘린더 서비스를 호출합니다.
다음 코드를 스크립트에 추가하여 채팅 앱을 Gmail 및 캘린더와 통합합니다.
Code.gs
var ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
* Turns on the user's vacation response for today in Gmail.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function turnOnAutoResponder(reason) {
var currentTime = (new Date()).getTime();
Gmail.Users.Settings.updateVacation({
enableAutoReply: true,
responseSubject: reason,
responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Bot!</i>",
restrictToContacts: true,
restrictToDomain: true,
startTime: currentTime,
endTime: currentTime + ONE_DAY_MILLIS
}, 'me');
}
/**
* Places an all-day meeting on the user's Calendar.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function blockOutCalendar(reason) {
CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}
마지막으로 프로젝트에서 Gmail 고급 서비스를 사용 설정해야 합니다. Gmail API를 사용하려면 다음을 수행합니다.
- Apps Script 편집기에서 서비스 옆에 있는 서비스 추가 를 클릭합니다.
- Gmail API를 선택합니다.
- 아래의 Google Cloud Platform API 대시보드를 클릭하면 Google Cloud 콘솔이 열립니다.
- API 및 서비스 사용 설정을 클릭합니다.
- Gmail API를 검색하고 Gmail API를 클릭합니다.
- Gmail API 페이지에서 사용 설정을 클릭합니다.
채팅 앱 테스트
이 버전의 채팅 앱을 테스트하려면 Google Chat의 이전 단계에서 시작한 DM을 열고 I'm going on vacation을 입력합니다. 앱에서 아래 이미지와 비슷한 카드로 응답합니다.
참고: 앱에 대한 액세스 권한을 제공하라는 메시지가 표시되면 메시지를 다시 입력해야 할 수 있습니다.
7. 수고하셨습니다.
이제 채팅 앱에서 사용자 메시지에 응답하고, Gmail에서 부재중 자동응답을 설정하고, 캘린더에 종일 일정을 추가할 수 있습니다.
학습한 내용
- Apps Script로 Google Chat 앱을 만들고 게시했습니다.
- 간단한 응답을 사용하여 사용자 메시지에 응답했습니다.
- 채팅 앱을 통해 사용자를 대신하여 다른 Google Workspace 서비스와 상호작용했습니다.