Аутентификация в приложении Google Chat

В этом руководстве объясняется, как настроить и использовать учетную запись службы для доступа к 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
    

Питон

  • Python 3.6 или выше
  • Инструмент управления пакетами pip

Node.js

  • Node.js
  • Инструмент управления пакетами npm
  • Инициализированный проект Node.js. Чтобы инициализировать новый проект, создайте новую папку и переключитесь на нее, затем выполните следующую команду в интерфейсе командной строки:

    npm init
    

Скрипт приложений

Шаг 1. Создайте учетную запись службы в консоли Google Cloud.

Создайте учетную запись службы, которую ваше приложение Chat сможет использовать для доступа к API Google.

Создать учетную запись службы

Чтобы создать учетную запись службы, выполните следующие действия:

Консоль Google Cloud

  1. В консоли Google Cloud выберите > IAM и администрирование > Учетные записи служб .

    Перейти к учетным записям служб

  2. Нажмите Создать учетную запись службы .
  3. Заполните данные учетной записи службы, затем нажмите «Создать и продолжить» .
  4. Необязательно: назначьте роли своему сервисному аккаунту, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Дополнительные сведения см. в разделе Предоставление, изменение и отзыв доступа к ресурсам .
  5. Нажмите Продолжить .
  6. Необязательно: укажите пользователей или группы, которые могут управлять этой учетной записью службы и выполнять действия с ней. Дополнительные сведения см. в разделе Управление олицетворением учетной записи службы .
  7. Нажмите Готово . Запишите адрес электронной почты для учетной записи службы.

интерфейс командной строки gcloud

  1. Создайте учетную запись службы:
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name="SERVICE_ACCOUNT_NAME"
  2. Необязательно: назначьте роли своему сервисному аккаунту, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Дополнительные сведения см. в разделе Предоставление, изменение и отзыв доступа к ресурсам .

Учетная запись службы отображается на странице учетной записи службы. Затем создайте закрытый ключ для учетной записи службы.

Создать закрытый ключ

Чтобы создать и загрузить закрытый ключ для учетной записи службы, выполните следующие действия:

  1. В консоли Google Cloud выберите > IAM и администрирование > Учетные записи служб .

    Перейти к учетным записям служб

  2. Выберите свою учетную запись службы.
  3. Нажмите «Ключи» > «Добавить ключ» > «Создать новый ключ» .
  4. Выберите JSON , затем нажмите «Создать» .

    Ваша новая пара открытого/закрытого ключей генерируется и загружается на ваш компьютер в виде нового файла. Сохраните загруженный файл JSON как credentials.json в своем рабочем каталоге. Этот файл является единственной копией этого ключа. Информацию о том, как безопасно хранить ключ, см. в разделе Управление ключами учетной записи службы .

  5. Нажмите Закрыть .

Дополнительную информацию об учетных записях служб см. в учетных записях служб в документации 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:

  1. Слева нажмите редактора» .
  2. Слева рядом с пунктом «Библиотеки » нажмите « библиотеку» .
  3. Введите идентификатор сценария 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF .
  4. Нажмите «Искать» , затем нажмите «Добавить» .

В этом примере используется служба Advanced Chat для вызова API Google Chat. Чтобы включить службу для проекта Apps Script:

  1. Слева нажмите редактора» .
  2. Слева рядом с пунктом «Услуги » нажмите « услугу» .
  3. Выберите API Чата Google .
  4. В разделе «Версия» выберите v1 .
  5. Нажмите Добавить .

Вы можете использовать любой язык, поддерживаемый нашими клиентскими библиотеками .

Шаг 3. Напишите сценарий, который использует учетную запись службы для аутентификации с помощью Chat API.

Следующий код проверяет подлинность API Chat с использованием учетной записи службы, а затем отправляет сообщение в пространство чата:

Джава

  1. В каталоге вашего проекта откройте файл src/main/java/com/google/chat/app/authsample/App.java .
  2. Замените содержимое 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();
        }
    }
    
  3. В коде замените SPACE_NAME именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства.

  4. Создайте новый подкаталог с именем resources в каталоге вашего проекта.

  5. Убедитесь, что файл закрытого ключа для вашей учетной записи службы называется credentials.json , и скопируйте его в подкаталог resources .

  6. Чтобы настроить Maven для включения файла закрытого ключа в пакет проекта, отредактируйте файл pom.xml в каталоге вашего проекта и добавьте следующую конфигурацию в раздел <build> :

    <build>
      <!-- ... existing configurations ... -->
      <resources>
        <resource>
          <directory>resources</directory>
        </resource>
      </resources>
    </build>
    
  7. Чтобы настроить 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>
    

Питон

  1. В своем рабочем каталоге создайте файл с chat_app_auth.py .
  2. Включите следующий код в 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)
    
  3. В коде замените SPACE_NAME именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства. Убедитесь, что файл закрытого ключа для вашей учетной записи службы имеет имя credentials.json .

Node.js

  1. В каталоге вашего проекта создайте файл с chat_app_auth.js .
  2. Включите следующий код 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);
    
  3. В коде замените SPACE_NAME именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства. Убедитесь, что файл закрытого ключа для вашей учетной записи службы имеет имя credentials.json .

Скрипт приложений

  1. В редакторе Apps Script отредактируйте файл appsscript.json и добавьте область OAuth, необходимую для выполнения внешних запросов для получения токена OAuth сервисного аккаунта:

      "oauthScopes": [
        "https://www.googleapis.com/auth/script.external_request"
      ]
    
  2. Сохраните следующий код в файле с именем 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());
    }
    
  3. В коде замените CREDENTIALS содержимым файла credentials.json .

  4. В коде замените 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.