이 가이드에서는 서비스 계정을 설정하고 사용하여 Chat 앱을 대신하여 Google Chat API에 액세스하는 방법을 설명합니다. 먼저 서비스 계정을 만드는 방법을 안내합니다. 그런 다음 서비스 계정을 사용하여 Chat API로 인증하고 Chat 스페이스에 메시지를 게시하는 스크립트를 작성하는 방법을 보여줍니다.
서비스 계정으로 인증된 경우 Chat 스페이스에 관한 데이터를 가져오거나 스페이스에서 작업을 실행하려면 Chat 앱에 스페이스 멤버십이 있어야 합니다. 예를 들어 스페이스의 구성원을 나열하거나 스페이스에서 메시지를 만들려면 Chat 앱이 스페이스의 구성원 자체여야 합니다. 유일한 예외는 Chat 앱이 앱 인증으로 스페이스를 만드는 경우입니다. 이 경우 앱이 스페이스를 만든 후 자동으로 참여자가 됩니다.
이름이 https://www.googleapis.com/auth/chat.app.*
로 시작하는 승인 범위로 앱 승인을 지원하는 Google Chat API 메서드에는 일회성 관리자 승인이 필요합니다.
https://www.googleapis.com/auth/chat.bot
승인 범위로 앱 승인을 지원하는 Google Chat API 메서드에는 추가 승인이 필요하지 않습니다. https://www.googleapis.com/auth/chat.app.*
승인 범위는 개발자 프리뷰에서 사용할 수 있습니다.
Chat 앱에서 사용자 데이터에 액세스하거나 사용자를 대신하여 작업을 실행해야 하는 경우 대신 사용자로 인증하세요. 도메인 관리자는 각 사용자의 동의를 받지 않고도 Chat 앱의 서비스 계정에서 사용자의 데이터에 액세스할 수 있도록 승인하는 도메인 전체 권한 위임을 부여할 수 있습니다. 자세한 내용은 도메인 전체 위임을 사용하여 인증 및 승인을 참고하세요.
Chat 앱에 인증이 필요한 경우와 사용할 인증 유형에 관한 자세한 내용은 Chat API 인증 및 승인 개요의 필수 인증 유형을 참고하세요.
기본 요건
자바
- JDK 1.7 이상
- Maven 패키지 관리 도구
-
초기화된 Maven 프로젝트입니다. 새 프로젝트를 초기화하려면 명령줄 인터페이스에서 다음 명령어를 실행합니다.
mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
- 대화형 기능이 사용 설정된 Google Chat 앱 HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.
- 스페이스에 Chat 앱을 추가합니다. Chat 앱을 추가하려면 Google Chat 앱의 대화형 기능 테스트를 참고하세요.
Python
- Python 3.6 이상
- pip 패키지 관리 도구
- 대화형 기능이 사용 설정된 Google Chat 앱 HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.
- 스페이스에 Chat 앱을 추가합니다. Chat 앱을 추가하려면 Google Chat 앱의 대화형 기능 테스트를 참고하세요.
Node.js
- Node.js 14 이상
- npm 패키지 관리 도구
-
초기화된 Node.js 프로젝트 새 프로젝트를 초기화하려면 새 폴더를 만들고 이 폴더로 전환한 다음 명령줄 인터페이스에서 다음 명령어를 실행합니다.
npm init
- 대화형 기능이 사용 설정된 Google Chat 앱 HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.
- 스페이스에 Chat 앱을 추가합니다. Chat 앱을 추가하려면 Google Chat 앱의 대화형 기능 테스트를 참고하세요.
Apps Script
- 대화형 기능이 사용 설정된 Google Chat 앱 Apps Script에서 양방향 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.
- 스페이스에 Chat 앱을 추가합니다. Chat 앱을 추가하려면 Google Chat 앱의 대화형 기능 테스트를 참고하세요.
1단계: Google Cloud 콘솔에서 서비스 계정 만들기
Chat 앱에서 Google API에 액세스하는 데 사용할 수 있는 서비스 계정을 만듭니다.
서비스 계정 만들기
서비스 계정을 만드는 방법은 다음과 같습니다.
Google Cloud 콘솔
- Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.
- 서비스 계정 만들기를 클릭합니다.
- 서비스 계정 세부정보를 입력한 다음 만들고 계속하기를 클릭합니다.
- 선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
- 계속을 클릭합니다.
- 선택사항: 이 서비스 계정으로 작업을 관리하고 실행할 수 있는 사용자 또는 그룹을 입력합니다. 자세한 내용은 서비스 계정 명의 도용 관리를 참고하세요.
- 완료를 클릭합니다. 서비스 계정의 이메일 주소를 기록해 둡니다.
gcloud CLI
- 서비스 계정을 만듭니다.
gcloud iam service-accounts create
SERVICE_ACCOUNT_NAME
\ --display-name="SERVICE_ACCOUNT_NAME
" - 선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
서비스 계정이 서비스 계정 페이지에 표시됩니다. 다음으로 서비스 계정의 비공개 키를 만듭니다.
비공개 키 만들기
서비스 계정의 비공개 키를 만들고 다운로드하려면 다음 단계를 따르세요.
- Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.
- 서비스 계정을 선택합니다.
- 키 > 키 추가 > 새 키 만들기를 클릭합니다.
- JSON을 선택한 다음 만들기를 클릭합니다.
새 공개 키/비공개 키 쌍이 생성되어 새 파일로 머신에 다운로드됩니다. 다운로드한 JSON 파일을 작업 디렉터리에
credentials.json
로 저장합니다. 이 파일은 이 키의 유일한 사본입니다. 키를 안전하게 저장하는 방법에 관한 자세한 내용은 서비스 계정 키 관리를 참고하세요. - 닫기를 클릭합니다.
서비스 계정에 대한 자세한 내용은 Google Cloud IAM 문서의 서비스 계정을 참고하세요.
다음으로 이 서비스 계정에 대해 Google Workspace Marketplace 호환 OAuth 클라이언트를 만듭니다.
관리자 승인 받기
개발자 프리뷰의 일부로 제공되는 https://www.googleapis.com/auth/chat.app.*
로 시작하는 승인 범위를 사용하려면 Chat 앱에서 일회성 관리자 승인을 받아야 합니다.
https://www.googleapis.com/auth/chat.bot
승인 범위를 사용하려면 관리자 승인이 필요하지 않습니다.
관리자 승인을 받으려면 다음 정보로 Chat 앱의 서비스 계정을 준비해야 합니다.
- Google Workspace Marketplace 호환 OAuth 클라이언트
- Google Workspace Marketplace SDK의 앱 구성
Google Workspace Marketplace 호환 OAuth 클라이언트 만들기
Google Workspace Marketplace 호환 OAuth 클라이언트를 만들려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.
Chat 앱용으로 만든 서비스 계정을 클릭합니다.
고급 설정을 클릭합니다.
Google Workspace Marketplace 호환 OAuth 클라이언트 만들기를 클릭합니다.
계속을 클릭합니다.
Google Workspace Marketplace 호환 OAuth 클라이언트가 생성되었다는 확인 메시지가 표시됩니다.
Google Workspace Marketplace SDK에서 Chat 앱 구성
Google Workspace Marketplace SDK에서 Chat 앱을 구성하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Google Workspace Marketplace SDK를 사용 설정합니다.
Google Cloud 콘솔에서 메뉴 > API 및 서비스 > 사용 설정된 API 및 서비스 > Google Workspace 마켓플레이스 SDK > 앱 구성으로 이동합니다.
앱 구성 페이지를 작성합니다. Chat 앱을 구성하는 방법은 의도한 시청자층과 기타 요인에 따라 다릅니다. 앱 구성 페이지를 작성하는 데 도움이 필요한 경우 Google Workspace Marketplace SDK에서 앱 구성을 참고하세요. 이 가이드의 목적을 위해 다음 정보를 입력합니다.
- 앱 표시 여부에서 비공개를 선택합니다.
- 설치 설정에서 개인 + 관리자 설치를 선택합니다.
- 앱 통합에서 Chat 앱을 선택합니다.
OAuth 범위에서 Chat 앱에서 사용하는 모든 인증 범위를 입력합니다.
개발자 정보에서 개발자 이름, 개발자 웹사이트 URL, 개발자 이메일을 입력합니다.
초안 저장을 클릭합니다.
관리자 승인 받기
이제 서비스 계정이 관리자 승인을 받도록 구성되었으므로 Chat 앱 승인 설정의 단계에 따라 승인을 부여할 수 있는 Google Workspace 관리자에게 승인을 받습니다.
2단계: Google 클라이언트 라이브러리 및 기타 종속 항목 설치
프로젝트에 필요한 Google 클라이언트 라이브러리 및 기타 종속 항목을 설치합니다.
자바
Maven 프로젝트에 Google 클라이언트 라이브러리 및 기타 필수 종속 항목을 추가하려면 프로젝트 디렉터리의 pom.xml
파일을 수정하고 다음 종속 항목을 추가합니다.
<dependencies>
<!-- ... existing dependencies ... -->
<dependency>
<groupId>com.google.apis</groupId>
<artifactId>google-api-services-chat</artifactId>
<version>v1-rev20230905-2.0.0</version>
</dependency>
<dependency>
<groupId>com.google.auth</groupId>
<artifactId>google-auth-library-oauth2-http</artifactId>
<version>1.19.0</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>
</dependencies>
Python
Python용 Google 클라이언트 라이브러리가 아직 설치되어 있지 않은 경우 명령줄 인터페이스에서 다음 명령어를 실행합니다.
pip3 install --upgrade google-api-python-client google-auth
Node.js
Node.js 프로젝트에 Google 클라이언트 라이브러리를 추가하려면 프로젝트 디렉터리로 전환하고 명령줄 인터페이스에서 다음 명령어를 실행합니다.
npm install "@googleapis/chat"
Apps Script
이 샘플은 Apps Script용 OAuth2 라이브러리를 사용하여 서비스 계정 인증을 위한 JWT 토큰을 생성합니다. Apps Script 프로젝트에 라이브러리를 추가하려면 다음 단계를 따르세요.
- 왼쪽에서 편집기 를 클릭합니다.
- 왼쪽의 라이브러리 옆에 있는 라이브러리 추가 를 클릭합니다.
- 스크립트 ID
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
를 입력합니다. - Look up을 클릭한 다음 Add를 클릭합니다.
이 샘플은 고급 Chat 서비스를 사용하여 Google Chat API를 호출합니다. Apps Script 프로젝트에 서비스를 사용 설정하려면 다음 단계를 따르세요.
- 왼쪽에서 편집기 를 클릭합니다.
- 왼쪽의 서비스 옆에 있는 서비스 추가 를 클릭합니다.
- Google Chat API를 선택합니다.
- 버전에서 v1을 선택합니다.
- 추가를 클릭합니다.
Google 클라이언트 라이브러리에서 지원하는 모든 언어를 사용할 수 있습니다.
3단계: 서비스 계정을 사용하여 Chat API로 인증하는 스크립트 작성
다음 코드는 서비스 계정을 사용하여 Chat API로 인증한 후 Chat 스페이스에 메시지를 게시합니다.
자바
- 프로젝트 디렉터리에서
src/main/java/com/google/chat/app/authsample/App.java
파일을 엽니다. App.java
의 내용을 다음 코드로 바꿉니다.package com.google.chat.app.authsample; import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport; import com.google.api.client.http.HttpRequestInitializer; import com.google.api.client.json.gson.GsonFactory; import com.google.api.services.chat.v1.HangoutsChat; import com.google.api.services.chat.v1.model.Message; import com.google.auth.http.HttpCredentialsAdapter; import com.google.auth.oauth2.GoogleCredentials; /** * Authenticates with Chat API using service account credentials, * then creates a Chat message. */ public class App { // Specify required scopes. private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot"; // Specify service account details. private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json"; public static void main( String[] args ) { try { // Run app. Message response = App.createChatMessage(); // Print details about the created message. System.out.println(response); } catch (Exception e) { e.printStackTrace(); } } private static Message createChatMessage() throws Exception { // Build the Chat API client and authenticate with the service account. GoogleCredentials credentials = GoogleCredentials.fromStream( App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI)) .createScoped(CHAT_SCOPE); HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials); HangoutsChat chatService = new HangoutsChat.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), requestInitializer) .setApplicationName("auth-sample-app") .build(); // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. String spaceName = "spaces/SPACE_NAME"; // Create a Chat message. Message message = new Message().setText("Hello, world!"); return chatService.spaces().messages().create(spaceName, message).execute(); } }
코드에서
SPACE_NAME
를 스페이스 이름으로 바꿉니다. 스페이스 이름은 Chat API의spaces.list
메서드 또는 스페이스의 URL에서 가져올 수 있습니다.프로젝트 디렉터리 내에
resources
라는 새 하위 디렉터리를 만듭니다.서비스 계정의 비공개 키 파일 이름이
credentials.json
인지 확인하고resources
하위 디렉터리에 복사합니다.프로젝트 패키지에 비공개 키 파일을 포함하도록 Maven을 구성하려면 프로젝트 디렉터리의
pom.xml
파일을 수정하고<build>
섹션에 다음 구성을 추가합니다.<build> <!-- ... existing configurations ... --> <resources> <resource> <directory>resources</directory> </resource> </resources> </build>
프로젝트 패키지에 종속 항목을 포함하고 애플리케이션의 기본 클래스를 실행하도록 Maven을 구성하려면 프로젝트 디렉터리의
pom.xml
파일을 수정하고<plugins>
섹션에 다음 구성을 추가합니다.<plugins> <!-- ... existing configurations ... --> <plugin> <artifactId>maven-assembly-plugin</artifactId> <configuration> <archive> <manifest> <mainClass>com.google.chat.app.authsample.App</mainClass> </manifest> </archive> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> </configuration> </plugin> </plugins>
Python
- 작업 디렉터리에
chat_app_auth.py
라는 파일을 만듭니다. chat_app_auth.py
에 다음 코드를 포함합니다.from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. creds = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=creds) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE_NAME with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE_NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result)
코드에서
SPACE_NAME
를 스페이스 이름으로 바꿉니다. 스페이스 이름은 Chat API의spaces.list
메서드 또는 스페이스의 URL에서 가져올 수 있습니다. 서비스 계정의 비공개 키 파일 이름이credentials.json
인지 확인합니다.
Node.js
- 프로젝트 디렉터리에서
chat_app_auth.js
라는 파일을 만듭니다. chat_app_auth.js
에 다음 코드를 포함합니다.const chat = require('@googleapis/chat'); async function createMessage() { const auth = new chat.auth.GoogleAuth({ // Specify service account details. keyFilename: 'credentials.json', // Specify required scopes. scopes: ['https://www.googleapis.com/auth/chat.bot'] }); const authClient = await auth.getClient(); // Create the Chat API client and authenticate with the service account. const chatClient = await chat.chat({ version: 'v1', auth: authClient }); // Create a Chat message. const result = await chatClient.spaces.messages.create({ // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. parent: 'spaces/SPACE_NAME', // The message to create. requestBody: { 'text': 'Hello, world!' } }); return result; } // Execute function then print details about the created message. createMessage().then(console.log);
코드에서
SPACE_NAME
를 스페이스 이름으로 바꿉니다. 스페이스 이름은 Chat API의spaces.list
메서드 또는 스페이스의 URL에서 가져올 수 있습니다. 서비스 계정의 비공개 키 파일 이름이credentials.json
인지 확인합니다.
Apps Script
Apps Script 편집기에서
appsscript.json
파일을 수정하고 서비스 계정 OAuth 토큰을 가져오기 위한 외부 요청을 하는 데 필요한 OAuth 범위를 추가합니다."oauthScopes": [ "https://www.googleapis.com/auth/script.external_request" ]
Apps Script 프로젝트의
ChatAppAuth.gs
파일에 다음 코드를 저장합니다.// Specify the contents of the file credentials.json. const CREDENTIALS = CREDENTIALS; const SCOPE = 'https://www.googleapis.com/auth/chat.bot'; // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. const PARENT = 'spaces/SPACE_NAME' /** * Authenticates with Chat API using app credentials, then posts a message. */ function createMessageWithAppCredentials() { try { const service = getService_(); if (!service.hasAccess()) { console.error(service.getLastError()); return; } // Specify the message to create. const message = {'text': 'Hello world!'}; // Call Chat API with a service account to create a message. const result = Chat.Spaces.Messages.create( message, PARENT, {}, // Authenticate with the service account token. {'Authorization': 'Bearer ' + service.getAccessToken()}); // Log details about the created message. console.log(result); } catch (err) { // TODO (developer) - Handle exception. console.log('Failed to create message with error %s', err.message); } } /** * Configures the OAuth library to authenticate with the service account. */ function getService_() { return OAuth2.createService(CREDENTIALS.client_email) .setTokenUrl('https://oauth2.googleapis.com/token') .setPrivateKey(CREDENTIALS.private_key) .setIssuer(CREDENTIALS.client_email) .setSubject(CREDENTIALS.client_email) .setScope(SCOPE) .setPropertyStore(PropertiesService.getScriptProperties()); }
코드에서
CREDENTIALS
를credentials.json
파일의 콘텐츠로 바꿉니다.코드에서
SPACE_NAME
를 스페이스 이름으로 바꿉니다. 스페이스 이름은 Chat API의spaces.list
메서드 또는 스페이스의 URL에서 가져올 수 있습니다.
4단계: 전체 예시 실행
작업 디렉터리에서 샘플을 빌드하고 실행합니다.
자바
mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar
Python
python3 chat_app_auth.py
Node.js
node chat_app_auth.js
Apps Script
Apps Script 편집기에서 ChatAppAuth.gs
파일을 열고 Run을 클릭합니다.
스크립트는 Chat API에 인증된 요청을 실행하고, Chat 스페이스에 Chat 앱으로 메시지를 게시하여 응답합니다.
예시 문제 해결
이 섹션에서는 이 샘플을 실행하려고 할 때 발생할 수 있는 일반적인 문제를 설명합니다.
이 앱을 사용할 수 없습니다.
스크립트를 실행할 때 다음과 같은 오류가 표시될 수 있습니다.
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">
이 오류 메시지는 Chat 앱에 지정된 Chat 스페이스에서 Chat 메시지를 만들 권한이 없음을 의미합니다.
이 오류를 해결하려면 스크립트에 지정된 Chat 스페이스에 Chat 앱을 추가합니다.
관리자가 앱에 이 작업에 필요한 OAuth 승인 범위를 부여해야 합니다.
스크립트를 실행할 때 다음과 같은 오류가 표시될 수 있습니다.
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">
이 오류 메시지는 Google Workspace 관리자가 아직 Chat 앱에 https://www.googleapis.com/auth/chat.app.*
이름으로 시작하는 승인 범위를 사용하도록 일회성 승인을 부여하지 않았음을 의미합니다.
이 오류를 해결하려면 다음 단계를 따르세요.
- Google Workspace 관리자에게 Chat 앱 승인을 요청합니다. Chat 앱 로직에서 이 오류를 처리할 때는 요청된 작업을 실행하려면 Chat 앱에 관리자 승인이 필요하다고 알리는 메시지를 전송하는 것이 좋습니다(예:
To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
). - Google Chat API 메서드가 관리자 승인이 필요하지 않은
https://www.googleapis.com/auth/chat.bot
승인 범위를 지원하는 경우 이를 대신 사용하는 것이 좋습니다. 메서드가 지원하는 승인 범위를 확인하려면 Google Chat API 참조 문서를 참고하세요.
관련 주제
- Chat API 참조 문서를 검토하여 Chat API의 다른 기능을 알아보세요.
https://www.googleapis.com/auth/chat.app.*
로 시작하는 OAuth 승인 범위를 사용하는 경우 관리자가 일회성 승인을 부여하는 방법을 알아보세요.