Tworzenie aplikacji do obsługi czatu za pomocą Apps Script

Apps Script to jeden z najszybszych sposobów tworzenia aplikacji do obsługi czatu w Google Chat.

• Aplikację możesz uruchomić w zaledwie kilka minut bezpośrednio w przeglądarce.
• Nie musisz martwić się o uruchamianie serwerów i zarządzanie nimi, dbanie o koszty operacyjne i operacyjne, a nawet pobieranie i konfigurowanie środowiska programistycznego.
• Wywołanie interfejsów API Google – a zwłaszcza interfejsu APIGoogle Workspace – jest bardzo proste, ponieważ w przypadku Apps Script nie trzeba niczego pobierać ani konfigurować, a uwierzytelnianie jest obsługiwane automatycznie, a wywołania interfejsu Google API niczym nie różnią się od wywołań funkcji natywnych.

Ten przewodnik wyjaśnia, jak utworzyć i zarejestrować aplikację za pomocą Apps Script.

Pierwsze kroki

W tej sekcji dowiesz się, jak szybko utworzyć aplikację do obsługi czatu za pomocą Apps Script.

Krok 1. Skopiuj szablon Apps Script

Najprostszym sposobem na rozpoczęcie tworzenia aplikacji Apps Script jest użycie szablonu Google Chat. Spowoduje to utworzenie projektu Apps Script z potrzebnymi Ci metodami. Następnie wypełnij metody wymagane do wdrożenia logiki aplikacji lub jej integracji z utworzoną przez Ciebie aplikacją. Poniżej znajduje się przykład szablonu wypełnionego w przypadku prostej aplikacji.

Jeśli tworzysz projekt ręcznie – bez użycia szablonu czatu – musisz też edytować plik manifestu Apps Script.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

Krok 2. Edytuj funkcję onMessage

Domyślnie funkcja onMessage w szablonie zwraca obiekt Message zawierający tekst oraz prostą kartę. Możesz edytować tę funkcję, aby zwracała tekst lub określone widżety kart.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Krok 3. Uzyskaj identyfikator wdrożenia

Zanim zarejestrujesz aplikację, musisz pobrać identyfikator wdrożenia tej aplikacji.

1. Kliknij Wdróż > Nowe wdrożenie.
2. W sekcji Wybierz typ kliknij Dodatek.
3. Wypełnij pola opcji i kliknij Wdróż.
4. W sekcji „Identyfikator wdrożenia” kliknij Kopiuj.

Ostrzeżenie: możesz użyć wdrożenia HEAD do prostych testów podczas programowania. Aplikacje z wdrożeniami HEAD nie mogą być jednak udostępniane w całej domenie i użytkownicy nie mogą z nich korzystać, chyba że mają dostęp do odczytu Twojego skryptu. Dlatego do ogólnego testowania i publikowania musisz utworzyć wdrożenie wersji.

W przewodniku po zarządzaniu wersjami znajdziesz więcej informacji o zalecanych metodach korzystania z identyfikatorów wdrożenia.

Krok 4. Zarejestruj aplikację

Możesz zarejestrować swoją aplikację w Google Cloud Console. Na ekranie rejestracji aplikacji musisz wpisać jej nazwę, adres URL awatara i opis. Na potrzeby testów możesz włączyć opcję „Wiadomość może być wysyłana bezpośrednio” i „Aplikacja działa w pokojach z wieloma użytkownikami”. W ustawieniach połączenia wybierz Apps Script i wklej identyfikator wdrożenia skopiowany w poprzednim kroku.

Aby zarejestrować aplikację Apps Script, musisz być właścicielem lub mieć uprawnienia do edycji tego projektu.

Krok 5. Przetestuj aplikację

Aby przetestować aplikację, możesz rozpocząć w niej czat lub @wzmiankę o niej w Pokoju. Odpowiadając na wiadomość, otrzymasz ją w kroku 2. Znakomicie.

Pojęcia w Apps Script

Wydarzenia

Apps Script obsługuje kilka funkcji modułu obsługi zdarzeń, które aplikacja może zaimplementować. Każda funkcja obsługuje inny typ zdarzenia. Każda funkcja otrzymuje pojedynczy argument e, który jest obiektem Event.

onAddToSpace(e)

Ta funkcja jest wykonywana, gdy aplikacja zostanie dodana do pokoju. Aplikację możesz dodać bezpośrednio do pokoju lub za pomocą @wzmianki. W drugim przypadku zdarzenie e będzie też miało właściwość message. Ta funkcja powinna zwracać obiekt Message, który jest zwykle komunikatem powitalnym informującym użytkowników o aplikacji lub odpowiedzi na @wzmiankę.

onMessage(e)

Ta funkcja jest wywoływana, gdy Twoja aplikacja jest już w pokoju, a użytkownik @wspomnia o niej. Powinien zwracać obiekt Message zawierający odpowiedź aplikacji.

onRemoveFromSpace(e)

Ta funkcja jest wywoływana, gdy użytkownik usunie Twoją aplikację z listy czatu lub z pokoju. Wartość zwrócona przez tę funkcję jest ignorowana, ponieważ Twoja aplikacja została usunięta i nie można opublikować w niej więcej wiadomości.

W tym przykładzie zaimplementowano onAddToSpace i onRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Pamiętaj, że e.space.displayName może nie być obecny na czacie.

Karty interaktywne

Podobnie jak inne aplikacje, aplikacje Apps Script mogą wyświetlać interaktywne karty. Aby dowiedzieć się, jak tworzyć karty interaktywne, zajrzyj do dokumentacji kart interaktywnych. Główna różnica w przypadku aplikacji Apps Script polega na tym, że mogą określić konkretną metodę, która ma być wywoływana po wywołaniu zdarzenia onClick przy użyciu par klucz-wartość „action.actionMethodName” i „action.params”.

Upoważnienie

Aplikacje Apps Script, które mają dostęp do chronionych zasobów, muszą prosić użytkowników o przyznanie Ci tego dostępu przy pierwszym uruchomieniu. Nie musisz nic robić, ale pamiętaj, że użytkownicy przy pierwszym użyciu aplikacji mogą zobaczyć okno autoryzacji.

Skrypt Apps Script obsługuje autoryzację na poziomie skryptu. Aplikacje, które wymagają autoryzacji, nie mogą wykonywać żadnych czynności, dopóki użytkownik nie autoryzuje aplikacji. Jeśli chcesz, aby Twoja aplikacja powitalna wyświetlała się w sytuacji, gdy nie została autoryzowana, a aplikacja jest bezpośrednio dodana do pokoju, możesz określić wiadomość zastępczą w pliku manifestu. Jeśli aplikacja wymaga logiki inicjowania, może być konieczne zduplikowanie tej reguły w działaniu onMessage. Na przykład:

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Wiadomości asynchroniczne

Niektóre aplikacje mogą wysyłać wiadomości do Google Chat na podstawie aktywatora zewnętrznego, np. aktywatora na podstawie czasu w Apps Script.

W tym przypadku planujemy natywne zintegrowanie interfejsu Google Chat API z Apps Script. Tymczasem jedynym sposobem na osiągnięcie tego celu jest zastosowanie zewnętrznego interfejsu HTTP API (patrz dokumentacja). Wymaga to użycia konta usługi Cloud (zobacz dokumentację) za pomocą biblioteki OAuth2 dla Apps Script.

Poniższa przykładowa aplikacja, która publikuje wiadomość co minutę do każdego pokoju:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = '[e-mail]';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Plik manifestu

Poniżej znajdziesz przykładowy plik manifestu Apps Script, który musi towarzyszyć skryptowi.

Jeśli projekt nie został uruchomiony z poziomu szablonu czatu, musisz edytować plik manifestu, aby dodać do niego obiekt "chat": {}.

W pliku manifestu ustaw środowisko wykonawcze na Rhino: "runtimeVersion": "DEPRECATED_ES5". Aplikacje do obsługi czatu nie obsługują w pełni środowiska wykonawczego Apps Script w wersji 8, więc jeśli określisz właściwość "runtimeVersion": "V8", aplikacja Google Chat może wyświetlać błędy przez pomyłkę. Na przykład struktura odpowiedzi JSON może się zmieniać w nieprzewidywalny sposób w przypadku aplikacji do obsługi czatu utworzonych w środowisku wykonawczym V8.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

Przed autoryzowaniem aplikacji użytkownik może dodać ją do pokoju. W tym przypadku aplikacja nie może odpowiedzieć na zdarzenie „Dodaj do pokoju”. W takim przypadku możesz podać w polu addToSpaceFallbackMessage wiadomość powitalną, która ma się wyświetlać.

Plik manifestu ma nazwę appsscript.json i jest częścią Twojego projektu Apps Script. Aby wyświetlić plik manifestu w edytorze Apps Script, wybierz Widok > Pokaż plik manifestu.