Uwierzytelnianie jako aplikacja Google Chat

Z tego przewodnika dowiesz się, jak skonfigurować konto usługi i używać go do uzyskiwania dostępu do interfejsu Google Chat API w imieniu aplikacji do obsługi czatu. Najpierw dowiesz się, jak utworzyć konto usługi. Następnie pokazuje, jak napisać skrypt, który używa konta usługi do uwierzytelniania w interfejsie Chat API i publikowania wiadomości w przestrzeni w Chat.

Aby uzyskać dane o pokoju czatu lub wykonywać w nim działania po uwierzytelnieniu za pomocą konta usługi, aplikacje Google Chat muszą być członkami tego pokoju. Na przykład, aby wyświetlić listę członków pokoju lub utworzyć w nim wiadomość, aplikacja Chat musi być członkiem tego pokoju. Jedynym wyjątkiem jest sytuacja, w której aplikacja Google Chat tworzy pokój z uwierzytelnianiem aplikacji. W takim przypadku aplikacja tworzy pokój, a następnie automatycznie staje się jego użytkownikiem.

Metody interfejsu Google Chat API, które obsługują autoryzację aplikacji za pomocą zakresów autoryzacji, których nazwy zaczynają się od https://www.googleapis.com/auth/chat.app.*, wymagają jednorazowego zatwierdzenia przez administratora. Metody interfejsu Google Chat API, które obsługują autoryzację aplikacji za pomocą zakresu autoryzacji https://www.googleapis.com/auth/chat.bot, nie wymagają dodatkowego zatwierdzenia. https://www.googleapis.com/auth/chat.app.*Zakresy autoryzacji są dostępne w wersji przedpremierowej dla programistów.

Jeśli aplikacja do obsługi czatu musi mieć dostęp do danych użytkownika lub wykonywać działania w jego imieniu, uwierzytelnij się jako użytkownik. Jeśli jesteś administratorem domeny, możesz przyznać przekazywanie uprawnień w obrębie całej domeny, aby autoryzować konto usługi aplikacji Google Chat do uzyskiwania dostępu do danych użytkowników bez potrzeby pytania każdego użytkownika o zgodę. Więcej informacji znajdziesz w artykule Uwierzytelnianie i autoryzacja za pomocą przekazywania dostępu w całej domenie.

Więcej informacji o tym, kiedy aplikacje Google Chat wymagają uwierzytelniania i jakiego rodzaju uwierzytelniania należy użyć, znajdziesz w artykule Rodzaje wymaganego uwierzytelniania w przeglądzie uwierzytelniania i autoryzacji w interfejsie Chat API.

Wymagania wstępne

Java

  • JDK w wersji 1.7 lub nowszej
  • Narzędzie do zarządzania pakietami Maven
  • Zainicjowany projekt Maven. Aby zainicjować nowy projekt, uruchom to polecenie w interfejsie wiersza poleceń: 
    mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
  • Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu za pomocą usługi HTTP, wykonaj czynności opisane w tym krótkim wprowadzeniu.
  • Dodaj aplikację Google Chat do pokoju. Aby dodać aplikację Google Chat, zapoznaj się z artykułem Testowanie funkcji interaktywnych aplikacji Google Chat.

Python

Node.js

Google Apps Script

Krok 1. Utwórz konto usługi w konsoli Google Cloud

Utwórz konto usługi, którego aplikacja w Google Chat może używać do uzyskiwania dostępu do interfejsów API Google.

Tworzenie konta usługi

Aby utworzyć konto usługi, wykonaj te czynności:

Google Cloud Console

  1. W konsoli Google Cloud otwórz Menu  > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

  2. Kliknij Utwórz konto usługi.
  3. Wpisz szczegóły konta usługi, a następnie kliknij Utwórz i kontynuuj.
  4. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
  5. Kliknij Dalej.
  6. Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać na nim działania. Więcej informacji znajdziesz w artykule Zarządzanie przejmowaniem tożsamości konta usługi.
  7. Kliknij Gotowe. Zanotuj adres e-mail konta usługi.

interfejs wiersza poleceń gcloud

  1. Utwórz konto usługi: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.

Konto usługi pojawi się na stronie kont usługi. Następnie utwórz klucz prywatny dla konta usługi.

Tworzenie klucza prywatnego

Aby utworzyć i pobrać klucz prywatny dla konta usługi, wykonaj te czynności:

  1. W konsoli Google Cloud otwórz Menu  > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

  2. Wybierz konto usługi.
  3. Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
  4. Wybierz JSON, a następnie kliknij Utwórz.

    Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Zarządzanie kluczami konta usługi.

  5. Kliknij Zamknij.

Więcej informacji o kontach usługi znajdziesz w artykule Konta usługi w dokumentacji Google Cloud IAM.

Następnie utwórz zgodnego z Google Workspace Marketplace klienta OAuth dla tego konta usługi.

Uzyskiwanie zatwierdzenia przez administratora

Aby użyć zakresu autoryzacji https://www.googleapis.com/auth/chat.bot, nie musisz uzyskiwać zgody administratora. Przejdź do sekcji Krok 2. Zainstaluj bibliotekę klienta Google i inne zależności. W przykładzie w tym przewodniku użyto zakresu autoryzacji https://www.googleapis.com/auth/chat.bot, więc jeśli postępujesz zgodnie z przykładem, przejdź do kroku 2.

Aby używać zakresu autoryzacji, który zaczyna się od znaku https://www.googleapis.com/auth/chat.app.*, dostępnego w ramach wersji przedpremierowej dla deweloperów, aplikacja do obsługi czatu musi uzyskać jednorazowe zatwierdzenie administratora.

Aby uzyskać zgodę administratora, musisz przygotować konto usługi aplikacji do obsługi czatu, podając te informacje:

  • Klient OAuth zgodny z Google Workspace Marketplace.
  • Konfiguracja aplikacji w pakiecie SDK Google Workspace Marketplace.

Tworzenie klienta OAuth zgodnego z Google Workspace Marketplace

Aby utworzyć klienta OAuth zgodnego z Google Workspace Marketplace:

  1. W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

  2. Kliknij konto usługi utworzone na potrzeby aplikacji Chat.

  3. Kliknij Ustawienia zaawansowane.

  4. Kliknij Utwórz klienta OAuth zgodnego z Google Workspace Marketplace.

  5. Kliknij Dalej.

Pojawi się komunikat z potwierdzeniem, że utworzono klienta OAuth zgodnego z Google Workspace Marketplace.

Konfigurowanie aplikacji do obsługi czatu w pakiecie SDK Google Workspace Marketplace

Aby skonfigurować aplikację Google Chat w pakiecie SDK Google Workspace Marketplace, wykonaj te czynności:

  1. W konsoli Google Cloud włącz pakiet SDK Google Workspace Marketplace.

    Włączanie pakietu SDK Google Workspace Marketplace

  2. W konsoli Google Cloud otwórz Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Pakiet SDK Google Workspace Marketplace > Konfiguracja aplikacji.

    Otwórz stronę Konfiguracja aplikacji

  3. Wypełnij stronę Konfiguracja aplikacji. Sposób konfiguracji aplikacji do czatu zależy od docelowych odbiorców i innych czynników. Aby uzyskać pomoc dotyczącą wypełniania strony konfiguracji aplikacji, przeczytaj artykuł Konfigurowanie aplikacji w pakiecie SDK Google Workspace Marketplace. Na potrzeby tego przewodnika podaj te informacje:

    1. W sekcji Widoczność aplikacji wybierz Prywatna.
    2. W sekcji Ustawienia instalacji kliknij Instalacja indywidualna i administracyjna.
    3. W sekcji Integracje aplikacji wybierz Aplikacja do czatu.

    4. W sekcji Zakresy OAuth wpisz wszystkie zakresy uwierzytelniania, których używa Twoja aplikacja do Google Chat.

    5. W sekcji Informacje o deweloperze wpisz nazwę dewelopera, adres URL witryny dewelopera i adres e-mail dewelopera.

    6. Kliknij Zapisz kopię roboczą.

Uzyskiwanie zatwierdzenia przez administratora

Po skonfigurowaniu konta usługi do otrzymywania zgody administratora uzyskaj ją od administratora Google Workspace, który może ją przyznać, wykonując czynności opisane w artykule Konfigurowanie autoryzacji aplikacji do obsługi czatu.

Krok 2. Zainstaluj bibliotekę klienta Google i inne zależności

Zainstaluj bibliotekę klienta Google i inne zależności wymagane w projekcie.

Java

Aby dodać biblioteki klienta Google i inne wymagane zależności do projektu Maven, zmień plik pom.xml w katalogu projektu i dodaj te zależności:

<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

Jeśli nie masz jeszcze zainstalowanych bibliotek klienta Google dla Pythona, uruchom w interfejsie wiersza poleceń to polecenie:

pip3 install --upgrade google-api-python-client google-auth

Node.js

Aby dodać biblioteki klienta Google do projektu Node.js, przejdź do katalogu projektu i uruchom to polecenie w interfejsie wiersza poleceń:

npm install "@googleapis/chat"

Google Apps Script

Ten przykład korzysta z biblioteki OAuth2 do Apps Script do generowania tokena JWT na potrzeby uwierzytelniania konta usługi. Aby dodać bibliotekę do projektu Apps Script:

  1. Po lewej stronie kliknij Edytor .
  2. Po lewej stronie obok Biblioteki kliknij Dodaj bibliotekę .
  3. Wpisz identyfikator skryptu 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
  4. Kliknij Wyszukaj, a następnie Dodaj.

W tym przykładzie do wywoływania interfejsu Google Chat API używana jest zaawansowana usługa Chat. Aby włączyć usługę w projekcie Apps Script:

  1. Po lewej stronie kliknij Edytor .
  2. Po lewej stronie obok pozycji Usługi kliknij Dodaj usługę .
  3. Wybierz Google Chat API.
  4. W polu Wersja wybierz v1.
  5. Kliknij Dodaj.

Możesz użyć dowolnego języka obsługiwanego przez nasze biblioteki klienta.

Krok 3. Napisz skrypt, który używa konta usługi do uwierzytelniania w interfejsie Chat API

Poniższy kod uwierzytelnia się w interfejsie Chat API za pomocą konta usługi, a następnie publikuje wiadomość w pokoju Google Chat:

Java

  1. W katalogu projektu otwórz plik src/main/java/com/google/chat/app/authsample/App.java.

  2. Zastąp zawartość pliku App.java tym kodem:

    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();
    }
}

  3. W kodzie zastąp SPACE_NAME nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju.

  4. Utwórz nowy podkatalog o nazwie resources w katalogu projektu.

  5. Upewnij się, że plik klucza prywatnego konta usługi ma nazwę credentials.json, i skopiuj go do podkatalogu resources.

  6. Aby skonfigurować Mavena tak, aby uwzględniał plik klucza prywatnego w pakiecie projektu, edytuj plik pom.xml w katalogu projektu i dodaj tę konfigurację do sekcji <build>:

    <build>
  <!-- ... existing configurations ... -->
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>

  7. Aby skonfigurować Maven tak, aby uwzględniał zależności w pakiecie projektu i wykonywał główną klasę aplikacji, edytuj plik pom.xml w katalogu projektu i dodaj tę konfigurację do sekcji <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

  1. W katalogu roboczym utwórz plik o nazwie chat_app_auth.py.

  2. Dodaj do pliku chat_app_auth.py ten kod:

    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)

  3. W kodzie zastąp SPACE_NAME nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego konta usługi ma nazwę credentials.json.

Node.js

  1. W katalogu projektu utwórz plik o nazwie chat_app_auth.js.

  2. Dodaj do pliku chat_app_auth.js ten kod:

    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. W kodzie zastąp SPACE_NAME nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego konta usługi ma nazwę credentials.json.

Google Apps Script

  1. W edytorze Apps Script zmień plik appsscript.json i dodaj zakres OAuth niezbędny do wysyłania żądań zewnętrznych w celu uzyskania tokena OAuth konta usługi:

      "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]

  2. Zapisz ten kod w pliku o nazwie ChatAppAuth.gs w projekcie 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 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());
}

  3. W kodzie zastąp CREDENTIALS zawartością pliku credentials.json.

  4. W kodzie zastąp SPACE_NAME nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju.

Krok 4. Uruchom pełny przykład

W katalogu roboczym skompiluj i uruchom przykład:

Java

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

Google Apps Script

Otwórz plik ChatAppAuth.gs w edytorze Apps Script i kliknij Uruchom.

Skrypt wysyła uwierzytelnione żądanie do interfejsu Chat API, który odpowiada, publikując wiadomość w pokoju Google Chat jako aplikacja Google Chat.

Rozwiązywanie problemów z przykładem

W tej sekcji opisujemy typowe problemy, które mogą wystąpić podczas próby uruchomienia tego przykładu.

Nie masz uprawnień do korzystania z tej aplikacji

Podczas uruchamiania skryptu może pojawić się błąd:

<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">

Ten komunikat o błędzie oznacza, że aplikacja Chat nie ma uprawnień do tworzenia wiadomości w określonym pokoju w Chat.

Aby rozwiązać ten problem, dodaj aplikację Google Chat do pokoju czatu określonego w skrypcie.

Aby wykonać to działanie, administrator musi przyznać aplikacji wymagany zakres autoryzacji OAuth.

Podczas uruchamiania skryptu może pojawić się błąd:

<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.">

Ten komunikat o błędzie oznacza, że administrator Google Workspace nie udzielił jeszcze jednorazowej zgody na używanie przez aplikację Google Chat zakresów autoryzacji, które zaczynają się od nazwy https://www.googleapis.com/auth/chat.app.*.

Aby rozwiązać ten problem:

  • Poproś administratora Google Workspace o przyznanie uprawnień aplikacji do Google Chat. Podczas obsługi tego błędu w logice aplikacji do Google Chat rozważ wysłanie wiadomości z informacją, że aplikacja do Google Chat wymaga zatwierdzenia przez administratora, aby wykonać żądane działanie, np.: To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
  • Jeśli metoda interfejsu Google Chat API obsługuje zakres autoryzacji https://www.googleapis.com/auth/chat.bot, który nie wymaga zatwierdzenia przez administratora, rozważ użycie tej metody. Aby sprawdzić, które zakresy autoryzacji obsługuje dana metoda, zapoznaj się z dokumentacją interfejsu Google Chat API.