1. Wprowadzenie
Aplikacje Google Chat udostępniają usługi i zasoby bezpośrednio w Google Chat, dzięki czemu użytkownicy mogą uzyskiwać informacje i podejmować działania bez opuszczania rozmowy.
W tym laboratorium dowiesz się, jak utworzyć aplikację do obsługi czatu „Attendance Chat app”, która ustawia automatyczne odpowiedzi w Gmailu i planuje spotkania w Kalendarzu Google. Dzięki utworzeniu aplikacji do sprawdzania obecności w Google Apps Script możesz łatwo korzystać z innych usług Google, takich jak Dysk, Gmail, Kalendarz, Dokumenty, Arkusze i wiele innych.
Czego się nauczysz
- Dodawanie modułów obsługi zdarzeń wywoływanych w Chat
- Jak analizować obiekty zdarzeń wysyłane z czatu
- Jak odpowiadać na czacie za pomocą odpowiedzi w formacie karty
- Definiowanie działań niestandardowych i reagowanie na nie w przypadku kliknięć przycisków na kartach
Czego potrzebujesz
- Dostęp do internetu i przeglądarki.
- Konto Google Workspace z dostępem do Google Chat.
- Podstawowa znajomość JavaScriptu – Google Apps Script obsługuje tylko JavaScript.
2. Pobieranie przykładowego kodu
Aby zobaczyć kod każdego kroku w tym przykładzie, możesz pobrać plik ZIP lub sklonować repozytorium GitHub.
Foldery step-NN w solutions/attendance-chat-app zawierają oczekiwany stan końcowy każdego kroku tego modułu. Są one podane w celach informacyjnych.
Pobieranie kodu
Aby pobrać kod do tego ćwiczenia, kliknij ten przycisk:
Rozpakuj pobrany plik ZIP. Spowoduje to rozpakowanie folderu głównego (apps-script-samples), który zawiera po 1 folderze dla każdego kroku tego modułu pod solutions/attendance-chat-app.
Klonowanie repozytorium GitHub
Aby sklonować repozytorium GitHub na potrzeby tego laboratorium, wykonaj to polecenie:
git clone https://github.com/googleworkspace/apps-script-samples
3. Tworzenie modułów obsługi zdarzeń Google Chat
Tworzenie projektu Apps Script
Aby utworzyć projekt Apps Script, wykonaj te czynności:
- Otwórz script.new.
- Kliknij Projekt bez nazwy.
- Zmień nazwę skryptu na Aplikacja do czatu dotyczącego obecności i kliknij Zmień nazwę.
Wydarzenia w Google Chat
Większość interakcji Apps Script z Google Chat jest oparta na zdarzeniach. Interakcja między użytkownikiem, aplikacją Chat i Google Chat zwykle przebiega w tej kolejności:
- Użytkownik inicjuje działanie, np. dodaje aplikację do obsługi czatu do pokoju, rozpoczyna rozmowę na czacie z aplikacją do obsługi czatu lub usuwa aplikację do obsługi czatu z pokoju.
- Działanie wywołuje zdarzenie skierowane do aplikacji Google Chat w Google Chat.
- Chat wywołuje odpowiedni moduł obsługi zdarzeń zdefiniowany w skrypcie aplikacji Chat.
Google Chat wywołuje 4 zdarzenia, których może nasłuchiwać Twoja aplikacja:
ADDED_TO_SPACE: to zdarzenie występuje, gdy użytkownik dodaje aplikację do obsługi czatu do pokoju lub wiadomości bezpośredniej. W Apps Script definiujeszonAddToSpace()funkcję do obsługi tego zdarzenia.REMOVED_FROM_SPACE: to zdarzenie występuje, gdy użytkownik usunie aplikację Google Chat z pokoju lub rozmowy na czacie. To zdarzenie nie wysyła odpowiedzi do Google Chat. W Apps Script definiujeszonRemoveFromSpace()funkcję do obsługi tego zdarzenia.MESSAGE: to zdarzenie występuje, gdy użytkownik wysyła wiadomość do aplikacji Chat bezpośrednio na czacie lub jako @wzmiankę w pokoju. W Apps Script definiujesz funkcjęonMessage(), która odpowiada na to zdarzenie.CARD_CLICKED: to zdarzenie występuje, gdy użytkownik kliknie przycisk z przypisanym do niego działaniem niestandardowym. W Apps Script definiujesz funkcjęonCardClick(), która odpowiada na to zdarzenie.
Zastąp zawartość pliku Code.gs tym kodem, który definiuje obsługę zdarzeń ADDED_TO_SPACE i REMOVE_FROM_SPACE. (Obsługę zdarzeń MESSAGE i CARD_CLICKED dodasz w dalszej części tego samouczka).
Code.gs
/**
* Responds to an ADDED_TO_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onAddToSpace(event) {
console.info(event);
var message = 'Thank you for adding me to ';
if (event.space.type === 'DM') {
message += 'a DM, ' + event.user.displayName + '!';
} else {
message += event.space.displayName;
}
return { text: message };
}
/**
* Responds to a REMOVED_FROM_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onRemoveFromSpace(event) {
console.info(event);
console.log('Chat app removed from ', event.space.name);
}
4. Publikowanie i testowanie aplikacji Google Chat
Aktualizowanie pliku manifestu skryptu
Zanim opublikujesz aplikację w Google Chat, musisz zaktualizować plik manifestu skryptu.
- Kliknij Ustawienia projektu
. - Zaznacz pole wyboru Wyświetlaj plik manifestu „appsscript.json” w edytorze.
- Kliknij Edytor
. - Kliknij plik
appsscript.json. - Dodaj do pliku manifestu wiersz
"chat": {}.
Plik manifestu powinien wyglądać podobnie do tego przykładu.
appsscript.json
{
"timeZone": "America/Los_Angeles",
"dependencies": {
},
"chat": {}
}
Tworzenie projektu Google Cloud
Zanim uruchomisz i przetestujesz aplikację do obsługi czatu, musisz utworzyć projekt Google Cloud, włączyć i skonfigurować interfejs Chat API oraz opublikować aplikację do obsługi czatu w organizacji Google Workspace.
- W konsoli Google Cloud kliknij Menu
> Administracja > Utwórz projekt. - W polu Nazwa projektu wpisz nazwę opisową.
- W razie potrzeby wybierz Organizację i Konto rozliczeniowe.
- Kliknij Utwórz.
- Gdy tworzenie projektu zostanie ukończone, w prawym górnym rogu strony pojawi się powiadomienie. Kliknij wpis Utwórz projekt: <nazwa projektu>, aby otworzyć projekt.
- Kliknij Menu > Interfejsy API i usługi > Dane logowania.
- Kliknij Ekran zgody OAuth.
- W polu Nazwa aplikacji wpisz Aplikacja na czacie do sprawdzania obecności.
- W razie potrzeby podaj adres e-mail pomocy dla użytkowników i informacje kontaktowe dewelopera.
- Kliknij Zapisz i kontynuuj.
- Kliknij Ustawienia i narzędzia
> Ustawienia projektu. - Skopiuj Numer projektu.
- Wróć do edytora Apps Script i kliknij Ustawienia projektu .
- W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
- Kliknij Numer projektu GCP i wpisz numer projektu.
- Kliknij Ustaw projekt.
Publikowanie aplikacji w Google Chat
Aby opublikować aplikację Google Chat w Google Chat:
- W edytorze Apps Script kliknij Wdróż > Nowe wdrożenie.
- Obok opcji Wybierz typ kliknij Włącz typy wdrożenia .
- Wybierz Dodatek i kliknij Wdróż.
- Skopiuj identyfikator wdrożenia i kliknij Gotowe.
- W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Biblioteka.
- Wyszukaj Google Chat API. Wybierz interfejs API z listy wyników.
- Na stronie interfejsu Google Chat API kliknij Włącz.
- Po włączeniu interfejsu API kliknij Konfiguracja. Ignoruj wszystkie wiadomości z prośbą o utworzenie danych logowania.
- Na stronie Konfiguracja wykonaj te czynności:
- Odznacz opcję Utwórz tę aplikację Google Chat jako dodatek do Workspace i kliknij WYŁĄCZ, aby potwierdzić.
- W polu Nazwa aplikacji wpisz Aplikacja na czacie do sprawdzania obecności.
- W polu URL awatara wpisz https://goo.gl/kv2ENA.
- W polu Description (Opis) wpisz Apps Script codelab Chat app (Aplikacja do czatu w ramach ćwiczeń z programowania w Apps Script).
- W sekcji Funkcje wybierz Otrzymywanie wiadomości bezpośrednich.
- W sekcji Ustawienia połączenia wybierz Projekt Apps Script i wklej w polu tekstowym identyfikator wdrożenia skryptu.
- W sekcji Uprawnienia kliknij Określeni użytkownicy i grupy w Twojej domenie. W polu tekstowym pod menu rozwijanym wpisz adres e-mail powiązany z Twoją organizacją Google Workspace.
- Kliknij Zapisz.
Po zapisaniu zmian sprawdź, czy na stronie interfejsu Google Chat API w sekcji Stan aplikacji widnieje stan NA ŻYWO – dostępna dla użytkowników.
Testowanie aplikacji Google Chat
Aby przetestować aplikację w Google Chat:
- Otwórz Google Chat.
- Wyślij nową wiadomość bezpośrednią do aplikacji Chat, klikając Rozpocznij czat
> Znajdź aplikacje. - Na stronie Znajdź aplikacje wyszukaj aplikację do czatu dotyczącą obecności.
- Obok pozycji Aplikacja do czatu na potrzeby obecności kliknij Dodaj> Czat.
Po otwarciu wątku czatu powinna pojawić się wiadomość z aplikacji Google Chat z podziękowaniem za dodanie jej do czatu, jak pokazano na poniższym obrazie.
5. Określanie odpowiedzi w formacie karty
W poprzednim kroku aplikacja odpowiadała na zdarzenia w Google Chat prostą odpowiedzią tekstową. W tym kroku zaktualizujesz aplikację, aby odpowiadała za pomocą kart.
Odpowiedzi na kartach
Google Chat obsługuje używanie kart w odpowiedziach. Karty to kontenery wizualne, które umożliwiają grupowanie zestawów widżetów interfejsu. Karty mogą wyświetlać nagłówki, akapity tekstu, zestawy przycisków, obrazy i tekst w formacie klucz-wartość. Aplikacja może zdefiniować w odpowiedzi JSON do Google Chat co najmniej 1 kartę, która następnie zostanie przetłumaczona na odpowiednie elementy interfejsu.
Obraz poniżej przedstawia odpowiedź w formie karty z 3 sekcjami, które zawierają nagłówek, widżet klucz/wartość, widżet obrazu i przycisk tekstowy.
Aby odpowiadać na wiadomości użytkowników za pomocą odpowiedzi w formie karty, dodaj ten kod do pliku Code.gs aplikacji do obsługi czatu.
Code.gs
const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
header: {
title : 'Attendance Chat app',
subtitle : 'Log your vacation time',
imageUrl : DEFAULT_IMAGE_URL
}
};
/**
* Creates a card-formatted response.
* @param {object} widgets the UI components to send
* @return {object} JSON-formatted response
*/
function createCardResponse(widgets) {
return {
cards: [HEADER, {
sections: [{
widgets: widgets
}]
}]
};
}
/**
* Responds to a MESSAGE event triggered
* in Google Chat.
*
* @param event the event object from Google Chat
* @return JSON-formatted response
*/
function onMessage(event) {
const userMessage = event.message.text;
const widgets = [{
"textParagraph": {
"text": "You said: " + userMessage
}
}];
return createCardResponse(widgets);
}
Dodana w tym kroku funkcja onMessage() odczytuje oryginalną wiadomość użytkownika i tworzy odpowiedź w postaci prostego widżetu TextParagragh. Funkcja onMessage() wywołuje następnie funkcję createCardResponse(), która umieszcza widżet TextParagraph w sekcji pojedynczej karty. Aplikacja do obsługi czatu zwraca do Google Chat obiekt JavaScript utworzony na podstawie odpowiedzi karty.
Testowanie aplikacji Google Chat
Aby przetestować tę aplikację, wróć do wiadomości na czacie z nią w Google Chat i wpisz wiadomość (dowolną).
Zwróć uwagę, że moduł obsługi zdarzeń onMessage() analizuje obiekt zdarzenia przekazany przez Google Chat, aby wyodrębnić oryginalną wiadomość użytkownika. Możesz też uzyskać inne informacje o zdarzeniu, w tym nazwę użytkownika, który je zainicjował, jego adres e-mail, nazwę przestrzeni, w której wystąpiło zdarzenie, i wiele innych.
Więcej informacji o strukturze obiektów zdarzeń wysyłanych przez Google Chat znajdziesz w materiałach referencyjnych dotyczących formatów zdarzeń.
6. Reagowanie na kliknięcia przycisków na kartach
W poprzednim kroku aplikacja Google Chat odpowiedziała na wiadomość użytkownika – zdarzenie MESSAGE – prostą kartą zawierającą widżet TextParagragh. W tym kroku utworzysz odpowiedź zawierającą przyciski, z których każdy ma zdefiniowane działanie niestandardowe.
Interaktywne karty
Odpowiedzi w formie kart mogą zawierać 2 typy przycisków: widżety przycisków tekstowych, które wyświetlają przyciski zawierające tylko tekst, oraz widżety przycisków z obrazem, które wyświetlają przycisk z prostą ikoną lub obrazem bez tekstu. Widżety TextButton i ImageButton obsługują jeden z 2 onClick zachowań (zdefiniowanych w odpowiedzi JSON wysyłanej z powrotem do Google Chat): openLink lub action. Jak sama nazwa wskazuje, openLink otwiera określony link w nowej karcie przeglądarki.
Obiekt action określa niestandardowe działanie, które ma wykonać przycisk. W obiekcie działania możesz określić kilka dowolnych wartości, w tym unikalny actionMethodName i zestaw par klucz / wartość.
Określenie obiektu action dla przycisku powoduje utworzenie karty interaktywnej. Gdy użytkownik kliknie przycisk w wiadomości, Google Chat wywoła zdarzenie CARD_CLICKED i wyśle żądanie z powrotem do aplikacji, która wysłała pierwotną wiadomość. Aplikacja musi następnie obsłużyć zdarzenie wywołane przez Google Chat i odesłać odpowiedź do pokoju.
Zastąp funkcję onMessage() w pliku Code.gs tym kodem. Ten kod tworzy 2 przyciski: Ustaw nieobecność w Gmailu i Zablokuj dzień w Kalendarzu na karcie wysłanej do Google Chat.
Code.gs
const REASON = {
SICK: 'Out sick',
OTHER: 'Out of office'
};
/**
* Responds to a MESSAGE event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
*/
function onMessage(event) {
console.info(event);
const reason = REASON.OTHER;
const name = event.user.displayName;
const userMessage = event.message.text;
// If the user said that they were 'sick', adjust the image in the
// header sent in response.
if (userMessage.indexOf('sick') > -1) {
// Hospital material icon
HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
reason = REASON.SICK;
} else if (userMessage.indexOf('vacation') > -1) {
// Spa material icon
HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
}
const widgets = [{
textParagraph: {
text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
}
}, {
buttons: [{
textButton: {
text: 'Set vacation in Gmail',
onClick: {
action: {
actionMethodName: 'turnOnAutoResponder',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}, {
textButton: {
text: 'Block out day in Calendar',
onClick: {
action: {
actionMethodName: 'blockOutCalendar',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}]
}];
return createCardResponse(widgets);
}
Aby obsługiwać zdarzenie CARD_CLICKED, musisz dodać funkcję onCardClick() do skryptu aplikacji do obsługi Google Chat. Dodaj ten kod, który definiuje funkcję onCardClick() Code.gs.
Code.gs
/**
* Responds to a CARD_CLICKED event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onCardClick(event) {
console.info(event);
let message = '';
const reason = event.action.parameters[0].value;
if (event.action.actionMethodName == 'turnOnAutoResponder') {
turnOnAutoResponder(reason);
message = 'Turned on vacation settings.';
} else if (event.action.actionMethodName == 'blockOutCalendar') {
blockOutCalendar(reason);
message = 'Blocked out your calendar for the day.';
} else {
message = "I'm sorry; I'm not sure which button you clicked.";
}
return { text: message };
}
W odpowiedzi na kliknięcia użytkownika aplikacja do obsługi czatu wykonuje jedną z 2 czynności: ustawia automatyczną odpowiedź w Gmailu na wiadomość „poza biurem” lub planuje całodzienne spotkanie w Kalendarzu użytkownika. Aby wykonać te zadania, aplikacja wywołuje zaawansowaną usługę Gmail i usługę Kalendarz.
Aby zintegrować aplikację Chat z Gmailem i Kalendarzem, dodaj do skryptu poniższy kod.
Code.gs
const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
* Turns on the user's vacation response for today in Gmail.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function turnOnAutoResponder(reason) {
let currentTime = (new Date()).getTime();
Gmail.Users.Settings.updateVacation({
enableAutoReply: true,
responseSubject: reason,
responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
restrictToContacts: true,
restrictToDomain: true,
startTime: currentTime,
endTime: currentTime + ONE_DAY_MILLIS
}, 'me');
}
/**
* Places an all-day meeting on the user's Calendar.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function blockOutCalendar(reason) {
CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}
Na koniec musisz włączyć w projekcie usługę zaawansowaną Gmail. Aby włączyć interfejs Gmail API:
- W edytorze Apps Script obok pozycji Usługi kliknij Dodaj usługę .
- Kliknij Gmail API.
- Kliknij Panel interfejsów API Google Cloud Platform, aby otworzyć konsolę Google Cloud.
- Kliknij Włącz interfejsy API i usługi.
- Wyszukaj Gmail API i kliknij Gmail API.
- Na stronie interfejsu Gmail API kliknij Włącz.
Testowanie aplikacji Google Chat
Aby przetestować tę wersję aplikacji Chat, otwórz wiadomość bezpośrednią, którą rozpoczęto w poprzednich krokach w Google Chat, i wpisz Jadę na wakacje. Aplikacja powinna odpowiedzieć kartą podobną do tej na obrazie poniżej.
Uwaga: jeśli pojawi się prośba o przyznanie dostępu do aplikacji, może być konieczne ponowne wpisanie wiadomości.
7. Gratulacje!
Aplikacja Chat może teraz odpowiadać na wiadomości użytkowników, ustawiać automatyczną odpowiedź w Gmailu i umieszczać całodniowe wydarzenia w Kalendarzu.
Omówione zagadnienia
- utworzyć i opublikować aplikację Google Chat za pomocą Apps Script,
- odpowiadać na wiadomości użytkowników prostą odpowiedzią;
- wchodzić w interakcje z innymi usługami Google Workspace w imieniu użytkownika za pomocą aplikacji Chat,