Wyjazd na wakacje z aplikacją Google Chat

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 apps-script/attendance-chat-app zawierają 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 (google-chat-samples), który zawiera po 1 folderze dla każdego kroku tego modułu pod apps-script/attendance-chat-app.

Klonowanie repozytorium GitHub

Aby sklonować repozytorium GitHub na potrzeby tego laboratorium, wykonaj to polecenie:

git clone https://github.com/googleworkspace/google-chat-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 stronę script.new.
Kliknij Projekt bez nazwy.
Zmień nazwę skryptu na Attendance Chat app i kliknij Rename (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 następujący sposób:

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 definiujesz onAddToSpace() 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 definiujesz onRemoveFromSpace() 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 Edytujący .
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 Google Chat, musisz utworzyć projekt Google Cloud, włączyć i skonfigurować interfejs Chat API oraz opublikować aplikację do obsługi Google Chat 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 do sprawdzania obecności na czacie.
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 otwórz 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ę do czatu jako dodatek do Workspace i kliknij WYŁĄCZ, aby potwierdzić.
W polu Nazwa aplikacji wpisz Aplikacja do sprawdzania obecności na czacie.
W polu URL awatara wpisz https://goo.gl/kv2ENA.
W polu Description (Opis) wpisz Aplikacja do obsługi czatu w ćwiczeniu Apps Script.
W sekcji Funkcje wybierz Otrzymywanie wiadomości bezpośrednich.
W sekcji Ustawienia połączenia wybierz Projekt Apps Script i wklej identyfikator wdrożenia skryptu w polu tekstowym.
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 AKTYWNA – 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 do Google Chat, klikając Rozpocznij czat > Znajdź aplikacje.
Na stronie Znajdź aplikacje wyszukaj aplikację do obsługi obecności w Google Chat.
Obok pozycji Aplikacja do obsługi czatu podczas spotkania kliknij Dodaj> Chat.

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 Google Chat prostą odpowiedzią tekstową. W tym kroku zaktualizujesz aplikację, aby odpowiadała kartami.

Odpowiedzi na kartach

Google Chat obsługuje używanie kart w odpowiedziach. Karty to wizualne kontenery, 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, w tym nagłówkiem, widżetem klucz/wartość, widżetem obrazu i przyciskiem tekstowym.

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

Funkcja onMessage() dodana w tym kroku 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 czatu 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ść od 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 niestandardowe działanie.

Karty interaktywne

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 z Google Chat i zwrócić 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 Google Cloud Platform API Dashboard (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ź na czas nieobecności w Gmailu i dodawać całodniowe wydarzenia do Kalendarza.

Omówione zagadnienia

utworzyć i opublikować aplikację Google Chat za pomocą Apps Script,
odpowiadać na wiadomości użytkowników prostą odpowiedzią;
interakcji z innymi usługami Google Workspace w imieniu użytkownika za pomocą aplikacji Chat,

Wyjazd na wakacje z aplikacją Google Chat Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

1. Wprowadzenie

Czego się nauczysz

Czego potrzebujesz

2. Pobieranie przykładowego kodu

Pobieranie kodu

Klonowanie repozytorium GitHub

3. Tworzenie modułów obsługi zdarzeń Google Chat

Tworzenie projektu Apps Script

Wydarzenia w Google Chat

Code.gs

4. Publikowanie i testowanie aplikacji Google Chat

Aktualizowanie pliku manifestu skryptu

appsscript.json

Tworzenie projektu Google Cloud

Publikowanie aplikacji w Google Chat

Testowanie aplikacji Google Chat

5. Określanie odpowiedzi w formacie karty

Odpowiedzi na kartach

Code.gs

Testowanie aplikacji Google Chat

6. Reagowanie na kliknięcia przycisków na kartach

Karty interaktywne

Code.gs

Code.gs

Code.gs

Testowanie aplikacji Google Chat

7. Gratulacje!

Omówione zagadnienia

Więcej informacji

Wyjazd na wakacje z aplikacją Google Chat