Uwierzytelnianie jako aplikacja Google Chat

Z tego przewodnika dowiesz się, jak skonfigurować konto usługi i używać go do uzyskiwania dostępu do Interfejs Google Chat API w imieniu aplikacji Google Chat. Po pierwsze, Przeprowadzi Cię on przez proces tworzenia konta usługi. Później pokazuje, Napisanie skryptu, który będzie używać konta usługi do uwierzytelniania w Google Chat API i opublikować wiadomość w pokoju czatu.

Aplikacje do obsługi czatu mogą używać kont usługi do uwierzytelniania podczas wywoływania asynchronicznego Google Chat API, dzięki czemu będą mogli:

  • Wysyłaj wiadomości do Google Chat przez: spaces.messages.create do:
      .
    • Powiadom użytkowników o zakończeniu długo trwającego zadania w tle.
    • Ostrzegaj użytkowników, że serwer przeszedł do trybu offline.
    • Poproś pracownika obsługi klienta, aby odpowiadał za niedawno otwarte zgłoszenie klienta.
  • Zaktualizuj wcześniej wysłane wiadomości za pomocą spaces.messages.update do:
      .
    • Zmień stan trwającej operacji.
    • Zaktualizuj przypisaną osobę lub termin.
  • Pokaż użytkowników w pokoju za pomocą: spaces.members.list na:
      .
    • Sprawdzanie, kto jest w pokoju.
    • Potwierdź, że udział w pokoju obejmuje wszystkich członków zespołu.

Po uwierzytelnieniu za pomocą konta usługi w celu pobierania danych lub wykonywania działań w pokoju czatu, aplikacje do obsługi czatu muszą mieć przypisaną osobę z pokoju. Aby na przykład: wyświetlać listę osób w pokoju lub utworzyć wiadomość w pokoju, aplikacja Google Chat musi że sama będzie członkiem grupy.

Jeśli aplikacja Google Chat musi mieć dostęp do danych użytkownika lub wykonywać działania na uwierzytelnij się jako użytkownik.

Jeśli jesteś administratorem domeny, możesz przyznać przekazywanie uprawnień w całej domenie do autoryzowania konta usługi aplikacji na potrzeby dostępu do danych bez wymaganie od każdego użytkownika wyrażenia zgody. Gdy skonfigurujesz przekazywanie dostępu w całej domenie, możesz wywoływać wywołania interfejsu API za pomocą konta usługi w celu podszywania się pod konto użytkownika. Mimo że konto usługi jest używane do uwierzytelnianie, przekazywanie dostępu w całej domenie polega na podszywaniu się pod użytkownika i dlatego jest uznawane za uwierzytelnianie użytkownika. Wszelkie funkcje, które wymagają użytkownika uwierzytelniania, możesz używać przekazywania dostępu w całej domenie.

Aby dowiedzieć się więcej o tym, kiedy aplikacje Google Chat wymagają uwierzytelnienia i jakiego uwierzytelniania użyć, zobacz Typy wymaganego uwierzytelniania w omówieniu uwierzytelniania i autoryzacji interfejsu Chat API.

Wymagania wstępne

Java

  • JDK 1.7 lub nowsza
  • Narzędzie do zarządzania pakietami Maven
  • Zainicjowany projekt Maven. Aby zainicjować nowy projekt, uruchom to polecenie w interfejs 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, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.
  • Dodaj aplikację Google Chat do pokoju. Aby dodać Aplikacja Google Chat, patrz sekcja Testowanie funkcji interaktywnych w aplikacjach Google Chat

Python

Node.js

  • Node.js w wersji 14 lub nowszej
  • npm narzędzie do zarządzania pakietami
  • Zainicjowany projekt Node.js. Aby zainicjować nowy projekt, utwórz i przełącz się na nowy folder, a następnie uruchom to polecenie w interfejsie wiersza poleceń:
    npm init
    
  • Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.
  • Dodaj aplikację Google Chat do pokoju. Aby dodać Aplikacja Google Chat, patrz sekcja Testowanie funkcji interaktywnych w aplikacjach Google Chat

Google Apps Script

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

Tworzenie konta usługi, do którego będzie mogła być używana aplikacja Google Chat uzyskać dostęp 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 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 przyjęciem 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 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 prywatną 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 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 na komputerze jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalog roboczy. Jest to jedyna kopia tego klucza. Informacje na temat sposobu przechowywania danych klucz bezpieczeństwa, zobacz Zarządzanie kluczami konta usługi

  5. Kliknij Zamknij.

Więcej informacji o kontach usługi znajdziesz w artykule konta usługi znajdziesz 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 przez projekt.

Java

Aby dodać biblioteki klienta Google i inne wymagane zależności do W projekcie Maven zmodyfikuj plik pom.xml w katalogu projektu i dodaj atrybut 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 języka Python, uruchom polecenie następujące 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, przełącz się na katalogu projektu i uruchom to polecenie w interfejsie wiersza poleceń:

npm install "@googleapis/chat"

Google Apps Script

W tym przykładzie użyto parametru Protokół OAuth2 w bibliotece Apps Script aby wygenerować token JWT do 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 Wyszukaj, a następnie kliknij Dodaj.

W tym przykładzie użyto parametru Zaawansowana usługa czatu aby wywołać interfejs Google Chat API. Aby włączyć usługę dla swojego urządzenia Projekt 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 biblioteki klienta.

Krok 3. Utwórz skrypt, który używa konta usługi do uwierzytelniania się w Chat API

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

Java

  1. Otwórz plik w katalogu projektu. src/main/java/com/google/chat/app/authsample/App.java
  2. Zastąp zawartość pola 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 spacją – znajdziesz ją w 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 klucza prywatnego konta usługi ma nazwę credentials.json i skopiuj go do podkatalogu resources.

  6. Aby skonfigurować narzędzie Maven do uwzględnienia pliku klucza prywatnego w pakiecie projektu, edytuj plik pom.xml w katalogu projektu i dodaj do niego ten kod do sekcji <build>:

    <build>
      <!-- ... existing configurations ... -->
      <resources>
        <resource>
          <directory>resources</directory>
        </resource>
      </resources>
    </build>
    
  7. Aby skonfigurować Maven, aby uwzględnić zależności w pakiecie projektu w celu wykonania głównej klasy aplikacji, edytuj plik pom.xml w katalogu projektu i dodaj tę konfigurację do Sekcja <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ść w 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.
    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 spacją – znajdziesz ją w spaces.list w interfejsie Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego Twojego konta usługi nazywa się credentials.json.

Node.js

  1. W katalogu projektu utwórz plik o nazwie chat_app_auth.js.
  2. Umieść w 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 spacją – znajdziesz ją w spaces.list w interfejsie Chat API lub z adresu URL pokoju. Upewnij się, że plik klucza prywatnego Twojego konta usługi nazywa się credentials.json.

Google Apps Script

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

      "oauthScopes": [
        "https://www.googleapis.com/auth/script.external_request"
      ]
    
  2. Zapisz ten kod w pliku o nazwie ChatAppAuth.gs w projektu 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 elementem zawartość pliku credentials.json.

  4. W kodzie zastąp SPACE_NAME spacją – znajdziesz ją w 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 wysyła uwierzytelnione żądanie do Chat API, który odpowiada, publikując wiadomość w pokoju czatu jako aplikację Google Chat.

Rozwiązywanie problemów z przykładem

W tej sekcji opisaliśmy typowe problemy, które mogą wystąpić podczas próby aby uruchomić ten fragment.

Nie możesz używać 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 Google Chat nie ma uprawnienia do tworzenia wiadomości w Google Chat w określonym zakresie Pokój czatu.

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

Zapoznaj się z interfejsem Chat API i dowiedz się, co jeszcze może robić interfejs Chat API dokumentacji referencyjnej.