Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google Chat API 구성

만드는 각 Google Chat 앱에는 Chat API가 사용 설정되고 구성된 자체 Google Cloud 프로젝트가 필요합니다.

스페이스 가져오기 및 메시지 나열과 같이 사용자 인증으로 읽기 전용 API 호출을 실행하려면 API를 사용 설정하고 OAuth 클라이언트를 만들기만 하면 됩니다.

API 호출을 생성, 업데이트, 삭제하거나 대화형 Chat 앱 (Chat을 확장하는 Google Workspace 부가기능으로 빌드됨)을 배포하고 테스트하려면 Chat API도 구성해야 합니다. Chat API 구성 설정에서는 표시 이름, 아바타, 배포 엔드포인트, 양방향 기능을 포함하여 Chat 앱에 관한 모든 세부정보를 지정합니다.

기본 요건

Google Chat에 액세스할 수 있는 Business 또는 Enterprise Google Workspace 계정
Google Cloud 프로젝트를 만듭니다.
OAuth 동의 화면 구성
Google Chat API를 사용 설정합니다.

Chat 앱의 표시 이름, 아바타, 설명을 선택합니다.

Chat API를 사용 설정하면 표시 이름, 아바타, 설명을 포함하여 Chat에서 사용자에게 표시되는 Chat 앱에 관한 세부정보를 구성합니다. 이러한 세부정보는 Chat에만 표시됩니다. Marketplace에 Chat 앱을 게시하려면 Chat 앱의 Marketplace 등록정보에 표시되는 세부정보도 지정해야 합니다.

Chat 앱을 구성하기 전에 다음 정보를 준비하세요.

필드	설명	형식
앱 이름	Chat 앱의 표시 이름입니다.	최대 25자의 영숫자 문자
아바타 URL	Chat 앱의 아바타로 표시되는 이미지입니다.	정사각형 그래픽 이미지 (PNG 또는 JPEG)를 가리키는 HTTPS URL입니다. 권장 크기는 256x256픽셀 이상입니다.
설명	Chat 앱의 목적에 대한 간단한 설명입니다.	최대 40자의 영숫자 문자

Chat 앱의 이름, 아바타, 설명은 Chat UI에서 사용자에게 표시됩니다. 일부 Chat API 쓰기 요청의 경우 Chat은 이 정보를 사용하여 Chat 앱이 Chat에서 수행하는 작업을 지정합니다.

예를 들어 spaces.create() 메서드를 호출하면 다음 이미지와 같이 Chat은 스페이스를 만든 사용자에 대한 설명에 Chat 앱의 이름을 포함합니다.

Google Chat 앱이 사용자를 위한 스페이스를 만듭니다. — **그림 1**. `spaces.create()` 메서드를 사용하여 사용자를 대신해 스페이스를 만들 때 Chat에서 표시하는 저작자 표시 메시지입니다.

채팅 앱과 상호작용하기 위해 사용자는 다음과 같은 방법으로 이 정보를 보거나 사용합니다.

Chat 앱을 @멘션하여 스페이스에 추가하거나 메시지를 보냅니다.
Chat 앱을 찾아 채팅 메시지를 시작합니다. 앱 메뉴에서 채팅 메시지에 Chat 앱의 이름과 아바타가 표시됩니다.
사용자는 작성 창에서 Chat 앱을 탐색하고 이름, 아바타, 설명을 확인할 수 있습니다.

Google Cloud 콘솔에서 Chat 앱 구성하기

Chat 앱 세부정보가 있으면 Cloud 프로젝트를 열고 Chat API를 구성합니다.

Google Cloud 콘솔에서 Chat API 페이지로 이동하여 구성 페이지를 클릭합니다.

Chat API 구성 페이지로 이동
애플리케이션 정보에서 앱 이름, 아바타 URL, 설명 필드를 작성합니다.
선택사항: 마크업 문법 메뉴에서 Chat 앱 메시지의 기본 마크업 문법(마크다운 또는 채팅)을 선택합니다. 텍스트 형식 지정과 Chat에서 API 요청의 마크업 문법을 결정하는 방법에 관한 자세한 내용은 메시지 형식 지정을 참고하세요.
대화형 기능에서 Chat 앱이 사용자 상호작용에 응답하는지 여부를 구성합니다.

참고: Chat 앱이 Chat API만 호출하고 사용자 상호작용을 수신하거나 이에 응답하지 않는 경우 대화형 기능 사용 설정을 사용 중지하고 다음 단계로 건너뜁니다.

대화형 Chat 앱을 빌드하려면 대화형 기능 사용 설정을 사용 설정하고 다음을 완료합니다.
1. 기능에서 다음을 수행합니다.
  - 선택사항: 앱 홈 지원을 선택하여 Chat 앱과의 1:1 채팅 메시지의 홈 탭에 홈페이지 카드를 표시합니다.
  - 스페이스 및 그룹 대화 참여를 선택하여 Chat 앱을 설치하고 사용할 수 있도록 합니다. 기본적으로 사용자는 사용자와 Chat 앱 간의 전용 스페이스에서 Chat 앱을 설치하고 메시지를 보낼 수 있습니다. 사용자는 여러 사용자가 있는 스페이스에서 Chat 앱을 추가하고 상호작용할 수도 있습니다.
2. 연결 설정에서 Chat에서 이벤트 객체를 수신하는 데 사용할 아키텍처를 선택합니다.
  - HTTP 서비스를 사용하려면 HTTP 엔드포인트 URL을 선택하고 URL을 제공합니다.
  - Google Apps Script 프로젝트를 사용하려면 Apps Script를 선택하고 프로젝트의 배포 ID를 제공합니다.
  - Dialogflow 에이전트를 사용하려면 Dialogflow를 선택하고 Dialogflow CX 또는 Dialogflow ES를 선택한 후 에이전트의 리소스 이름을 입력합니다.
  - Pub/Sub를 사용하려면 Cloud Pub/Sub를 선택하고 주제 이름을 입력합니다.
  경고: Apps Script 배포 ID가 이미 채워져 있으면 Cloud 프로젝트가 기존 Google Workspace 부가기능에 연결됩니다. Chat API에서 배포 ID를 업데이트하면 부가기능의 배포 ID가 업데이트되며 Google Workspace Marketplace의 등록정보에 영향을 미칠 수 있습니다. 부가기능 구성을 검토하려면 Google Workspace Marketplace SDK에서 앱 구성을 참고하세요.
3. 선택사항: 이벤트 객체를 특정 엔드포인트 또는 함수로 라우팅하려면 연결 설정 > 트리거로 이동하여 다음 Chat 트리거의 콜백 엔드포인트 또는 함수를 제공하거나 업데이트합니다.
  
  참고: Apps Script의 경우 트리거를 업데이트하지 않으면 이 섹션에 채워진 기본 콜백 함수 (예: onMessage, onAddedToSpace, onRemovedFromSpace, onAppCommand, onAppHome)를 구현해야 합니다.
  - 앱 홈 (앱 홈 지원이 사용 설정된 경우): 사용자가 Chat 앱과의 1:1 채팅 메시지에서 홈 탭을 엽니다.
  - 스페이스에 추가됨: 사용자가 그룹 대화 또는 스페이스에 Chat 앱을 추가하거나 1:1 메시지를 위해 Chat 앱을 설치합니다.
  - 메시지: 사용자가 Chat 앱에 메시지를 보냅니다. 예를 들어 사용자가 Chat 앱에 채팅 메시지를 보내거나 여러 사용자가 있는 스페이스에서 Chat 앱을 @멘션합니다.
  - 스페이스에서 삭제됨: 사용자가 스페이스에서 Chat 앱을 제거하거나 삭제합니다.
  - 앱 명령어: 사용자가 Chat 앱에서 빠른 명령어, 슬래시 명령어 또는 메시지 작업을 호출합니다.
4. 선택사항: 시작 프롬프트, 명령어 (빠른 명령어, 슬래시 명령어, 메시지 작업) 또는 링크 미리보기와 같은 다른 대화형 기능을 추가합니다.
5. 공개 상태에서 이메일 주소를 지정하여 Google Workspace Marketplace에 게시하기 전에 Chat 앱을 설치하고 테스트할 수 있습니다. Google Workspace 조직에서 최대 5명의 개인 또는 하나 이상의 Google 그룹스를 지정할 수 있습니다.
선택사항: 로그에서 Logging에 오류 로깅 체크박스를 선택하여 Google Cloud Logging을 사용합니다. 자세한 내용은 Chat 앱의 오류 로그 쿼리를 참고하세요.
저장을 클릭합니다.

구성을 저장하면 Chat API의 공개 상태 설정에 지정한 모든 사용자가 Chat 앱을 설치, 테스트 또는 사용할 수 있습니다. Chat 앱 테스트 및 디버깅을 시작하려면 Google Chat 앱의 대화형 기능 테스트를 참고하세요.

Google Workspace Add-ons API를 사용하여 채팅 앱 구성

Google Cloud 콘솔에서 Chat 앱을 수동으로 구성하는 대신 Google Workspace 개발자 프리뷰 프로그램에 등록된 Google Cloud 프로젝트를 사용하여 Google Workspace add-ons API의 chatAppConfig 리소스를 통해 Google Workspace 부가기능으로 빌드된 Chat 앱의 구성을 프로그래매틱 방식으로 읽고 업데이트할 수 있습니다.

chatAppConfig는 각 Cloud 프로젝트에 항상 존재하는 싱글톤 리소스입니다. 구성을 처음 저장하기 전에는 리소스에 빈 구성이 포함됩니다. 이는 첫 번째 저장 전에 리소스를 읽는 경우 GetChatAppConfig가 반환하는 항목이기도 합니다. 리소스가 이미 존재하므로 별도로 만들 필요가 없습니다. UpdateChatAppConfig를 사용하여 초기 구성을 저장하고 기존 구성을 업데이트합니다.

기본 요건 및 인증

GetChatAppConfig 또는 UpdateChatAppConfig를 호출하기 전에 다음 기본 요건을 완료하세요.

Google Workspace 개발자 프리뷰 프로그램에 Google Cloud 프로젝트를 등록합니다.
Cloud 프로젝트에서 Google Workspace 부가기능 API(gsuiteaddons.googleapis.com)를 사용 설정합니다. 원하는 경우 Google Cloud 콘솔에서 Chat 앱 구성을 보거나 업데이트하거나 Chat API를 호출하려면 Google Chat API (chat.googleapis.com)를 사용 설정하면 됩니다.
https://www.googleapis.com/auth/cloud-platform 범위를 포함하는 OAuth 2.0 사용자 인증 정보를 사용하여 사람 사용자로 인증합니다. chatAppConfig 메서드에는 서비스 계정 인증이 지원되지 않습니다.
인증된 사용자에게 대상 Cloud 프로젝트에 필요한 Identity and Access Management (IAM) 권한이 있는지 확인합니다.
- gsuiteaddons.chatAppConfigs.get 및 chat.bots.get: 구성 (GetChatAppConfig)을 읽습니다.
- gsuiteaddons.chatAppConfigs.update 및 chat.bots.update를 사용하여 구성 (UpdateChatAppConfig)을 업데이트합니다.
클라이언트 라이브러리를 사용하는 경우 등록된 개발자 프리뷰 계정으로 개발자 프리뷰 클라이언트 라이브러리를 다운로드합니다.

Chat 앱 구성 업데이트

Chat 앱을 처음 구성하거나 기존 구성을 업데이트하려면 Cloud 프로젝트의 싱글톤 chatAppConfig 리소스에 PATCH 요청(UpdateChatAppConfig)을 전송합니다.

chatAppConfig가 비어 있는 클라우드 프로젝트를 처음 저장하려면 displayName (3~25자) 및 description (1~40자)가 필요합니다. 처음 저장할 때 interactiveFeatureConfig를 생략하면 Chat 앱이 비대화형으로 구성됩니다.
이후 업데이트의 경우 선택적 updateMask 쿼리 매개변수를 사용하여 업데이트할 쉼표로 구분된 필드를 지정합니다 (또는 updateMask를 생략하여 제공된 모든 필드를 업데이트). 반복되는 입력란 (appCommands, urlPatterns 또는 allowlistedTestingPrincipals)을 업데이트하면 전체 목록이 대체됩니다.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

요청 URL, 헤더, 본문에서 다음을 바꿉니다.

PROJECT_NUMBER: Chat 앱을 호스팅하는 Cloud 프로젝트의 숫자 프로젝트 번호입니다.
ACCESS_TOKEN: https://www.googleapis.com/auth/cloud-platform 범위로 승인된 사용자 OAuth 2.0 액세스 토큰입니다.
USER_EMAIL: Chat 앱을 테스트하기 위해 허용 목록에 추가할 Google Workspace 조직의 이메일 주소 또는 Google 그룹입니다 (예: 본인의 이메일 주소).
요청 본문의 예시 구성 필드 (예: displayName, description, avatarUri, interactiveFeatureConfig, 엔드포인트 구성, 명령어, 링크 미리보기 URL 패턴, 테스트 주 구성원 포함)를 Chat 앱의 값으로 바꿉니다. 지원되는 모든 필드 및 엔드포인트 옵션에 관한 자세한 내용은 projects.chatAppConfig REST 참조 및 projects.chatAppConfig.patch를 참고하세요.

Chat 앱 구성 가져오기

Cloud 프로젝트의 현재 Chat 앱 구성을 읽으려면 GetChatAppConfig를 호출합니다. 선택사항인 view 쿼리 매개변수 (ChatAppConfigView)를 전달할 수 있습니다.

BASIC (기본값): interactiveFeatureConfig 없이 기본 메타데이터를 반환합니다.
FULL: interactiveFeatureConfig를 포함한 모든 구성 필드를 반환합니다.

Cloud 프로젝트에 Chat 앱 구성이 아직 저장되지 않은 경우 이 메서드는 빈 ChatAppConfig 객체를 반환합니다.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

기존 Google Workspace 부가기능에 대한 고려사항

채팅 앱은 다른 Google Workspace 애플리케이션을 확장하는 Google Workspace 부가기능과 다른 구성이 필요합니다. 부가기능이 다른 Google Workspace 애플리케이션을 확장하는 경우 Chat 앱을 구성할 때 다음 요구사항을 고려하세요.

개인과 Google Workspace 관리자 모두 Marketplace에서 부가기능을 설치할 수 있어야 합니다. 이러한 설치 설정은 Marketplace SDK에서 구성합니다.
채팅 앱은 매니페스트의 addons.common 객체에서 다른 Google Workspace 애플리케이션에 구성한 이름과 로고를 사용하지 않습니다.
Google Workspace Marketplace에 게시된 부가기능의 경우 Google Chat API 구성 설정의 변경사항 초안을 저장할 수 없습니다. Chat API 구성 설정을 업데이트하고 저장하면 업데이트된 Chat 앱을 모든 기존 사용자가 즉시 사용할 수 있습니다. 마켓플레이스 등록정보를 업데이트하려면 변경사항을 제출하기 전에 초안을 작성하면 됩니다.
Apps Script를 사용하여 부가기능을 빌드한 경우:
- 부가기능 구성의 나머지 부분에 사용하는 것과 동일한 Apps Script 배포 ID를 사용해야 합니다.
- Apps Script 편집기를 사용하여 Chat에 테스트 배포를 설치할 수 없습니다. 대신 Chat UI에서 직접 설치해야 합니다.
HTTP 서비스를 사용하여 부가기능을 빌드한 경우 Google Workspace 부가기능 API를 사용하여 만드는 projects.deployments 매니페스트에서 채팅 앱 구성 세부정보를 생략합니다. Google Workspace Marketplace SDK에서 지정하는 HTTP 배포는 다른 Google Workspace 애플리케이션에만 사용됩니다. 대신 Google Cloud 콘솔에서 또는 Google Workspace Add-ons API의 chatAppConfig 리소스를 사용하여 Chat 앱을 구성하세요.

다른 사용자에게 Chat API를 구성할 수 있는 권한 부여하기

Chat 앱 소유자 또는 Chat 앱 뷰어 Google Cloud Identity Access Management (IAM) 역할을 부여하여 특정 사용자에게 Chat 앱 구성 페이지에 대한 액세스 권한을 부여할 수 있습니다. 이러한 역할이 있는 사용자는 API 및 서비스 대시보드를 사용하여 Chat 앱 구성 페이지로 이동할 수 없지만 다음과 같이 Chat 앱의 호스트 Cloud 프로젝트의 Google Cloud 콘솔로 이동하여 구성 페이지에 액세스할 수 있습니다.

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

여기서 PROJECT_ID는 Chat 앱을 호스팅하는 Google Cloud 프로젝트의 프로젝트 ID입니다.

부가기능이 아닌 Chat 앱: Google Chat API 구성

Google Workspace 부가기능이 아닌 Chat 앱을 유지관리하는 경우 구성에서 이벤트별 트리거가 아닌 모든 상호작용 이벤트에 단일 엔드포인트를 사용합니다.

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

Chat API 구성 페이지로 이동
양방향 기능에서 양방향 기능 사용 설정을 사용 설정합니다.
이 채팅 앱을 Google Workspace 부가기능으로 빌드를 선택 해제합니다. 확인하라는 대화상자가 열립니다. 대화상자에서 사용 중지를 클릭합니다.
기능에서 필요에 따라 앱 홈 지원 또는 스페이스 및 그룹 대화 참여를 선택합니다.
연결 설정에서 Chat 앱의 단일 엔드포인트 (HTTP 엔드포인트 URL, Apps Script 배포 ID, Cloud Pub/Sub 주제 이름 또는 Dialogflow)를 지정합니다.
선택사항인 명령어, 링크 미리보기, 공개 상태, 로그를 구성한 후 저장을 클릭합니다.

부가기능이 아닌 Chat 앱을 Google Chat을 확장하는 Google Workspace 부가기능으로 업그레이드하려면 Google Chat 앱을 Google Workspace 부가기능으로 변환을 참고하세요.