Uwierzytelnianie jako aplikacja Google Chat

Z tego przewodnika dowiesz się, jak skonfigurować konto usługi i za jego pomocą uzyskać dostęp do Google Chat API w imieniu aplikacji do obsługi czatu. Najpierw omówimy sposób tworzenia konta usługi. Następnie pokazuje, jak napisać skrypt, który używa konta usługi do uwierzytelniania w interfejsie Chat API i opublikowania wiadomości w pokoju czatu.

Aplikacje do obsługi czatu mogą używać kont usługi do uwierzytelniania się podczas asynchronicznego wywoływania interfejsu Google Chat API. Pozwala to na:

  • Wysyłaj wiadomości do Google Chat, używając spaces.messages.create, aby:
    • Powiadamiaj użytkowników o zakończeniu długo działającego zadania w tle.
    • Poinformuj użytkowników o przełączeniu serwera w tryb offline.
    • Poproś pracownika obsługi klienta, aby na początku obsługiwał nowe zgłoszenie.
  • Zaktualizuj wcześniej wysłane wiadomości za pomocą spaces.messages.update, aby:
    • Zmień stan trwającej operacji.
    • Zaktualizuj osobę przypisaną do zadania lub termin.
  • Wyświetl użytkowników w pokoju za pomocą spaces.members.list, aby:
    • Sprawdzanie, kto jest w pokoju.
    • Sprawdź, czy wszyscy członkowie zespołu należą do pokoju.

Aby uzyskiwać dane o pokoju czatu i wykonywać w nim działania, po uwierzytelnieniu go za pomocą konta usługi aplikacje Google Chat muszą mieć dostęp do pokoju. Aby na przykład wyświetlić listę osób w pokoju lub utworzyć wiadomość w pokoju, aplikacja Google Chat musi być członkiem pokoju.

Jeśli aplikacja do obsługi czatu wymaga dostępu do danych użytkownika lub wykonywania działań w imieniu użytkownika, uwierzytelnij się jako użytkownik.

Jeśli jesteś administratorem domeny, możesz przyznać przekazywanie uprawnień w całej domenie w celu autoryzowania konta usługi aplikacji na dostęp do danych użytkowników bez konieczności wyrażenia zgody przez każdego użytkownika. Po skonfigurowaniu przekazywania dostępu w całej domenie możesz wykonywać wywołania interfejsu API przy użyciu konta usługi, aby podszywać się pod konto użytkownika. Chociaż konto usługi służy do uwierzytelniania, przekazywanie dostępu w całej domenie podszywa się pod użytkownika i dlatego jest uznawane za uwierzytelnianie użytkownika. W przypadku wszystkich funkcji, które wymagają uwierzytelniania użytkowników, możesz korzystać z przekazywania dostępu w całej domenie.

Aby dowiedzieć się więcej o tym, kiedy aplikacje do obsługi czatu wymagają uwierzytelniania, i jakiego rodzaju uwierzytelnianie należy używać, przeczytaj sekcję Typy wymaganych uwierzytelniania w artykule omawiającym uwierzytelnianie i autoryzację przy użyciu interfejsu Chat API.

Wymagania wstępne

Aby uruchomić przykład opisany w tym przewodniku, musisz spełnić te wymagania wstępne:

Musisz też spełniać te wymagania wstępne dotyczące poszczególnych języków:

Java

  • JDK w wersji 1.7 lub nowszej
  • Narzędzie do zarządzania pakietami Maven
  • Zainicjowany projekt Maven. Aby zainicjować nowy projekt, uruchom w interfejsie wiersza poleceń to polecenie:

    mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
    

Python

  • Python 3.6 lub nowszy
  • Narzędzie do zarządzania pakietami pip

Node.js

  • Node.js
  • Narzędzie do zarządzania pakietami npm
  • Zainicjowany projekt Node.js. Aby zainicjować nowy projekt, utwórz nowy folder i przełącz się na niego, a następnie uruchom to polecenie w interfejsie wiersza poleceń:

    npm init
    

Google Apps Script

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

Utwórz konto usługi, za pomocą którego aplikacja do obsługi czatu będzie mogła uzyskiwać dostęp do interfejsów API Google.

Tworzenie konta usługi

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

Konsola Google Cloud

  1. W konsoli Google Cloud kliknij 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 potem kliknij Utwórz i kontynuuj.
  4. Opcjonalnie: przypisz role do swojego konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie 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. Zapisz 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 swojego konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie dostępu do zasobów.

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

Tworzenie klucza prywatnego

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

  1. W konsoli Google Cloud kliknij 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 i kliknij Utwórz.

    Nowa para kluczy publiczny/prywatny zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Ten plik jest jedyną kopią tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w sekcji Zarządzanie kluczami konta usługi.

  5. Kliknij Zamknij.

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

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ć do projektu Maven biblioteki klienta Google i inne wymagane zależności, edytuj 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 to polecenie w interfejsie wiersza poleceń:

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

Node.js

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

npm install "@googleapis/chat"

Google Apps Script

W tym przykładzie użyto biblioteki OAuth2 dla Apps Script do wygenerowania 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 opcji Biblioteki kliknij Dodaj bibliotekę .
  3. Wpisz identyfikator skryptu 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
  4. Kliknij Look up (Wyszukaj), a następnie kliknij Add (Dodaj).

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

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

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

Krok 3. Napisz skrypt, który będzie używać konta usługi do uwierzytelniania w Google Chat API

Ten kod uwierzytelnia się w Chat API za pomocą konta usługi, a następnie publikuje wiadomość w pokoju czatu:

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 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. 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. Sprawdź, czy plik z kluczem prywatnym konta usługi nazywa się credentials.json i skopiuj go do podkatalogu resources.

  6. Aby skonfigurować narzędzie Maven do uwzględniania pliku 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ć narzędzie Maven do uwzględniania zależności w pakiecie projektu i wykonywania klasy głównej 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. Umieść ten kod w elemencie 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. 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. Pamiętaj, aby plik klucza prywatnego konta usługi nazywał się credentials.json.

Node.js

  1. W katalogu projektu utwórz plik o nazwie chat_app_auth.js.
  2. Umieść ten kod w elemencie 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. 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. Pamiętaj, aby plik klucza prywatnego konta usługi nazywał się credentials.json.

Google Apps Script

  1. W edytorze Apps Script edytuj 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 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. 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.

Twój skrypt wykonuje uwierzytelnione żądanie do interfejsu Chat API, który odpowiada, publikując wiadomość w pokoju czatu jako aplikację Google Chat.

Rozwiąż problemy 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

Po uruchomieniu skryptu może pojawić się błąd o następującej treści:

<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 Google Chat nie ma uprawnień do tworzenia wiadomości w Google Chat w określonym pokoju czatu.

Aby naprawić błąd, dodaj aplikację Google Chat do pokoju czatu określonego w skrypcie.

Aby dowiedzieć się, co jeszcze potrafi Chat API, zapoznaj się z dokumentacją interfejsu Chat API.