Otrzymywanie interakcji z aplikacją Google Chat i odpowiadanie na nie

Z tego artykułu dowiesz się, jak aplikacja Google Chat może odbierać interakcje z użytkownikami i na nie reagować, nazywane też zdarzeniami interakcji z aplikacją Google Chat.

Zdarzenie interakcji z aplikacją Google Chat reprezentuje dowolne działanie podejmowane przez użytkownika w celu wywołania aplikacji do obsługi czatu lub interakcji z nią. Może to być np. @wzmianka o aplikacji do obsługi czatu lub dodanie jej do pokoju. Gdy użytkownicy wchodzą w interakcję z aplikacją do obsługi czatu, Google Chat wysyła do niej zdarzenie interakcji. Aplikacja Google Chat może wykorzystać to zdarzenie, aby przetworzyć interakcję i utworzyć odpowiedź.

Aplikacje do obsługi czatu używają zdarzeń interakcji do wykonywania:

W przypadku każdego typu interakcji użytkownika Google Chat wysyła inny typ zdarzenia interakcji. Na przykład Google Chat używa typu zdarzenia MESSAGE w przypadku każdej interakcji, w której użytkownik wywołuje aplikację Google Chat w wiadomości. Więcej informacji znajdziesz w artykule Typy zdarzeń interakcji z aplikacją Google Chat.

Na tej stronie dowiesz się, jak:

• Skonfiguruj aplikację Google Chat, aby otrzymywać zdarzenia.
• Przetwarzanie zdarzenia interakcji w swojej infrastrukturze.
• W razie potrzeby zareaguj na zdarzenia interakcji.

Odbieranie zdarzeń interakcji z aplikacją Google Chat

Z tej sekcji dowiesz się, jak odbierać i przetwarzać zdarzenia interakcji z aplikacją Google Chat.

Konfigurowanie aplikacji Google Chat pod kątem odbierania zdarzeń interakcji

Nie wszystkie aplikacje do obsługi czatu są interaktywne. Na przykład webhooki przychodzące mogą tylko wysyłać wiadomości wychodzące i nie mogą odpowiadać użytkownikom. Jeśli tworzysz interaktywną aplikację do obsługi czatu, musisz wybrać punkt końcowy, który umożliwi aplikacji Google Chat odbieranie i przetwarzanie zdarzeń interakcji oraz reagowanie na nie. Więcej informacji o projektowaniu aplikacji do obsługi czatu znajdziesz w artykule na temat architektury wdrożenia aplikacji do obsługi czatu.

Jeśli masz utworzoną interaktywną aplikację Google Chat, musisz skonfigurować interfejs Google Chat API, aby usługa Google Chat mogła wysyłać Ci zdarzenia interakcji:

1. W konsoli Google Cloud otwórz stronę Google Chat API:

   Otwórz stronę interfejsu Google Chat API

2. Kliknij kartę Configuration (Konfiguracja).
3. W sekcji Funkcje interaktywne kliknij przełącznik Włącz funkcje interaktywne, aby ustawić go w pozycji włączenia.
4. W sekcji Funkcjonalność zaznacz jedno lub oba z tych pól wyboru:
   1. Odbieranie wiadomości 1:1: pozwala użytkownikom korzystać z Twojej aplikacji Google Chat w pokojach czatu. Aplikacja do obsługi czatu otrzymuje zdarzenia interakcji za każdym razem, gdy użytkownik wysyła wiadomość w pokoju czatu.
   2. Dołączanie do pokoi i rozmów grupowych: pozwala użytkownikom dodawać aplikację Google Chat do pokoi z więcej niż jedną osobą i usuwać ją z tych pokoi. Aplikacja do obsługi czatu otrzymuje zdarzenia interakcji za każdym razem, gdy zostanie ona dodana do pokoju lub z niego usunięta, a także za każdym razem, gdy użytkownik napisze @wzmiankę lub użyje w pokoju polecenia po ukośniku.
5. W sekcji Ustawienia połączenia określ, gdzie Google Chat ma wysyłać zdarzenia interakcji z aplikacją Google Chat.
6. Opcjonalnie: w sekcji Polecenia po ukośniku dodaj i skonfiguruj co najmniej 1 polecenie po ukośniku. Więcej informacji znajdziesz w artykule Konfigurowanie poleceń po ukośniku.
7. Opcjonalnie: w sekcji Podgląd linków dodaj i skonfiguruj co najmniej 1 wzorzec adresu URL, którego podgląd wyświetla aplikacja do obsługi czatu. Więcej informacji znajdziesz w artykule Podgląd linków.
8. Kliknij Zapisz.

Twoja aplikacja do obsługi czatu jest teraz skonfigurowana tak, aby odbierać zdarzenia interakcji z Google Chat.

Uwierzytelnianie żądań z Google Chat

W przypadku aplikacji utworzonych w punktach końcowych HTTP w tej sekcji znajdziesz instrukcje sprawdzania, czy żądania do Twojego punktu końcowego pochodzą z Google Chat.

Aby wysyłać zdarzenia interakcji do punktu końcowego aplikacji do obsługi czatu, Google wysyła żądania do Twojej usługi. Aby potwierdzić, że żądanie pochodzi z Google, Google Chat umieszcza token okaziciela w nagłówku Authorization każdego żądania HTTPS wysyłanego do punktu końcowego. Na przykład:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

Ciąg AbCdEf123456 w powyższym przykładzie to token autoryzacji okaziciela. Jest to token kryptograficzny wygenerowany przez Google. Token okaziciela możesz zweryfikować za pomocą biblioteki klienta interfejsu API Google typu open source:

• Java: https://github.com/google/google-api-java-client
• Python: https://github.com/google/google-api-python-client
• .NET: https://github.com/google/google-api-dotnet-client

W przypadku tokenów okaziciela wysyłanych w żądaniach Google Chat wydawca to chat@system.gserviceaccount.com, a pole audience jest ustawione na numer projektu Google Cloud użytego do skompilowania aplikacji Google Chat. Jeśli na przykład numer projektu Cloud aplikacji Google Chat to 1234567890, pole audience w tokenie okaziciela to 1234567890.

Jeśli token nie zostanie zweryfikowany w przypadku aplikacji Google Chat, Twoja usługa powinna odpowiedzieć na żądanie, używając kodu odpowiedzi HTTPS 401 (Unauthorized).

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Obsługa ponownych prób wywołań HTTP w usłudze

Jeśli żądanie HTTPS do Twojej usługi nie powiedzie się (na przykład upłynie czas oczekiwania, tymczasowa awaria sieci lub kod stanu HTTPS inny niż 2xx), Google Chat może ponawiać próbę dostarczenia w ciągu kilku minut (nie jest to jednak gwarantowane). W związku z tym w pewnych sytuacjach aplikacja do obsługi czatu może kilka razy otrzymać tę samą wiadomość. Jeśli żądanie zostanie ukończone, ale zwróci nieprawidłowy ładunek wiadomości, Google Chat nie ponawia żądania.

Przetwarzanie zdarzeń interakcji i reagowanie na nie

W tej sekcji wyjaśniamy, jak aplikacje Google Chat mogą przetwarzać zdarzenia interakcji i reagować na nie.

Gdy aplikacja do obsługi czatu otrzyma zdarzenie interakcji z Google Chat, może zareagować na wiele sposobów. W wielu przypadkach interaktywne aplikacje do obsługi czatu wysyłają do użytkownika wiadomość. Aplikacja Google Chat może też wyszukiwać niektóre informacje ze źródła danych, rejestrować informacje o zdarzeniu interakcji i robić wszystko inne. Zasadniczo to sposób przetwarzania danych definiuje aplikację Google Chat.

W przypadku każdego zdarzenia interakcji aplikacje do obsługi czatu otrzymują treść żądania, która jest ładunkiem JSON reprezentującym zdarzenie. Możesz wykorzystać te informacje do przetworzenia odpowiedzi. Przykłady ładunków zdarzeń znajdziesz w artykule Typy zdarzeń interakcji z aplikacją Google Chat.

Ten diagram pokazuje, jak aplikacja Google Chat zazwyczaj przetwarza różne typy zdarzeń interakcji lub na nie reaguje:

Odpowiadaj w czasie rzeczywistym

Zdarzenia interakcji pozwalają aplikacjom do obsługi czatu odpowiadać w czasie rzeczywistym lub synchronicznie. Odpowiedzi synchroniczne nie wymagają uwierzytelniania.

Jeśli chcesz utworzyć synchroniczne odpowiedzi na zdarzenia interakcji, skorzystaj z tych przewodników:

• Utwórz wiadomość karty
• Tworzenie SMS-a
• Otwieranie interaktywnych okien
• Podgląd linków
• Odczytywanie danych wprowadzonych w formularzu przez użytkowników na kartach
• Konfigurowanie poleceń po ukośniku

Aby odpowiedzieć synchronicznie, aplikacja do obsługi czatu musi odpowiedzieć w ciągu 30 sekund, a odpowiedź musi zostać opublikowana w miejscu, w którym doszło do interakcji. W przeciwnym razie aplikacja Google Chat może odpowiadać asynchronicznie.

Odpowiadaj asynchronicznie

Czasami aplikacje do obsługi czatu muszą odpowiedzieć na zdarzenie interakcji po 30 sekundach lub wykonać zadania poza pokojem, w którym zostało wygenerowane zdarzenie interakcji. Na przykład aplikacja do obsługi czatu może być zmuszona do udzielenia odpowiedzi użytkownikowi po wykonaniu długo trwającego zadania. W takim przypadku aplikacje do obsługi czatu mogą odpowiadać asynchronicznie, wywołując interfejs Google Chat API.

Aby utworzyć wiadomość za pomocą interfejsu Chat API, przeczytaj sekcję Tworzenie wiadomości. Wskazówki dotyczące korzystania z dodatkowych metod Chat API znajdziesz w omówieniu interfejsu Chat API.