Przekształcanie interaktywnej aplikacji Google Chat w dodatek do Google Workspace

Jeśli masz utworzoną i opublikowaną aplikację do obsługi czatu w Google Chat, która korzysta ze zdarzeń interakcji interfejsu Google Chat API, np. aplikację opartą na szybkim wprowadzeniu do aplikacji Google Chat, na tej stronie dowiesz się, jak przekonwertować ją na dodatek do Google Workspace, który rozszerza Google Chat.

Po przekonwertowaniu aplikacja Google Chat może korzystać z platformy dodatków do Google Workspace, co otwiera nowe możliwości integracji i funkcji w Google Chat i w Google Workspace. Na przykład zamiast rozpowszechniać 2 wersje – aplikację Google Chat i dodatek do Google Workspace – możesz rozpowszechniać jeden dodatek do Google Workspace w Google Workspace Marketplace, który rozszerza aplikacje do czatu wraz z innymi aplikacjami hosta Google Workspace, takimi jak Gmail, Kalendarz i Dokumenty.

Ograniczenia

Przed rozpoczęciem konwersji zapoznaj się z ograniczeniami dodatków do Google Workspace, które rozszerzają Google Chat, aby mieć pewność, że aplikację Google Chat można przekonwertować bez utraty podstawowych funkcji.

Krok 1. Skopiuj kod istniejącej aplikacji Google Chat

Proces konwersji wymaga zmian w kodzie. Aby nie wpływać na działanie aplikacji Google Chat, utwórz kopię kodu i na niej pracuj.

Google Apps Script

  1. Otwórz istniejący projekt Google Apps Script aplikacji Google Chat.
  2. Po lewej stronie kliknij Przegląd .
  3. Po prawej stronie kliknij Utwórz kopię .
  4. Po lewej stronie kliknij Ustawienia projektu .
  5. W sekcji Projekt Google Cloud kliknij Zmień projekt.
  6. Wpisz ten sam numer projektu powiązany z istniejącym projektem aplikacji Google Chat.
  7. Kliknij Ustaw projekt.

HTTP

Utwórz rozwidlenie lub kopię istniejącej bazy kodu i wdroż ją jako nową usługę, oddzielną od działającej aplikacji Google Chat.

Jeśli aplikacja jest wdrażana w Google Cloud i korzysta z funkcji powiązanych z projektem Google Cloud (np. domyślnej tożsamości App Engine), nowy kod należy wdrożyć w usłudze powiązanej z dotychczasowym projektem aplikacji Google Chat.

Krok 2. Zmodyfikuj skopiowany kod

Dodatki do Google Workspace, które rozszerzają Google Chat, używają innych struktur żądań i odpowiedzi niż aplikacje Google Chat utworzone za pomocą zdarzeń interakcji interfejsu Chat API. Musisz zaktualizować kod, aby używać dodatku Google WorkspaceEventObject zamiast interfejsu Google Chat APIEvent do obsługi żądań i odpowiedzi. Aby zmodyfikować kod, skorzystaj z przewodnika po konwersji kodu.

Krok 3. Włącz konfigurację dodatku do Google Workspace dla użytkowników testowych

W konsoli Google Cloud skonfiguruj ustawienia dodatku do Google Workspace dla aplikacji Google Chat:

  1. Otwórz stronę konfiguracji interfejsu Google Chat API w konsoli Google Cloud.

    Otwórz stronę konfiguracji interfejsu Google Chat API

  2. W sekcji Funkcje interaktywne kliknij Przekształć w dodatek.

  3. Włącz opcję Włącz ustawienia konfiguracji dodatku.

  4. W sekcji Widoczność dodaj adresy e-mail testerów.

  5. W razie potrzeby zaktualizuj ustawienia połączenia, podając adres URL punktu końcowego wdrożenia lub identyfikator wdrożenia Apps Script skopiowanego i zmodyfikowanego kodu aplikacji Google Chat z kroku 2.

  6. Kliknij Zapisz i przetestuj.

Krok 4. Przetestuj przekonwertowaną aplikację

Dokładnie przetestuj funkcje dodatku do Google Workspace, korzystając z kont użytkowników testowych skonfigurowanych w kroku 3. Sprawdź wszystkie funkcje i interakcje.

Krok 5. Przeprowadź konwersję u wszystkich użytkowników

Po sprawdzeniu, czy przekonwertowany dodatek Google Workspace działa prawidłowo, możesz udostępnić go wszystkim użytkownikom.

  1. Otwórz stronę konfiguracji interfejsu Google Chat API w konsoli Google Cloud.

    Otwórz stronę konfiguracji interfejsu Google Chat API

  2. W sekcji Funkcje interaktywne kliknij Przekształć w dodatek. Otworzy się panel boczny.

  3. W panelu bocznym kliknij Przekształć w dodatek.

  4. Wpisz identyfikator projektu i kliknij Konwertuj.

Twoja aplikacja Google Chat jest teraz dodatkiem do Google Workspace, który rozszerza Google Chat.

Opcjonalnie: wyczyść lub zwolnij nieużywane zasoby Google Cloud

Opcjonalnie, po przekonwertowaniu aplikacji Google Chat na dodatek Google Workspace, aby uniknąć obciążenia konta Google Cloud opłatami za zasoby używane przez aplikację Google Chat, które nie są już używane, możesz je wyłączyć.

Przewodnik po konwersji kodu

W tej sekcji znajdziesz szczegółowe informacje o mapowaniu formatu interakcji interfejsu Google Chat APIEventEventObject na format dodatku do Google Workspace.

Mapowanie żądań

W tabeli poniżej pokazano, jak pola w interfejsie Google Chat APIEvent odpowiadają polom w dodatku do Google WorkspaceEventObject.

Pole interakcji z interfejsem Google Chat API Event Pole dodatku do Google Workspace EventObject Uwagi
action.actionMethodName Nie dotyczy W przypadku interakcji z kartą nazwę metody można przekazać jako parametr w commonEventObject.parameters. Zobacz Otwieranie okna początkowego.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Dostępne w różnych ładunkach w zależności od typu zdarzenia.
token Nie dotyczy Weryfikacja jest obsługiwana w inny sposób. Więcej informacji znajdziesz w artykule Request Verification for HTTP Apps (Weryfikacja żądań w przypadku aplikacji HTTP).
type Nie dotyczy Typ zdarzenia można wywnioskować z aktywatora.
user chat.user

Mapowanie żądań według przypadku użycia

Tabela poniżej przedstawia różnice w ładunkach żądań w przypadku typowych zastosowań aplikacji Google Chat utworzonych za pomocą zdarzeń interakcji interfejsu Chat API i dodatków do Google Workspace, które rozszerzają Google Chat.

Przypadek użycia Interakcja z Chat API Event ładunek Ładunek dodatku do Google Workspace EventObject
Aplikacja została dodana do pokoju 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Usuwanie aplikacji z pokoju 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Użytkownik @wzmiankuje aplikację 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
Użytkownik @wspomina aplikację, aby dodać ją do pokoju. Musisz obsłużyć 1 prośbę z Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Musisz obsłużyć 2 żądania z Google Chat.

Pierwsze żądanie:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Drugie żądanie:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Polecenie po ukośniku 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Polecenie po ukośniku do dodawania aplikacji do pokoju Musisz obsłużyć 1 prośbę z Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Musisz obsłużyć 2 żądania z Google Chat.

Pierwsze żądanie:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Drugie żądanie:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Użytkownik klika przycisk na karcie lub w oknie 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

W przypadku zdarzeń związanych z oknem dialogowym pole common.formInputs zawiera wartości widżetów. Przykład Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

W przypadku zdarzeń związanych z oknem dialogowym pole commonEventObject.formInputs zawiera wartości widżetów. Przykład Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
Użytkownik przesyła informacje na karcie głównej aplikacji 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
Użytkownik wywołuje polecenie aplikacji za pomocą szybkiego polecenia 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Podgląd linku 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
Użytkownik aktualizuje widżet w wiadomości na karcie lub w oknie. 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Mapowanie odpowiedzi według przypadku użycia

Dodatki do Google Workspace, które rozszerzają Google Chat, zwracają działania zamiast obiektu Message. W tabeli poniżej znajdziesz mapowanie typów odpowiedzi interfejsu Google Chat APIMessage na odpowiadające im działania dodatku do Google Workspace.

Przypadek użycia Odpowiedź interfejsu Google Chat API Message Odpowiedź działania w Google Chat dodatku do Google Workspace
Tworzenie wiadomości w wywołanym pokoju 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

Opcjonalny składnik to actionResponse. Więcej informacji znajdziesz w artykule Odpowiadanie na polecenie po ukośniku.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Więcej informacji znajdziesz w artykule Wysyłanie wiadomości.
Aktualizowanie wiadomości 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Więcej informacji znajdziesz w artykule Aktualizowanie wiadomości (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Więcej informacji znajdziesz w artykule Aktualizowanie wiadomości (dodatki).
Podgląd linku 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linku (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linku(dodatki).
Otwieranie pierwszego okna 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Więcej informacji znajdziesz w artykule Otwieranie okna (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
Karta, którą przesuwasz, może zawierać widżety z onClick działaniami. W przypadku dodatków do Google Workspace HTTP skonfiguruj te działania, aby wywoływać punkt końcowy funkcji: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Więcej informacji znajdziesz w artykule Otwieranie okna (dodatki).
Zamykanie okna 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Więcej informacji znajdziesz w artykule Zamykanie okna (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Więcej informacji znajdziesz w artykule Zamykanie okna (dodatki).
Łączenie z systemem zewnętrznym (konfiguracja żądania) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Więcej informacji znajdziesz w artykule Łączenie się z systemem zewnętrznym.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Więcej informacji znajdziesz w artykule Łączenie dodatku do Google Workspace z usługą innej firmy.
Autouzupełnianie elementów w widżetach interaktywnych 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Więcej informacji znajdziesz w artykule Dodawanie menu wielokrotnego wyboru.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Więcej informacji znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników Google Chat.

Obsługa interakcji z kartami w przypadku wiadomości utworzonych przed konwersją

Gdy przekonwertujesz aplikację Google Chat HTTP na dodatek do Google Workspace, interakcje z kartami w wiadomościach utworzonych przed konwersją będą wymagać specjalnego traktowania. Dodatki do Google Workspace używają pełnego adresu URL HTTP dla action.function karty, a aplikacje Google Chat utworzone za pomocą zdarzeń interakcji interfejsu Google Chat API używają nazwy funkcji. W tabeli poniżej zestawiono te różnice.

Aplikacja Google Chat utworzona za pomocą zdarzeń interakcji interfejsu Google Chat API Dodatek do Google Workspace, który rozszerza Google Chat
Konfiguracja Wszystkie zdarzenia możesz skonfigurować w jednym punkcie końcowym w konsoli Google Cloud. Podczas implementowania interakcji z kartą element action karty zawiera tylko nazwę funkcji do wykonania. Wspólny punkt końcowy HTTP jest wywoływany w przypadku zdarzeń kliknięcia karty.

Więcej informacji znajdziesz w artykule Otwieranie okna (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 W konsoli Google Cloud możesz opcjonalnie skonfigurować punkty końcowe dla poszczególnych zdarzeń, ale nie obejmuje to zdarzeń kliknięcia karty. Podczas implementowania interakcji z kartą element action karty musi zawierać pełny adres URL punktu końcowego HTTP, który ma zostać wywołany. Możesz ustawić unikalny punkt końcowy HTTP dla każdego przycisku lub użyć wspólnego punktu końcowego i przekazać działanie jako parametr w action.parameters.

Więcej informacji znajdziesz w artykule Otwieranie okna (dodatki).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Aby interakcje z kartami działały w przypadku wiadomości utworzonych przed konwersją, skonfiguruj adres URL interakcji z kartą na stronie konfiguracji interfejsu Google Chat API.

Ten adres URL jest używany tylko w przypadku interakcji z wiadomościami utworzonymi przed przekonwertowaniem aplikacji. Gdy użytkownik wejdzie w interakcję z jedną z tych wiadomości, pierwotna wartość action.function zostanie przekazana jako parametr o nazwie __action_method_name__.

Przykład: kliknięcie karty

Jeśli skonfigurowano adres URL interakcji z kartą jako https://.../card-interaction-handler, a użytkownik kliknie kartę w wiadomości historycznej, wykonując następujące działanie:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Zdarzenie jest dostarczane na skonfigurowany adres URL interakcji z kartą w tym formacie:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Przykład: menu wybierania wielu elementów

Jeśli użytkownik wchodzi w interakcję z menu wielokrotnego wyboru ze źródłem danych zewnętrznych:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Zdarzenie jest dostarczane na skonfigurowany adres URL interakcji z kartą w tym formacie:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Jeśli włączysz opcję Używaj wspólnego adresu URL punktu końcowego HTTP dla wszystkich aktywatorów w przypadku aktywatorów HTTP, wspólny adres URL będzie też używany w przypadku zdarzeń Kliknięcie przycisku.

Weryfikowanie żądań dotyczących dodatków HTTP do Google Workspace, które rozszerzają Google Chat

W przypadku aplikacji Google Chat opartych na protokole HTTP podczas konwertowania ich na dodatki do Google Workspace należy zaktualizować logikę weryfikacji, czy żądania pochodzą z Google.

Główne różnice w weryfikacji żądań to:

Typ treści Obsługiwani odbiorcy E-mail konta usługi
Aplikacja Google Chat utworzona za pomocą zdarzeń interakcji interfejsu Google Chat API Numer projektu chat@system.gserviceaccount.com
Dodatek do Google Workspace rozszerzający Google Chat Tylko punkt końcowy HTTP Adres e-mail konta usługi w projekcie

Unikalny adres e-mail konta usługi dla dodatku Google Workspace znajdziesz w sekcji Konwertowanie na dodatki Google Workspace na stronie konfiguracji interfejsu Google Chat API w konsoli Google Cloud.

Aby weryfikować żądania w ulepszonym dodatku do Google Workspace:

  1. Jeśli używasz funkcji Cloud Run, przypisz rolę roles/cloudfunctions.invoker do konta usługi każdego dodatku. Więcej informacji znajdziesz w artykule Autoryzowanie dostępu za pomocą uprawnień.
  2. Zaktualizuj kod weryfikacyjny tokena, aby używać adresu e-mail konta usługi dodatku Google Workspace do weryfikowania podpisu tokena okaziciela. Zobacz Weryfikowanie żądań od Google.