В этом руководстве объясняется, как настроить и использовать учетную запись службы для доступа к API Google Chat от имени приложения Chat. Сначала вы узнаете, как создать учетную запись службы. Затем демонстрируется, как написать сценарий, который использует учетную запись службы для аутентификации с помощью API чата и публикации сообщения в пространстве чата.
Приложения чата могут использовать учетные записи служб для аутентификации при асинхронном вызове API Google Chat, чтобы они могли:
- Отправляйте сообщения в Google Chat с помощью
spaces.messages.create
по адресу:- Уведомляйте пользователей о завершении длительного фонового задания.
- Предупреждайте пользователей о том, что сервер отключен от сети.
- Попросите сотрудника службы поддержки клиентов заняться вновь открытым обращением клиента.
- Обновите ранее отправленные сообщения с помощью
spaces.messages.update
, чтобы:- Измените статус текущей операции.
- Обновите ответственного за задачу или дату выполнения.
- Перечислите пользователей в пространстве с помощью
spaces.members.list
, чтобы:- Посмотрите, кто находится в пространстве.
- Убедитесь, что членство в пространстве включает всех членов команды.
При проверке подлинности с помощью учетной записи службы, чтобы получать данные о пространстве Chat или выполнять действия в нем, приложения Chat должны иметь членство в этом пространстве. Например, чтобы составить список участников пространства или создать сообщение в пространстве, приложение Chat само должно быть участником пространства.
Если вашему приложению чата требуется доступ к пользовательским данным или выполнение действий от имени пользователя, вместо этого выполните аутентификацию пользователя .
Если вы администратор домена, вы можете делегировать полномочия на уровне домена, чтобы разрешить сервисному аккаунту приложения доступ к данным ваших пользователей, не требуя согласия каждого пользователя. После настройки делегирования на уровне домена вы можете выполнять вызовы API, используя свою учетную запись службы, чтобы олицетворять учетную запись пользователя . Хотя для аутентификации используется учетная запись службы, делегирование на уровне домена олицетворяет пользователя и поэтому считается аутентификацией пользователя . Любую функциональность, требующую аутентификации пользователя, можно использовать делегирование на уровне домена.
Дополнительные сведения о том, когда приложениям 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, см. раздел Тестирование интерактивных функций для приложений Google Chat .
Питон
- Python 3.6 или выше
- Инструмент управления пакетами pip
- Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с использованием службы HTTP, выполните это краткое руководство .
- Добавьте приложение Chat в пространство. Чтобы добавить приложение Chat, см. раздел Тестирование интерактивных функций для приложений Google Chat .
Node.js
- Node.js 14 или более поздней версии
- Инструмент управления пакетами npm
- Инициализированный проект Node.js. Чтобы инициализировать новый проект, создайте новую папку и переключитесь на нее, затем выполните следующую команду в интерфейсе командной строки:
npm init
- Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с использованием службы HTTP, выполните это краткое руководство .
- Добавьте приложение Chat в пространство. Чтобы добавить приложение Chat, см. раздел Тестирование интерактивных функций для приложений Google Chat .
Скрипт приложений
- Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с помощью Apps Script, выполните это краткое руководство .
- Добавьте приложение Chat в пространство. Чтобы добавить приложение Chat, см. раздел Тестирование интерактивных функций для приложений Google Chat .
Шаг 1. Создайте учетную запись службы в консоли Google Cloud.
Создайте учетную запись службы, которую ваше приложение Chat сможет использовать для доступа к API Google.
Создать учетную запись службы
Чтобы создать учетную запись службы, выполните следующие действия:
Консоль Google Cloud
- В консоли Google Cloud выберите > IAM и администрирование > Учетные записи служб .
- Нажмите Создать учетную запись службы .
- Заполните данные учетной записи службы, затем нажмите «Создать» и продолжите .
- Необязательно: назначьте роли своему сервисному аккаунту, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Дополнительные сведения см. в разделе Предоставление, изменение и отзыв доступа к ресурсам .
- Нажмите Продолжить .
- Необязательно: укажите пользователей или группы, которые могут управлять этой учетной записью службы и выполнять действия с ней. Дополнительные сведения см. в разделе Управление олицетворением учетной записи службы .
- Нажмите Готово . Запишите адрес электронной почты для учетной записи службы.
интерфейс командной строки gcloud
- Создайте учетную запись службы:
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.
Шаг 2. Установите клиентскую библиотеку Google и другие зависимости.
Установите клиентскую библиотеку Google и другие зависимости, необходимые для проекта.
Ява
Чтобы добавить клиентские библиотеки Google и другие необходимые зависимости в ваш проект Maven, отредактируйте файл 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>
Питон
Если вы еще не установили клиентские библиотеки Google для Python, выполните следующую команду в интерфейсе командной строки:
pip3 install --upgrade google-api-python-client google-auth
Node.js
Чтобы добавить клиентские библиотеки Google в свой проект Node.js, перейдите в каталог вашего проекта и выполните следующую команду в интерфейсе командной строки:
npm install "@googleapis/chat"
Скрипт приложений
В этом примере используется библиотека сценариев OAuth2 для приложений для создания токена JWT для проверки подлинности учетной записи службы. Чтобы добавить библиотеку в проект Apps Script:
- Слева нажмите редактора» .
- Слева рядом с пунктом «Библиотеки» нажмите библиотеку» .
- Введите идентификатор сценария
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
. - Нажмите «Искать» , затем нажмите « Добавить» .
В этом примере используется служба Advanced Chat для вызова API Google Chat. Чтобы включить службу для проекта Apps Script:
- Слева нажмите редактора» .
- Слева рядом с пунктом «Услуги» нажмите услугу» .
- Выберите API Чата Google .
- В разделе «Версия» выберите v1 .
- Нажмите Добавить .
Вы можете использовать любой язык, поддерживаемый нашими клиентскими библиотеками .
Шаг 3. Напишите сценарий, который использует учетную запись службы для аутентификации с помощью Chat API.
Следующий код проверяет подлинность 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 via 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
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из 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>
Питон
- В своем рабочем каталоге создайте файл с
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. CREDENTIALS = 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=CREDENTIALS) # 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
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из 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
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из URL-адреса пространства. Убедитесь, что файл закрытого ключа для вашей учетной записи службы называетсяcredentials.json
.
Скрипт приложений
В редакторе Apps Script отредактируйте файл
appsscript.json
и добавьте область OAuth, необходимую для выполнения внешних запросов для получения токена OAuth сервисного аккаунта:"oauthScopes": [ "https://www.googleapis.com/auth/script.external_request" ]
Сохраните следующий код в файле с именем
ChatAppAuth.gs
в проекте Apps Script:// 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 via 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
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из URL-адреса пространства.
Шаг 4. Запустите полный пример
В своем рабочем каталоге соберите и запустите пример:
Ява
mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar
Питон
python3 chat_app_auth.py
Node.js
node chat_app_auth.js
Скрипт приложений
Откройте файл ChatAppAuth.gs
в редакторе сценариев приложений и нажмите « Выполнить» .
Ваш скрипт отправляет аутентифицированный запрос к API чата , который в ответ публикует сообщение в пространстве чата как приложение чата.
Устранение неполадок в примере
В этом разделе описаны распространенные проблемы, с которыми вы можете столкнуться при попытке запустить этот пример.
Вам не разрешено использовать это приложение
При запуске сценария вы можете получить сообщение об ошибке:
<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 API, из справочной документации Chat API.