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 Google Chat. Najpierw omówimy, jak utworzyć konto usługi. Następnie pokazuje, jak napisać skrypt, który będzie używać konta usługi do uwierzytelniania się w interfejsie Chat API, i publikować wiadomość w pokoju czatu.
Aplikacje do obsługi czatu mogą używać kont usługi do uwierzytelniania podczas asynchronicznego wywoływania interfejsu Google Chat API. Dzięki temu mogą:
- Wysyłaj wiadomości do Google Chat za pomocą
spaces.messages.create
, aby:- 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 zajął się nowo otwartym zgłoszeniem.
- Zaktualizuj wysłane wcześniej wiadomości za pomocą
spaces.messages.update
, aby:- Zmień stan trwającej operacji.
- Zaktualizuj przypisaną osobę lub termin.
- Wyświetl użytkowników w pokoju ze znacznikami
spaces.members.list
, aby:- Sprawdzanie, kto jest w pokoju.
- Potwierdź, że udział w pokoju obejmuje wszystkich członków zespołu.
Aby można było pobierać dane lub wykonywać działania w pokoju czatu po uwierzytelnieniu za pomocą konta usługi, aplikacje Google Chat muszą mieć członkostwo w pokoju. Aby na przykład wyświetlić listę osób w pokoju lub utworzyć w nim wiadomość, aplikacja Google Chat musi być osobą w tym pokoju.
Jeśli Twoja aplikacja do obsługi czatu musi mieć dostęp do danych użytkownika lub wykonywać działania w imieniu użytkownika, uwierzytelnij się jako użytkownik.
Jeśli jesteś administratorem domeny, możesz przyznać przekazywanie uprawnień w całej domenie, by autoryzować dostęp konta usługi aplikacji 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 za pomocą swojego konta usługi, aby przyjmować tożsamość konta użytkownika. Mimo że konto usługi jest używane do uwierzytelniania, przekazywanie dostępu w całej domenie pełni rolę użytkownika i dlatego jest uznawane za uwierzytelnianie użytkownika. W przypadku każdej funkcji, która wymaga uwierzytelniania użytkownika, możesz używać przekazywania dostępu w całej domenie.
Aby dowiedzieć się więcej o tym, kiedy aplikacje Google Chat wymagają uwierzytelniania i jakiego rodzaju uwierzytelniania należy używać, przeczytaj artykuł Typy wymaganego uwierzytelniania w omówieniu uwierzytelniania i autoryzacji interfejsu Chat API.
Wymagania wstępne
Aby uruchomić przykład w tym przewodniku, musisz spełnić te wymagania wstępne:
- Konto Google Workspace z dostępem do Google Chat .
- Projekt Google Cloud z włączonym interfejsem Chat API. Aby utworzyć projekt i włączyć interfejs API, zapoznaj się z sekcją Tworzenie projektu i włączanie interfejsu API.
- Opublikowana aplikacja Google Chat z członkostwem w pokoju czatu:
- Aby utworzyć i opublikować aplikację Google Chat, zapoznaj się z artykułem o tworzeniu aplikacji Google Chat za pomocą Cloud Functions.
- Aby dowiedzieć się, jak dodać aplikację Google Chat do pokoju czatu, przeczytaj artykuł Dodawanie aplikacji do pokoi lub rozmów w Google Chat.
Dodatkowo musisz spełnić te wymagania wstępne w zależności od języka:
Java
- JDK 1.7 lub nowsza
- 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 w wersji 3.6 lub nowszej
- Narzędzie do zarządzania pakietami pip
Node.js
Google Apps Script
- Projekt Apps Script połączony z projektem Google Cloud. Aby zainicjować projekt Apps Script, zobacz krótkie wprowadzenie do aplikacji Google Apps Script Chat.
Krok 1. Utwórz konto usługi w konsoli Google Cloud
Utwórz konto usługi, za pomocą którego aplikacja Google Chat 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
- W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.
- Kliknij Utwórz konto usługi.
- Wpisz szczegóły konta usługi, a potem kliknij Utwórz i kontynuuj.
- 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.
- Kliknij Dalej.
- Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać 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.
- Kliknij Gotowe. Zanotuj adres e-mail konta usługi.
interfejs wiersza poleceń gcloud
- Utwórz konto usługi:
gcloud iam service-accounts create
SERVICE_ACCOUNT_NAME
\ --display-name="SERVICE_ACCOUNT_NAME
" - 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 dla konta usługi, wykonaj te czynności:
- W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.
- Wybierz konto usługi.
- Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
- Wybierz JSON i 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 o zarządzaniu kluczami konta usługi. - 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 przez projekt.
Java
Aby dodać do projektu Maven biblioteki klienta Google i inne wymagane zależności, zmodyfikuj 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 języka Python, 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 projektu i uruchom to polecenie w interfejsie wiersza poleceń:
npm install "@googleapis/chat"
Google Apps Script
W tym przykładzie korzystamy z biblioteki OAuth2 dla Apps Script do wygenerowania tokena JWT na potrzeby uwierzytelniania za pomocą konta usługi. Aby dodać bibliotekę do projektu Apps Script:
- Po lewej stronie kliknij Edytor .
- Po lewej stronie obok opcji Biblioteki kliknij Dodaj bibliotekę .
- Wpisz identyfikator skryptu
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
. - Kliknij Wyszukaj, a następnie kliknij Dodaj.
W tym przykładzie użyto zaawansowanej usługi Google Chat do wywołania interfejsu Google Chat API. Aby włączyć usługę w projekcie Apps Script:
- Po lewej stronie kliknij Edytor .
- Po lewej stronie obok opcji Usługi kliknij Dodaj usługę .
- Wybierz Google Chat API.
- W sekcji Wersja wybierz v1.
- Kliknij Dodaj.
Możesz używać dowolnego języka obsługiwanego przez nasze biblioteki klienta.
Krok 3. Utwórz skrypt, który używa konta usługi do uwierzytelniania się w Chat API
Ten kod uwierzytelnia się w interfejsie Chat API za pomocą konta usługi, a następnie publikuje wiadomość w pokoju Google Chat:
Java
- Otwórz plik
src/main/java/com/google/chat/app/authsample/App.java
w katalogu projektu. 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(); } }
W kodzie zastąp
SPACE_NAME
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju.Utwórz nowy podkatalog o nazwie
resources
w katalogu projektu.Sprawdź, czy plik klucza prywatnego Twojego konta usługi nazywa się
credentials.json
i skopiuj go do podkataloguresources
.Aby skonfigurować narzędzie Maven do uwzględnienia pliku klucza prywatnego w pakiecie projektu, edytuj plik
pom.xml
w katalogu projektu i dodaj tę konfigurację w sekcji<build>
:<build> <!-- ... existing configurations ... --> <resources> <resource> <directory>resources</directory> </resource> </resources> </build>
Aby skonfigurować narzędzie Maven tak, aby uwzględniało zależności w pakiecie projektu i uruchamiało klasę główną aplikacji, edytuj plik
pom.xml
w katalogu projektu i dodaj tę konfigurację w 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
- W katalogu roboczym utwórz plik o nazwie
chat_app_auth.py
. 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)
W kodzie zastąp
SPACE_NAME
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju. Sprawdź, czy plik klucza prywatnego konta usługi nazywa sięcredentials.json
.
Node.js
- W katalogu projektu utwórz plik o nazwie
chat_app_auth.js
. 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);
W kodzie zastąp
SPACE_NAME
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju. Sprawdź, czy plik klucza prywatnego konta usługi nazywa sięcredentials.json
.
Google Apps Script
W edytorze Apps Script zmodyfikuj 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" ]
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()); }
W kodzie zastąp
CREDENTIALS
zawartością plikucredentials.json
.W kodzie zastąp
SPACE_NAME
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.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 interfejsu 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 opisujemy typowe problemy, które mogą wystąpić podczas próby uruchomienia tego przykładu.
Nie możesz korzystać 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 Google Chat nie ma uprawnień do tworzenia wiadomości Google Chat w określonym pokoju czatu.
Aby naprawić ten błąd, dodaj aplikację Google Chat do pokoju czatu określonego w skrypcie.
Powiązane artykuły
Aby dowiedzieć się, co jeszcze może robić interfejs Chat API, zapoznaj się z dokumentacją interfejsu Chat API.