Jeśli masz utworzoną i opublikowaną aplikację do Google Chat, która nie jest dodatkiem do Google Workspace, na tej stronie dowiesz się, jak przekonwertować ją na dodatek do Google Workspace, który rozszerza Google Chat.
Po przekonwertowaniu aplikacja do obsługi czatu w Google 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. Możesz na przykład rozpowszechniać jeden dodatek do Google Workspace w Google Workspace Marketplace, który rozszerza aplikacje Google Chat wraz z innymi aplikacjami hosta Google Workspace, takimi jak Gmail, Kalendarz i Dokumenty.
Ograniczenia
Przed rozpoczęciem konwersji zapoznaj się z ograniczeniami i kwestiami dotyczącymi dodatków do Google Workspace, aby mieć pewność, że aplikacja do Google Chat, która nie jest dodatkiem, może zostać przekonwertowana bez utraty podstawowych funkcji.
Krok 1. Skopiuj istniejący kod aplikacji Google Chat
Proces konwersji wymaga zmian w kodzie. Aby nie wpływać na działanie aplikacji Google Chat w wersji produkcyjnej, utwórz kopię kodu i pracuj nad nią.
Google Apps Script
- Otwórz istniejący projekt Google Apps Script aplikacji Google Chat.
- Po lewej stronie kliknij Przegląd .
- Po prawej kliknij Utwórz kopię .
- Po lewej stronie kliknij Ustawienia projektu .
- W sekcji Projekt Google Cloud kliknij Zmień projekt.
- Wpisz ten sam numer projektu, który jest powiązany z istniejącym projektem aplikacji Google Chat.
- Kliknij Ustaw projekt.
HTTP
Utwórz rozwidlenie lub kopię istniejącej bazy kodu i wdróż ją jako nową usługę, oddzielną od aktywnej aplikacji Google Chat.
Jeśli aplikacja jest wdrożona 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, które nie są dodatkami. Musisz zaktualizować kod, aby w przypadku żądań i odpowiedzi używać obiektów zdarzeń dodatku do Google Workspace (EventObject) zamiast zdarzeń interakcji interfejsu Google Chat API (Event).
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:
Otwórz stronę konfiguracji interfejsu Google Chat API w konsoli Google Cloud.
W sekcji Funkcje interaktywne włącz opcję Włącz funkcje interaktywne.
W sekcji Przekształć w dodatek do Google Workspace kliknij Przekształć w dodatek.
Włącz opcję Włącz ustawienia konfiguracji dodatku.
W sekcji Widoczność dodaj adresy e-mail użytkowników testowych.
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.
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ę dla wszystkich użytkowników
Po sprawdzeniu, czy przekonwertowany dodatek do Google Workspace działa prawidłowo, możesz udostępnić go wszystkim użytkownikom.
Otwórz stronę konfiguracji interfejsu Google Chat API w konsoli Google Cloud.
W sekcji Funkcje interaktywne kliknij Przekształć w dodatek. Otworzy się panel boczny.
W panelu bocznym kliknij Przekształć w dodatek.
Wpisz identyfikator projektu i kliknij Konwertuj.
Twoja aplikacja do obsługi Google Chat jest teraz dodatkiem do Google Workspace, który rozszerza funkcje Google Chat.
Opcjonalnie: zwolnij miejsce lub zwolnij nieużywane zasoby Google Cloud
Opcjonalnie, po przekształceniu aplikacji Google Chat w 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 APIEvent na format dodatku do Google WorkspaceEventObject.
Mapowanie żądań
W tabeli poniżej pokazujemy, jak pola w interfejsie Google Chat APIEvent aplikacji do obsługi czatu, która nie jest dodatkiem,EventObject odpowiadają polom w dodatku do Google Workspace.
Aplikacja do obsługi czatu, która nie jest dodatkiem (pole 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 polu commonEventObject.parameters. Zobacz Otwieranie początkowego okna dialogowego. |
action.parameters |
commonEventObject.parameters |
|
appCommandMetadata |
chat.appCommandPayload.appCommandMetadata |
|
common |
commonEventObject |
|
configCompleteRedirectUrl |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
dialogEventType |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
eventTime |
chat.eventTime |
|
isDialogEvent |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
message |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
space |
|
|
thread |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
threadKey |
|
Dostępne w różnych ładunkach w zależności od typu zdarzenia. |
token |
Nie dotyczy | Weryfikacja przebiega inaczej. Więcej informacji znajdziesz w artykule Prośba o weryfikację 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ń między aplikacjami do obsługi czatu, które nie są dodatkami, a dodatkami do Google Workspace rozszerzającymi Google Chat.
| Przypadek użycia | Aplikacja do obsługi czatu, która nie jest dodatkiem (Event Payload) |
Ł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 { "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": { "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 Messagetypów odpowiedzi interfejsu Google Chat API w przypadku aplikacji Google Chat, która nie jest dodatkiem, na ich odpowiedniki w postaci działań dodatku do Google Workspace.
| Przypadek użycia | Aplikacja do obsługi czatu, która nie jest dodatkiem (Message odpowiedź) |
Odpowiedź działania w Google Chat dodatku do Google Workspace |
|---|---|---|
| Utwórz wiadomość w wywołanym pokoju | { "actionResponse": { "type": "NEW_MESSAGE" }, "text": "..." }
|
{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": { "text": "..." } } } } } Więcej informacji znajdziesz w artykule Odpowiadanie wiadomością. |
| Aktualizowanie wiadomości | { "actionResponse": { "type": "UPDATE_MESSAGE" }, "text": "..." } Więcej informacji znajdziesz w artykule Aktualizowanie wiadomości. |
{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": { "message": { "text": "..." } } } } } Więcej informacji znajdziesz w artykule Aktualizowanie wiadomości. |
| Podgląd linku | { "actionResponse": { "type": "UPDATE_USER_MESSAGE_CARDS" }, "cardsV2": [{ ... }] } Więcej informacji znajdziesz w sekcji Podgląd linków. |
{ "hostAppDataAction": { "chatDataAction": { "updateInlinePreviewAction": { "cardsV2": [{ ... }] } } } } Więcej informacji znajdziesz w sekcji Podgląd linków. |
| Otwieranie okna początkowego | { "actionResponse": { "type": "DIALOG", "dialogAction": { "dialog": { "body": { /* Card object */ } } } } } Więcej informacji znajdziesz w artykule Otwieranie interaktywnych okien dialogowych. |
{ "action": { "navigations": [{ "pushCard": { /* Card object */ } }] } } Karta, którą wysyłasz, 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 interaktywnych okien dialogowych. |
| Zamykanie okna | { "actionResponse": { "type": "DIALOG", "dialogAction": { "actionStatus": { "userFacingMessage": "..." } } } } Więcej informacji znajdziesz w artykule Zamykanie okna. |
{ "action": { "navigations": [{ "endNavigation": "CLOSE_DIALOG" }], "notification": { "text": "..."} } } Więcej informacji znajdziesz w artykule Zamykanie okna. |
| Łączenie z systemem zewnętrznym (konfiguracja żądania) | { "actionResponse": { "type": "REQUEST_CONFIG", "url": "..." } } Więcej informacji znajdziesz w artykule Łączenie się z systemem zewnętrznym (aplikacje do obsługi czatu, które nie są dodatkami). |
{ "basic_authorization_prompt": { "authorization_url": "...", "resource": "..." } } Więcej informacji znajdziesz w artykule Łączenie aplikacji do obsługi czatu z innymi usługami i narzędziami. |
| 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 Odczytywanie danych z formularza wprowadzonych przez użytkowników na kartach. |
Obsługa interakcji z kartami w wiadomościach utworzonych przed konwersją
Gdy przekonwertujesz aplikację do obsługi czatu HTTP, która nie jest dodatkiem, na dodatek do Google Workspace, interakcje z kartami w wiadomościach utworzonych przed konwersją będą wymagać specjalnej obsługi. Dodatki używają pełnego adresu URL HTTP dla funkcji action.function karty, a aplikacje do obsługi czatu, które nie są dodatkami, używają nazwy funkcji.
W tabeli poniżej znajdziesz podsumowanie tych różnic.
| Aplikacja Google Chat, która nie jest dodatkiem | Dodatek do Google Workspace, który rozszerza Google Chat | |
|---|---|---|
| Konfiguracja | W konsoli Google Cloud możesz skonfigurować jeden punkt końcowy dla wszystkich zdarzeń. Podczas wdrażania interakcji z kartami 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 interaktywnych okien dialogowych. { "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 wdrażania interakcji z kartami 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 interaktywnych okien dialogowych. { "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 z następującym działaniem:
{
"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 wielokrotnego wyboru
Jeśli użytkownik wejdzie 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 przypadku aktywatorów HTTP włączysz opcję Używaj wspólnego adresu URL punktu końcowego HTTP dla wszystkich aktywatorów, wspólny adres URL będzie też używany w przypadku zdarzeń Kliknięto przycisk.
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.
- Weryfikacja aplikacji do Google Chat w protokole HTTP, które nie są dodatkami: Weryfikowanie próśb z Google Chat
- Weryfikacja HTTP dodatku do Google Workspace: Weryfikowanie próśb od Google
Najważniejsze różnice w weryfikacji żądań to:
| Typ treści | Obsługiwani odbiorcy | E-mail konta usługi |
|---|---|---|
| Aplikacja Google Chat, która nie jest dodatkiem | 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 do Google Workspace znajdziesz w sekcji Konwertowanie na dodatki do Google Workspace na stronie konfiguracji interfejsu Google Chat API w konsoli Google Cloud.
Aby weryfikować żądania w ulepszonym dodatku do Google Workspace:
- Jeśli używasz funkcji Cloud Run, przyznaj rolę
roles/cloudfunctions.invokerkontu usługi każdego dodatku. Więcej informacji znajdziesz w artykule Autoryzowanie dostępu za pomocą uprawnień. - Zaktualizuj kod weryfikacji tokena, aby używać adresu e-mail konta usługi dodatku Google Workspace do weryfikowania podpisu tokena okaziciela. Zapoznaj się z sekcją Weryfikowanie żądań od Google.