Uwierzytelnianie jako aplikacji Google Chat

Z tego przewodnika dowiesz się, jak skonfigurować konto usługi, aby uzyskać dostęp do 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 korzysta z konta usługi do uwierzytelniania w interfejsie Chat API i publikowania 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. Dzięki temu:

  • Wysyłaj wiadomości do Google Chat z użyciem spaces.messages.create, aby:
    • Powiadom użytkowników o zakończeniu długo trwającego zadania w tle.
    • Ostrzegaj użytkowników o wyłączeniu serwera.
    • Poproś kogoś z działu obsługi klienta, aby przesłał nowo otwarte zgłoszenie.
  • Zaktualizuj wiadomości wysłane wcześniej 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 w pokoju uczestniczą wszyscy członkowie zespołu.

Aby uzyskiwać dane o pokoju czatu i wykonywać w nim działania, aplikacje do obsługi czatu muszą należeć do pokoju po uwierzytelnieniu za pomocą konta usługi. Aby na przykład wyświetlać listę osób w pokoju lub utworzyć wiadomość w pokoju, aplikacja Google Chat musi być użytkownikiem 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 przyznawać uprawnienia do przekazywania uprawnień w obrębie całej domeny, aby umożliwić kontu usługi aplikacji dostęp do danych użytkowników bez pytania każdego użytkownika o zgodę. Po skonfigurowaniu przekazywania dostępu w całej domenie możesz wykonywać wywołania interfejsu API przy użyciu swojego konta usługi, aby podszywać się pod konto użytkownika. Chociaż konto usługi jest używane do uwierzytelniania, przekazywanie dostępu w całej domenie podszywa się pod użytkownika i dlatego jest uznawane za uwierzytelnianie użytkowników. W przypadku funkcji, które wymagają uwierzytelniania użytkowników, możesz przekazywać dostęp w całej domenie.

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

Wymagania wstępne

Aby uruchomić przykład z tego przewodnika, musisz spełnić te wymagania wstępne:

Dodatkowo musisz spełniać te wymagania wstępne związane z danym językiem:

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
    

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ę do 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:

  1. W konsoli Google Cloud kliknij Menu > Administracja > Konta usługi.

    Otwórz 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 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 czynności. Więcej informacji znajdziesz w artykule Zarządzanie przejmowaniem tożsamości konta usługi.
  7. Kliknij Gotowe. Zapisz sobie adres e-mail konta usługi.

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 dla konta usługi, wykonaj te czynności:

  1. W konsoli Google Cloud kliknij Menu > Administracja > Konta usługi.

    Otwórz 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 komputer jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Ten plik jest jedyną kopią tego klucza. Informacje o bezpiecznym przechowywaniu klucza znajdziesz w sekcji Zarządzanie kluczami konta usługi.

  5. Kliknij Zamknij.

Więcej informacji o kontach usługi znajdziesz w sekcji na temat 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-httplib2 google-auth-oauthlib oauth2client

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

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 wybierz Add (Dodaj).

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

Krok 3. Napisz skrypt, który korzysta z konta usługi do uwierzytelniania w 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ć w metodzie spaces.list w Chat API lub z adresu URL pokoju.

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

  5. Sprawdź, czy plik klucza prywatnego konta usługi nosi nazwę credentials.json i skopiuj go do podkatalogu resources.

  6. Aby skonfigurować 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ć Maven tak, aby uwzględnił zależności w pakiecie projektu i uruchomił klasę główną 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 pliku chat_app_auth.py:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # 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ć w metodzie spaces.list w Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego konta usługi nosi nazwę credentials.json.

Node.js

  1. W katalogu projektu utwórz plik o nazwie chat_app_auth.js.
  2. Umieść ten kod w pliku 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ć w metodzie spaces.list w Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego konta usługi nosi nazwę credentials.json.

Google Apps Script

  1. W edytorze Apps Script edytuj plik appsscript.json i dodaj zakresy OAuth niezbędne do wywoływania interfejsu API:

      "oauthScopes": [
        "https://www.googleapis.com/auth/chat.messages.create",
        "https://www.googleapis.com/auth/script.external_request"
      ]
    
  2. Zapisz ten kod w pliku o nazwie ChatAppAuth.gs w projekcie Apps Script:

    const CREDENTIALS = CREDENTIALS;
    
    const SCOPE = 'https://www.googleapis.com/auth/chat.bot';
    
    /**
     * Authenticates with Chat API via app credentials, then posts a message.
     */
    function createMessage() {
      const service = getService_();
      if (!service.hasAccess()) {
        console.error(service.getLastError());
        return;
      }
    
      // 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';
    
      // Call the Chat API to create a message.
      const result = UrlFetchApp.fetch(`https://chat.googleapis.com/v1/${parent}/messages`,
        {
          method: 'post',
          contentType: 'application/json',
          // Authenticate with the service account token.
          headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
          // The message to create.
          payload: JSON.stringify({ 'text': 'Hello, world!' })
        });
    
      // Log details about the created message.
      console.log(result.getContentText());
    }
    
    /**
     * 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ć w metodzie spaces.list w 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 czatu jako aplikację do obsługi czatu.

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

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

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

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