Konfigurowanie interfejsu Google Chat API

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:

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:

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:

1. W konsoli Google Cloud otwórz stronę interfejsu Chat API i kliknij Konfiguracja:

   Otwórz stronę konfiguracji interfejsu Google Chat API

2. W sekcji Informacje o aplikacji wypełnij pola Nazwa aplikacji, URL awatara i Opis.

3. Opcjonalnie: wypełnij pole Długi opis (dostępne w ramach programu wersji przedpremierowej Google Workspace dla deweloperów).

4. 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.

5. 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:

   1. 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.

   2. 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.

   3. 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.

   4. 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.

   5. 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.

6. 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.

7. 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ą interfejsu Google Workspace Add-ons API

Zamiast ręcznie konfigurować aplikację Google Chat w konsoli Google Cloud, możesz użyć projektu w chmurze Google zarejestrowanego w programie wersji przedpremierowej dla programistów Google Workspace, aby automatycznie odczytywać i aktualizować konfigurację aplikacji 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:

1. Zarejestruj swój projekt Google Cloud w programie wersji przedpremierowej Google Workspace dla deweloperów.
2. 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.
3. 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 metod chatAppConfig.
4. Sprawdź, czy uwierzytelniony użytkownik ma wymagane uprawnienia Identity and Access Management (IAM) w docelowym projekcie w chmurze:
   • gsuiteaddons.chatAppConfigs.get i chat.bots.get, aby odczytać konfigurację (GetChatAppConfig).
   • gsuiteaddons.chatAppConfigs.update i chat.bots.update, aby zaktualizować konfigurację (UpdateChatAppConfig).
5. Jeśli używasz biblioteki klienta, pobierz bibliotekę klienta w wersji przedpremierowej dla programistów, korzystając z zarejestrowanego konta w wersji przedpremierowej dla programistów.

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) i description (od 1 do 40 znaków). Jeśli pominiesz interactiveFeatureConfig podczas 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, urlPatterns lub allowlistedTestingPrincipals) 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 zakresem https://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, avatarUri i interactiveFeatureConfig, 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 dokumentacji projects.chatAppConfig REST i projects.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 bez interactiveFeatureConfig.
• FULL: zwraca wszystkie pola konfiguracji, w tym interactiveFeatureConfig.

Jeśli konfiguracja aplikacji Google Chat nie została jeszcze zapisana w projekcie w chmurze, metoda zwraca pusty obiekt ChatAppConfig.

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

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();

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)

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.common w 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 lub za pomocą zasobu chatAppConfig w 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