Każda tworzona przez Ciebie aplikacja do Google Chat wymaga własnego projektu w chmurze Google Cloud z włączonym i skonfigurowanym interfejsem Chat API.
Aby wykonywać wywołania interfejsu API tylko do odczytu z uwierzytelnianiem użytkownika, takie jak pobieranie pokoi i wyświetlanie listy wiadomości, wystarczy włączyć interfejs API i utworzyć klienta OAuth.
Aby wykonywać wywołania interfejsu API do tworzenia, aktualizowania i usuwania, lub aby wdrożyć i przetestować interaktywną aplikację do Google Chat (utworzoną jako dodatek do Google Workspace, który rozszerza Google Chat), musisz też skonfigurować interfejs Chat API. W ustawieniach konfiguracji interfejsu Chat API określasz wszystkie szczegóły dotyczące aplikacji Google Chat, w tym jej wyświetlaną nazwę, awatar, punkty końcowe wdrożenia i funkcje interaktywne.
Wymagania wstępne
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz interfejs Google Chat API.
Wybieranie wyświetlanej nazwy, awatara i opisu aplikacji do Google Chat
Gdy włączysz interfejs Chat API, skonfigurujesz szczegóły aplikacji Google Chat, które będą widoczne dla użytkowników w Google Chat, w tym wyświetlaną nazwę, awatar i opis. Te informacje są widoczne tylko w Google Chat. Aby opublikować aplikację do Google Chat w Marketplace, musisz też podać informacje, które będą widoczne na stronie aplikacji w Marketplace.
Zanim skonfigurujesz aplikację do Google Chat, przygotuj te informacje:
| Pole | Opis | Format |
|---|---|---|
| Nazwa aplikacji | Wyświetlana nazwa aplikacji Google Chat. | Do 25 znaków alfanumerycznych |
| URL awatara | Obraz, który wyświetla się jako awatar aplikacji do Google Chat. | Adres URL HTTPS wskazujący kwadratowy obraz graficzny (PNG lub JPEG). Zalecany rozmiar to co najmniej 256 × 256 pikseli. |
| Opis | Krótki opis aplikacji do Google Chat, który wyświetla się, gdy użytkownicy wyszukują aplikacje w Google Chat. | Maksymalnie 40 znaków alfanumerycznych |
| Długi opis | Opcjonalnie: Opis możliwości aplikacji Google Chat, który wyświetla się, gdy użytkownicy rozpoczynają rozmowę z aplikacją Google Chat lub otwierają stronę główną sesji agenta. Obecnie jest to obsługiwane tylko podczas aktualizowania konfiguracji aplikacji za pomocą konsoli Google Cloud i nie jest obsługiwane przez interfejs API dodatków do Google Workspace. | Do 250 znaków |
Nazwa, awatar i opis aplikacji Google Chat są wyświetlane użytkownikom w interfejsie Google Chat. W przypadku niektórych żądań zapisu interfejsu Chat API Google Chat używa tych informacji do przypisywania działań, które aplikacja Google Chat wykonuje w Google Chat.
Jeśli na przykład wywołasz metodę spaces.create(), Google Chat uwzględni nazwę aplikacji do Google Chat w opisie osoby, która utworzyła pokój, jak pokazano na tym obrazie:
spaces.create() jest używana do utworzenia pokoju w imieniu użytkownika.
Aby korzystać z aplikacji do Google Chat, użytkownicy mogą też wyświetlać te informacje lub używać ich w następujący sposób:
- Użyj @wzmianki, aby dodać aplikację do Google Chat do pokoju lub wysłać do niej wiadomość.
- Znajdź aplikację do Google Chat i rozpocznij z nią czat. W menu Aplikacje czaty wyświetlają nazwę i awatar aplikacji do Google Chat.
- Na pasku tworzenia wiadomości użytkownicy mogą przeglądać aplikacje do Google Chat oraz wyświetlać ich nazwy, awatary i opisy.
Konfigurowanie aplikacji do Google Chat w konsoli Google Cloud
Gdy masz już szczegóły aplikacji Google Chat, otwórz projekt w chmurze i skonfiguruj interfejs Chat API:
W konsoli Google Cloud otwórz stronę interfejsu Chat API i kliknij Konfiguracja:
W sekcji Informacje o aplikacji wypełnij pola Nazwa aplikacji, URL awatara i Opis.
Opcjonalnie: wypełnij pole Długi opis.
Opcjonalnie: w menu Składnia znaczników wybierz domyślną składnię znaczników (Markdown lub Google Chat) dla wiadomości aplikacji do Google Chat. Więcej informacji o formatowaniu tekstu i o tym, jak Google Chat określa składnię znaczników w żądaniach do interfejsu API, znajdziesz w artykule Formatowanie wiadomości.
W sekcji Funkcje interaktywne określ, czy aplikacja do Google Chat ma reagować na interakcje użytkowników:
Aby utworzyć interaktywną aplikację do Google Chat, włącz opcję Włącz funkcje interaktywne i wykonaj te czynności:
- W sekcji Funkcje:
- Opcjonalnie: wybierz Obsługuj stronę główną aplikacji, aby wyświetlać kartę strony głównej na karcie Strona główna w czatach indywidualnych z aplikacją Google Chat.
- Wybierz Dołączanie do pokoi i rozmów grupowych, aby aplikacja Google Chat była dostępna do zainstalowania i używania. Domyślnie użytkownicy mogą instalować aplikację do Google Chat i wysyłać wiadomości w dedykowanym pokoju między użytkownikiem a aplikacją do Google Chat. Użytkownicy mogą też dodawać aplikację do Google Chat i korzystać z niej w pokojach z wieloma osobami.
W sekcji Ustawienia połączenia wybierz architekturę, której chcesz używać do odbierania obiektów zdarzeń z Google Chat:
- Aby użyć usługi HTTP, wybierz Adres URL punktu końcowego HTTP i podaj adres URL.
- Aby użyć projektu Google Apps Script, wybierz Apps Script i podaj identyfikator wdrożenia projektu.
- Aby użyć agenta Dialogflow, wybierz Dialogflow, a następnie Dialogflow CX lub Dialogflow ES i podaj nazwę zasobu agenta.
- Aby użyć Pub/Sub, wybierz Cloud Pub/Sub i wpisz nazwę tematu.
Opcjonalnie: aby kierować obiekty zdarzeń do określonych punktów końcowych lub funkcji, kliknij Ustawienia połączenia > Aktywatory i podaj lub zaktualizuj punkty końcowe lub funkcje wywołania zwrotnego dla tych aktywatorów Google Chat:
- Strona główna aplikacji (jeśli włączona jest opcja Obsługuj stronę główną aplikacji): użytkownik otwiera kartę Strona główna w czacie indywidualnym z aplikacją Google Chat.
- Dodano do pokoju: użytkownik dodaje aplikację Google Chat do rozmowy grupowej lub pokoju albo instaluje aplikację Google Chat do wiadomości 1:1.
- Wiadomość: użytkownik wysyła wiadomość do aplikacji Google Chat. Może to być na przykład wiadomość na czacie lub @wzmianka o aplikacji Google Chat w pokoju z wieloma osobami.
- Usunięcie z pokoju: użytkownik odinstalowuje lub usuwa aplikację Google Chat z pokoju.
- Polecenie aplikacji: użytkownik wywołuje szybkie polecenie, polecenie po ukośniku lub działanie na wiadomości z aplikacji do obsługi czatu.
Opcjonalnie: dodaj inne funkcje interaktywne, takie jak sesje, prompty początkowe, polecenia (szybkie polecenia, polecenia po ukośniku i działania związane z wiadomościami) lub podglądy linków.
W sekcji Widoczność wybierz Udostępnij tę aplikację do obsługi czatu konkretnym osobom i grupom i wpisz adresy e-mail osób lub grup dyskusyjnych Google w organizacji Google Workspace:
- Aby samodzielnie zainstalować i przetestować aplikację, wpisz swój adres e-mail.
- Aby udostępnić wewnętrzną aplikację do Google Chat zespołowi lub całej organizacji bez publikowania jej w Marketplace, wpisz co najmniej jedną grupę dyskusyjną Google. Grupy nie mają limitu liczby członków. Jeśli Twoja aplikacja żąda zakresów
chat.app.*, musisz ją opublikować, aby administrator mógł ją zatwierdzić. - Jeśli administrator ograniczy instalacje z Marketplace do aplikacji z listy dozwolonych, konsola Google Cloud ograniczy to pole do 5 adresów e-mail poszczególnych użytkowników na potrzeby programowania. Widoczność grupy jest stosowana dopiero po dodaniu aplikacji do listy dozwolonych przez administratora.
- W sekcji Funkcje:
Opcjonalnie: w sekcji Logi zaznacz pole wyboru Logowanie błędów w Logging, aby używać Google Cloud Logging. Więcej informacji znajdziesz w artykule Dzienniki błędów zapytań w aplikacjach Google Chat.
Kliknij Zapisz.
Po zapisaniu konfiguracji każda osoba określona w ustawieniu Widoczność interfejsu Chat API może zainstalować, przetestować lub używać aplikacji Google Chat. Aby rozpocząć testowanie i debugowanie aplikacji Google Chat, przeczytaj artykuł Testowanie funkcji interaktywnych w aplikacjach do Google Chat.
Konfigurowanie aplikacji do Google Chat za pomocą Google Cloud CLI
Zamiast konsoli Google Cloud możesz wyświetlać i aktualizować konfigurację aplikacji Google Chat z poziomu wiersza poleceń za pomocą interfejsu wiersza poleceń Google Cloud (gcloud CLI). Możesz na przykład skonfigurować aplikację do Google Chat za pomocą skryptu lub zapisać jej konfigurację w pliku przechowywanym razem z kodem.
Grupa poleceń gcloud beta workspace-add-ons chat-app-config zawiera te polecenia:
describe: wyświetla konfigurację.update: konfiguruje aplikację do Google Chat po raz pierwszy lub zmienia jej konfigurację.
Polecenia używają zasobu chatAppConfig w interfejsie Google Workspace Add-ons API.
Zanim zaczniesz
- Zainstaluj gcloud CLI. Jeśli masz już zainstalowany gcloud CLI, upewnij się, że masz najnowszą wersję, uruchamiając polecenie
gcloud components update. Zaloguj się w gcloud CLI za pomocą konta użytkownika. Polecenia nie obsługują kont usługi.
gcloud auth loginUstaw projekt w chmurze aplikacji do Google Chat jako domyślny projekt gcloud CLI. Użyj identyfikatora projektu, ponieważ polecenia nie akceptują numeru projektu.
gcloud config set project PROJECT_IDMożesz też dodać flagę
--projectdo każdego polecenia.Włącz interfejs Google Workspace Add-ons API w projekcie w chmurze:
gcloud services enable gsuiteaddons.googleapis.comUpewnij się, że masz te role uprawnień w projekcie Cloud:
- Deweloper dodatków do Google Workspace (
roles/gsuiteaddons.developer), aby wyświetlać i aktualizować konfigurację, lub Odczytujący dodatki do Google Workspace (roles/gsuiteaddons.reader), aby tylko ją wyświetlać. Te role obejmują uprawnienia wymienione w sekcji Wymagania wstępne i uwierzytelnianie. - Konsument wykorzystania usług (
roles/serviceusage.serviceUsageConsumer). gcloud CLI używa projektu w chmurze jako projektu z limitami na potrzeby żądań, co wymaga uprawnieniaserviceusage.services.use.
Role Właściciel i Edytujący obejmują wszystkie te uprawnienia. Role Właściciel aplikacji do Google Chat i Przeglądający aplikacje do Google Chat, które dają dostęp do strony konfiguracji w konsoli Google Cloud, nie są wystarczające.
- Deweloper dodatków do Google Workspace (
Wyświetlanie konfiguracji
Aby wyświetlić konfigurację aplikacji Google Chat, uruchom polecenie describe:
gcloud beta workspace-add-ons chat-app-config describeDane wyjściowe są podobne do tych:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
Jeśli projekt w chmurze nie ma jeszcze aplikacji do Google Chat, polecenie zostanie wykonane i wyświetli tylko pole name konfiguracji:
name: projects/123456789012/chatAppConfig
Aby zmienić dane wyjściowe, dodaj jedną z tych flag:
--format=json: wyświetla konfigurację w formacie JSON.--view=basic: pomija ustawienia funkcji interaktywnych (interactiveFeatureConfig).--format="value(displayName)": wyświetla tylko wyświetlaną nazwę lub pusty wiersz, jeśli projekt w chmurze nie ma jeszcze aplikacji Google Chat. Skonfigurowana aplikacja do Google Chat zawsze ma wyświetlaną nazwę, więc możesz użyć tej flagi w skrypcie, aby sprawdzić, czy aplikacja do Google Chat istnieje.
Aktualizowanie konfiguracji
Aby po raz pierwszy skonfigurować aplikację do Google Chat lub zmienić jej konfigurację, uruchom polecenie update. Określ ustawienia za pomocą flag lub w pliku konfiguracji. Nie możesz połączyć tych 2 poleceń w jedno.
Przy pierwszym uruchomieniu polecenia w projekcie w chmurze musisz podać co najmniej wyświetlaną nazwę i opis. Jeśli nie ustawisz stanu na wyłączony, aplikacja do Google Chat będzie aktywna, gdy tylko polecenie zostanie wykonane. Osoby, które dodasz jako testerów, będą mogły ją znaleźć i z niej korzystać.
Używanie flag
W tym przykładzie skonfigurowano aplikację do Google Chat, która odbiera zdarzenia w punkcie końcowym HTTP:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledZastąp te elementy:
HTTP_ENDPOINT_URL: adres URL HTTPS, który otrzymuje obiekty zdarzeń z Google Chat.USER_EMAIL: adres e-mail osoby lub grupy w organizacji Google Workspace, która może zainstalować i przetestować aplikację Google Chat, na przykład Twój adres e-mail.
Polecenie wyświetli zaktualizowaną konfigurację.
W tabeli poniżej znajdziesz flagi ustawień na stronie Konfiguracja interfejsu Chat API w konsoli Google Cloud. Szczegółowe informacje o poszczególnych flagach znajdziesz w dokumentacji polecenia update.
| Ustawienie w konsoli Google Cloud | Flagi |
|---|---|
| Nazwa aplikacji | --display-name |
| URL awatara | --avatar-uri, podając adres URL HTTPS obrazu, który spełnia wymagania dotyczące awatara, lub --clear-avatar-uri, aby użyć domyślnego awatara. |
| Opis | --description |
| Stan aplikacji | --state=active lub --state=disabled |
| Składnia znaczników | --markup-syntax=markdown lub --markup-syntax=chat |
| Dołączanie do pokoi i rozmów grupowych | --supports-multiuser-spaces lub --no-supports-multiuser-spaces |
| Ustawienia połączenia | Jedna z tych wartości:
|
| Widoczność | --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals i --clear-allowlisted-testing-principals |
| Loguj błędy w usłudze Logging | --error-logging-enabled lub --no-error-logging-enabled |
Polecenia, podglądy linków i osobne punkty końcowe dla każdego aktywatora nie mają flag. Aby je skonfigurować, użyj pliku konfiguracji.
Aby na przykład wyłączyć aplikację Google Chat bez zmiany innych ustawień, uruchom to polecenie. Aby włączyć ją ponownie, użyj --state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledUżywanie pliku konfiguracji
Aby zachować konfigurację w pliku lub skonfigurować ustawienia, które nie mają flag, przekaż plik YAML lub JSON do polecenia update. Plik używa pól zasobu chatAppConfig, które są tymi samymi polami, które wyświetla polecenie describe.
Utwórz plik zawierający ustawienia, które chcesz zaktualizować. Na przykład utwórz plik o nazwie
chat_app_config.yamlz tą treścią:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILZastąp
USER_EMAILadresem e-mail osoby lub grupy w organizacji Google Workspace, która może zainstalować i przetestować aplikację Google Chat.Uruchom polecenie
updatez flagą--config-file:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
Aby rozpocząć od bieżącej konfiguracji aplikacji Google Chat, zapisz dane wyjściowe polecenia describe w pliku:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlNastępnie zmodyfikuj plik, usuń pola, których nie chcesz zmieniać, i przekaż plik do polecenia update. Jeśli plik zawiera ustawienie, którego polecenie nie może zaktualizować, polecenie nie powiedzie się. Więcej informacji znajdziesz w sekcji Ograniczenia.
Polecenie update ignoruje pole name w pliku. Zawsze aktualizuje projekt w chmurze ustawiony w gcloud CLI, dzięki czemu możesz używać tego samego pliku do konfigurowania aplikacji Google Chat w innym projekcie w chmurze.
Jak polecenie stosuje zmiany
- Zmienią się tylko określone przez Ciebie ustawienia. Jeśli użyjesz flag, polecenie zmieni ustawienia przekazanych flag. W przypadku pliku konfiguracji zmienia pola, które się w nim znajdują, więc plik nie musi zawierać całej konfiguracji. Wyjątkiem są ustawienia połączenia: ustawiony typ połączenia zastępuje bieżący, a ustawiona wersja Dialogflow zastępuje całą konfigurację Dialogflow.
- Listy są zastępowane w całości. Jeśli plik zawiera pole
appCommands,urlPatternsluballowlistedTestingPrincipals, lista w pliku zastępuje bieżącą listę. Aby dodać lub usunąć poszczególnych testerów, użyj flag--add-allowlisted-testing-principalsi--remove-allowlisted-testing-principals. - Pusta wartość powoduje wyczyszczenie ustawienia. Na przykład plik, który zawiera
urlPatterns: []w sekcjiinteractiveFeatureConfig, usuwa wszystkie wzorce adresów URL podglądu linku. - Polecenie, które się nie powiedzie, niczego nie zmienia. Jeśli wartość jest nieprawidłowa, polecenie wyświetla błąd i pozostawia konfigurację bez zmian.
- Żądania są objęte ograniczaniem liczby żądań. Limit dla interfejsu API ogranicza liczbę żądań odczytu i żądań aktualizacji na minutę w przypadku każdego projektu w chmurze i każdej organizacji. Każde polecenie
updatewysyła jedno żądanie aktualizacji. Jeśli dodasz lub usuniesz testerów za pomocą flag, polecenie wyśle też żądanie odczytu. Aby zmienić kilka ustawień, przekaż je w jednym poleceniu lub jednym pliku, zamiast uruchamiać polecenie dla każdego ustawienia.
Ograniczenia
- Polecenia obsługują tylko aplikacje do Google Chat utworzone jako dodatki do Google Workspace.
- Polecenia nie obsługują kont usługi ani przejmowania tożsamości konta usługi. Musisz zalogować się w gcloud CLI za pomocą konta użytkownika.
- Projekt w chmurze ma 1 konfigurację aplikacji do obsługi czatu, której nie można usunąć za pomocą poleceń. Aby uniemożliwić użytkownikom korzystanie z aplikacji Google Chat, ustaw jej stan na wyłączony lub usuń projekt w chmurze.
- Aktualizacja dotyczy aktywnej aplikacji Google Chat. Polecenia nie mają trybu wersji roboczej ani trybu próbnego.
- Gdy aplikacja do Google Chat jest opublikowana lub sprawdzana w Google Workspace Marketplace, polecenia nie mogą zmieniać jej wyświetlanej nazwy, awatara, opisu, poleceń ani wzorców adresów URL podglądu linków.
- Polecenia obsługują ustawienia w zasobie
chatAppConfig. Aby skonfigurować ustawienie, którego nie ma w zasobie, użyj konsoli Google Cloud.
Rozwiązywanie problemów
Jeśli polecenie się nie powiedzie, znajdź tekst komunikatu o błędzie w poniższej tabeli. Jeśli wiadomość zaczyna się od stanu, takiego jak INVALID_ARGUMENT, interfejs Google Workspace Add-ons API odrzucił żądanie, a tekst po stanie opisuje problem.
| Komunikat o błędzie zawiera | Przyczyna | Rozwiązanie |
|---|---|---|
Invalid choice: 'chat-app-config' lub Invalid choice: 'workspace-add-ons' |
Polecenie nie zawiera beta lub Twoja wersja gcloud CLI nie zawiera poleceń. |
Zacznij polecenie od gcloud beta workspace-add-ons chat-app-config. Jeśli błąd będzie się powtarzał, zaktualizuj gcloud CLI do najnowszej wersji. |
PROJECT ID |
Projekt jest ustawiony na numer projektu. | Ustaw projekt na identyfikator projektu. |
Failed to parse value(s) in protobuf |
Plik konfiguracji zawiera pole, którego gcloud CLI nie rozpoznaje. Nazwę pola znajdziesz w komunikacie o błędzie. | Porównaj nazwę pola z danymi wyjściowymi polecenia describe. Jeśli pole jest nowe, zaktualizuj gcloud CLI do najnowszej wersji. |
does not have permission to access projects instance |
Interfejs API odrzucił żądanie. Tekst po tym komunikacie podaje przyczynę. Na przykład:
|
Sprawdź wymagania w sekcji Zanim zaczniesz. |
INVALID_ARGUMENT |
Wartość jest nieprawidłowa. Na przykład wyświetlana nazwa musi mieć od 3 do 25 znaków, a opis od 1 do 40 znaków. Jeśli komunikat zawiera not found or deleted, identyfikator projektu jest nieprawidłowy. |
Popraw wartość opisaną w komunikacie o błędzie i ponownie uruchom polecenie. |
FAILED_PRECONDITION |
Aplikacja do Google Chat nie zezwala na żądanie. Na przykład nie jest ona utworzona jako dodatek do Google Workspace lub została opublikowana w Google Workspace Marketplace i nie można zmienić ustawienia. | Postępuj zgodnie z instrukcjami podanymi w komunikacie o błędzie. Aby skonfigurować aplikację do Google Chat, która nie jest dodatkiem do Google Workspace, użyj konsoli Google Cloud lub przekonwertuj ją. |
RESOURCE_EXHAUSTED lub 429 |
Interfejs API otrzymał zbyt wiele żądań dotyczących projektu w chmurze lub Twojej organizacji w krótkim czasie. | Zaczekaj minutę, a potem uruchom polecenie jeszcze raz. |
Konfigurowanie aplikacji do Google Chat za pomocą interfejsu Google Workspace Add-ons API
Zamiast ręcznie konfigurować aplikację do Google Chat w konsoli Google Cloud, możesz automatycznie odczytywać i aktualizować konfigurację aplikacji do Google Chat utworzonej jako dodatek do Google Workspace za pomocą zasobu chatAppConfig w Google Workspace add-ons API.
chatAppConfig to zasób singleton, który zawsze istnieje w każdym projekcie w chmurze. Zanim po raz pierwszy zapiszesz konfigurację, zasób zawiera pustą konfigurację (którą zwraca też GetChatAppConfig, jeśli odczytasz zasób przed pierwszym zapisem). Zasób już istnieje, więc nie musisz go tworzyć osobno – użyj UpdateChatAppConfig, aby zapisać konfigurację początkową i zaktualizować istniejącą konfigurację.
Wymagania wstępne i uwierzytelnianie
Zanim wywołasz metodę GetChatAppConfig lub UpdateChatAppConfig, spełnij te wymagania wstępne:
- Włącz interfejs Google Workspace Add-ons API (
gsuiteaddons.googleapis.com) w projekcie w chmurze. Opcjonalnie możesz włączyć interfejs Google Chat API (chat.googleapis.com), jeśli chcesz wyświetlać lub aktualizować konfigurację aplikacji Google Chat w konsoli Google Cloud lub wywoływać interfejs Chat API. - Uwierzytelnij się jako użytkownik za pomocą danych logowania OAuth 2.0, które obejmują zakres
https://www.googleapis.com/auth/cloud-platform. Uwierzytelnianie konta usługi nie jest obsługiwane w przypadku metodchatAppConfig. - Sprawdź, czy uwierzytelniony użytkownik ma wymagane uprawnienia Identity and Access Management (IAM) w docelowym projekcie w chmurze:
gsuiteaddons.chatAppConfigs.getichat.bots.get, aby odczytać konfigurację (GetChatAppConfig).gsuiteaddons.chatAppConfigs.update,chat.bots.updateichat.bots.get, aby zaktualizować konfigurację (UpdateChatAppConfig).
- Jeśli używasz biblioteki klienta, zainstaluj najnowszą wersję biblioteki klienta interfejsu Google Workspace Add-ons API dla swojego języka. Listę bibliotek klienta znajdziesz w dokumentacji interfejsu API dodatków do Google Workspace.
Aktualizowanie konfiguracji aplikacji do Google Chat
Aby po raz pierwszy skonfigurować aplikację do Google Chat lub zaktualizować istniejącą konfigurację, wyślij żądanie PATCH (UpdateChatAppConfig) do zasobu singletona chatAppConfig w projekcie w chmurze:
- Aby po raz pierwszy zapisać projekt w chmurze z pustym polem
chatAppConfig, musisz podaćdisplayName(od 3 do 25 znaków) idescription(od 1 do 40 znaków). Jeśli pominieszinteractiveFeatureConfigpodczas pierwszego zapisywania, aplikacja do Google Chat zostanie skonfigurowana jako nieinteraktywna. - W przypadku kolejnych aktualizacji użyj opcjonalnego parametru zapytania
updateMask, aby określić pola do zaktualizowania rozdzielone przecinkami (lub pomińupdateMask, aby zaktualizować wszystkie podane pola). Aktualizacja pola powtarzanego (appCommands,urlPatternsluballowlistedTestingPrincipals) powoduje zastąpienie całej listy.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
W adresie URL, nagłówku i treści żądania zastąp te elementy:
PROJECT_NUMBER: numer projektu w chmurze, w którym hostowana jest aplikacja Google Chat.ACCESS_TOKEN: token dostępu OAuth 2.0 użytkownika autoryzowany z zakresemhttps://www.googleapis.com/auth/cloud-platform.USER_EMAIL: adres e-mail lub grupa dyskusyjna Google z organizacji Google Workspace, które chcesz dodać do listy dozwolonych na potrzeby testowania aplikacji Google Chat (np. Twój adres e-mail).- Przykładowe pola konfiguracji w treści żądania (takie jak
displayName,description,avatarUriiinteractiveFeatureConfig, w tym konfiguracja punktu końcowego, polecenia, wzorce adresów URL podglądu linków i podmioty zabezpieczeń testowania) z wartościami aplikacji Google Chat. Szczegółowe informacje o wszystkich obsługiwanych polach i opcjach punktów końcowych znajdziesz w dokumentacjiprojects.chatAppConfigREST iprojects.chatAppConfig.patch.
Pobieranie konfiguracji aplikacji do Google Chat
Aby odczytać bieżącą konfigurację aplikacji Google Chat w projekcie w chmurze, wywołaj metodę GetChatAppConfig.
Możesz przekazać opcjonalny parametr zapytania view (ChatAppConfigView):
BASIC(domyślna): zwraca podstawowe metadane bezinteractiveFeatureConfig.FULL: zwraca wszystkie pola konfiguracji, w tyminteractiveFeatureConfig.
Jeśli konfiguracja aplikacji Google Chat nie została jeszcze zapisana w projekcie w chmurze, metoda zwraca pusty obiekt ChatAppConfig.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
Limity wykorzystania
Metody chatAppConfig mają limity na projekt. Jeśli przekroczysz limit, żądanie nie powiedzie się i zostanie zwrócony kod stanu HTTP 429: Too many requests. Limity wykorzystania znajdziesz w artykule Limity wykorzystania interfejsu Google Workspace Add-ons API.
Rozwiązywanie problemów
Jeśli żądanie chatAppConfig nie powiedzie się, sprawdź kod stanu HTTP i pole message w odpowiedzi na błąd. W tabeli poniżej znajdziesz typowe błędy, ich przyczyny i sposoby ich rozwiązywania.
| Kod stanu HTTP | Typowe przyczyny | Rozdzielczość |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
Sprawdź pole message, aby znaleźć nieprawidłowe pole, i popraw żądanie. Obsługiwane pola i wartości znajdziesz w dokumentacji projects.chatAppConfig. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
Projekt w chmurze w nazwie zasobu nie istnieje lub uwierzytelniony użytkownik nie ma do niego dostępu. | Sprawdź, czy nazwa zasobu używa prawidłowego numeru projektu w formacie projects/PROJECT_NUMBER/chatAppConfig i czy użytkownik ma dostęp do projektu w chmurze. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
Przekroczono limit na projekt. | Zaczekaj i spróbuj ponownie później. Limity znajdziesz w artykule Limity wykorzystania. |
Uwagi dotyczące dotychczasowych dodatków do Google Workspace
Aplikacje do Google Chat wymagają innej konfiguracji niż dodatki do Google Workspace, które rozszerzają inne aplikacje Google Workspace. Jeśli dodatek rozszerza inne aplikacje Google Workspace, weź pod uwagę te wymagania dotyczące konfigurowania aplikacji Google Chat:
- Zarówno osoby fizyczne, jak i administratorzy Google Workspace muszą mieć możliwość zainstalowania dodatku z Marketplace. Te ustawienia instalacji konfigurujesz w pakiecie SDK Marketplace.
- Aplikacje do Google Chat nie używają nazwy ani logo skonfigurowanych dla innych aplikacji Google Workspace w obiekcie
addons.commonw pliku manifestu. - W przypadku dodatków opublikowanych w Google Workspace Marketplace nie możesz zapisać wersji roboczej zmian w ustawieniach konfiguracji interfejsu Google Chat API. Gdy zaktualizujesz i zapiszesz ustawienia konfiguracji interfejsu Chat API, zaktualizowana aplikacja Google Chat będzie natychmiast dostępna dla wszystkich dotychczasowych użytkowników. Aby zaktualizować informacje o usłudze w Marketplace, możesz utworzyć wersję roboczą przed przesłaniem zmian.
- Jeśli dodatek został utworzony za pomocą Apps Script:
- Musisz użyć tego samego identyfikatora wdrożenia Apps Script, którego używasz w pozostałej części konfiguracji dodatku.
- Nie możesz używać edytora Apps Script do instalowania wdrożeń testowych w Google Chat. Zamiast tego musisz zainstalować je bezpośrednio z interfejsu Google Chat.
- Jeśli dodatek został utworzony przy użyciu usługi HTTP, pomiń szczegóły konfiguracji aplikacji do Google Chat w pliku manifestu
projects.deployments, który tworzysz za pomocą interfejsu Google Workspace Add-ons API. Wdrożenia HTTP określone w pakiecie SDK Google Workspace Marketplace są używane tylko w innych aplikacjach Google Workspace. Zamiast tego skonfiguruj aplikację do Google Chat w konsoli Google Cloud, za pomocą gcloud CLI lub zasobuchatAppConfigw interfejsie Google Workspace Add-ons API.
Przyznawanie innym osobom uprawnień do konfigurowania interfejsu Chat API
Możesz przyznać określonym użytkownikom dostęp do strony konfiguracji aplikacji do Google Chat, przypisując im rolę Właściciel aplikacji do Google Chat lub Przeglądający aplikacje do Google Chat w Google Cloud Identity Access Management (IAM). Użytkownicy z tymi rolami nie mogą przejść na stronę konfiguracji aplikacji do Google Chat za pomocą panelu Interfejsy API i usługi, ale mogą uzyskać dostęp do strony konfiguracji, przechodząc do konsoli Google Cloud projektu w chmurze hosta aplikacji do Google Chat w ten sposób:
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
Gdzie PROJECT_ID to identyfikator projektu Google Cloud, w którym hostowana jest aplikacja Google Chat.
Powiązane artykuły
- Wybieranie architektury aplikacji do Google Chat
- Odbieranie interakcji użytkowników i reagowanie na nie
- Testowanie funkcji interaktywnych aplikacji do Google Chat
Aplikacje do Google Chat, które nie są dodatkami: skonfiguruj Google Chat API
Jeśli zarządzasz aplikacją do Google Chat, która nie jest dodatkiem do Google Workspace, konfiguracja używa jednego punktu końcowego dla wszystkich zdarzeń interakcji, a nie aktywatorów dla poszczególnych zdarzeń:
W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API:
W sekcji Funkcje interaktywne włącz opcję Włącz funkcje interaktywne.
Odznacz pole Utwórz tę aplikację do Google Chat jako dodatek do Google Workspace. Otworzy się okno z prośbą o potwierdzenie. W oknie dialogowym kliknij Wyłącz.
W sekcji Funkcje wybierz Strona główna aplikacji pomocy lub Dołączanie do pokoi i rozmów grupowych.
W sekcji Ustawienia połączenia określ pojedynczy punkt końcowy dla aplikacji Google Chat (Adres URL punktu końcowego HTTP, identyfikator wdrożenia Apps Script, Nazwa tematu Cloud Pub/Sub lub Dialogflow).
Skonfiguruj opcjonalne Polecenia, Prompty początkowe, Podglądy linków, Widoczność i Logi, a następnie kliknij Zapisz.
Aby przekształcić aplikację do Google Chat, która nie jest dodatkiem, w dodatek do Google Workspace rozszerzający Google Chat, zapoznaj się z artykułem Przekształcanie aplikacji do Google Chat w dodatek do Google Workspace.