Tworzenie dodatku do Google Workspace przy użyciu Apps Script

W tym krótkim wprowadzeniu tworzymy prosty dodatek do Google Workspace, który pokazuje, strony główne, reguły kontekstowe i połączenia z interfejsami API innych firm.

Dodatek tworzy treści kontekstowe i niekontekstowe w Gmailu, Kalendarzu i na Dysku. Dodatek wyświetla losowy obraz kota z tekstu nakładanego na obraz. Tekst jest statyczny w przypadku stron głównych lub pochodzi z kontekstu aplikacji hosta dla aktywatorów kontekstowych.

Cele

  • skonfigurować środowisko,
  • Skonfiguruj skrypt.
  • Uruchom skrypt.

Wymagania wstępne

Aby korzystać z tego przykładu, musisz spełnić te wymagania wstępne:

  • Konto Google (konta Google Workspace mogą wymagają zatwierdzenia przez administratora).

  • Przeglądarka z dostępem do internetu.

  • Projekt Google Cloud.

Konfigurowanie środowiska

Otwieranie projektu Cloud w konsoli Google Cloud

Jeśli projekt Cloud nie jest jeszcze otwarty, otwórz go, którego chcesz używać. dla tego przykładu:

  1. W konsoli Google Cloud otwórz stronę Wybierz projekt.

    Wybierz projekt Cloud

  2. Wybierz projekt Google Cloud, którego chcesz użyć. Możesz też kliknąć Utwórz projekt i postępować zgodnie z instrukcjami wyświetlanymi na ekranie. Jeśli tworzysz projekt Google Cloud, konieczne może być włączenie dla niego płatności.

Dodatki do Google Workspace wymagają konfiguracji ekranu zgody. Konfiguruję ekran zgody OAuth dodatku określa, co Google wyświetlane użytkownikom.

  1. W konsoli Google Cloud otwórz menu . > Interfejsy API i Usługi > Ekran zgody OAuth.

    Otwórz ekran zgody OAuth

  2. Jako Typ użytkownika wybierz Wewnętrzny i kliknij Utwórz.
  3. Wypełnij formularz rejestracji aplikacji, a potem kliknij Zapisz i kontynuuj.

  4. Na razie możesz pominąć dodawanie zakresów i kliknąć Zapisz i kontynuuj. w przyszłości, gdy utworzysz aplikację do użytku poza swoim Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny, a następnie: dodaj zakresy autoryzacji wymagane przez aplikację.

  5. Przejrzyj podsumowanie rejestracji aplikacji. Aby wprowadzić zmiany, kliknij Edytuj. Jeśli aplikacja z rejestracji wszystko jest w porządku, kliknij Back to Dashboard (Powrót do panelu).

Konfigurowanie skryptu

Tworzenie projektu Apps Script

  1. Aby utworzyć nowy projekt Apps Script, otwórz stronę script.new.
  2. Kliknij Projekt bez tytułu.
  3. Zmień nazwę projektu Apps Script Koty i kliknij Zmień nazwę.
  4. Obok pliku Code.gs kliknij Więcej . > Zmień nazwę. Nazwij plik Common.
  5. Kliknij Dodaj plik . > Skrypt. Nazwij plik Gmail.
  6. Powtórz krok 5, aby utworzyć jeszcze 2 pliki skryptów o nazwach Calendar i Drive. Gdy skończysz, powinny być dostępne 4 osobne pliki skryptów.

  7. Zastąp zawartość każdego pliku odpowiednim kodem:

    Common.gs

      /**
 * This simple Google Workspace Add-on shows a random image of a cat in the
 * sidebar. When opened manually (the homepage card), some static text is
 * overlayed on the image, but when contextual cards are opened a new cat image
 * is shown with the text taken from that context (such as a message's subject
 * line) overlaying the image. There is also a button that updates the card with
 * a new random cat image.
 *
 * Click "File > Make a copy..." to copy the script, and "Publish > Deploy from
 * manifest > Install add-on" to install it.
 */

/**
 * The maximum number of characters that can fit in the cat image.
 */
var MAX_MESSAGE_LENGTH = 40;

/**
 * Callback for rendering the homepage card.
 * @return {CardService.Card} The card to show to the user.
 */
function onHomepage(e) {
  console.log(e);
  var hour = Number(Utilities.formatDate(new Date(), e.userTimezone.id, 'H'));
  var message;
  if (hour >= 6 && hour < 12) {
    message = 'Good morning';
  } else if (hour >= 12 && hour < 18) {
    message = 'Good afternoon';
  } else {
    message = 'Good night';
  }
  message += ' ' + e.hostApp;
  return createCatCard(message, true);
}

/**
 * Creates a card with an image of a cat, overlayed with the text.
 * @param {String} text The text to overlay on the image.
 * @param {Boolean} isHomepage True if the card created here is a homepage;
 *      false otherwise. Defaults to false.
 * @return {CardService.Card} The assembled card.
 */
function createCatCard(text, isHomepage) {
  // Explicitly set the value of isHomepage as false if null or undefined.
  if (!isHomepage) {
    isHomepage = false;
  }

  // Use the "Cat as a service" API to get the cat image. Add a "time" URL
  // parameter to act as a cache buster.
  var now = new Date();
  // Replace forward slashes in the text, as they break the CataaS API.
  var caption = text.replace(/\//g, ' ');
  var imageUrl =
      Utilities.formatString('https://cataas.com/cat/says/%s?time=%s',
          encodeURIComponent(caption), now.getTime());
  var image = CardService.newImage()
      .setImageUrl(imageUrl)
      .setAltText('Meow')

  // Create a button that changes the cat image when pressed.
  // Note: Action parameter keys and values must be strings.
  var action = CardService.newAction()
      .setFunctionName('onChangeCat')
      .setParameters({text: text, isHomepage: isHomepage.toString()});
  var button = CardService.newTextButton()
      .setText('Change cat')
      .setOnClickAction(action)
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED);
  var buttonSet = CardService.newButtonSet()
      .addButton(button);

  // Create a footer to be shown at the bottom.
  var footer = CardService.newFixedFooter()
      .setPrimaryButton(CardService.newTextButton()
          .setText('Powered by cataas.com')
          .setOpenLink(CardService.newOpenLink()
              .setUrl('https://cataas.com')));

  // Assemble the widgets and return the card.
  var section = CardService.newCardSection()
      .addWidget(image)
      .addWidget(buttonSet);
  var card = CardService.newCardBuilder()
      .addSection(section)
      .setFixedFooter(footer);

  if (!isHomepage) {
    // Create the header shown when the card is minimized,
    // but only when this card is a contextual card. Peek headers
    // are never used by non-contexual cards like homepages.
    var peekHeader = CardService.newCardHeader()
      .setTitle('Contextual Cat')
      .setImageUrl('https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png')
      .setSubtitle(text);
    card.setPeekCardHeader(peekHeader)
  }

  return card.build();
}

/**
 * Callback for the "Change cat" button.
 * @param {Object} e The event object, documented {@link
 *     https://developers.google.com/gmail/add-ons/concepts/actions#action_event_objects
 *     here}.
 * @return {CardService.ActionResponse} The action response to apply.
 */
function onChangeCat(e) {
  console.log(e);
  // Get the text that was shown in the current cat image. This was passed as a
  // parameter on the Action set for the button.
  var text = e.parameters.text;

  // The isHomepage parameter is passed as a string, so convert to a Boolean.
  var isHomepage = e.parameters.isHomepage === 'true';

  // Create a new card with the same text.
  var card = createCatCard(text, isHomepage);

  // Create an action response that instructs the add-on to replace
  // the current card with the new one.
  var navigation = CardService.newNavigation()
      .updateCard(card);
  var actionResponse = CardService.newActionResponseBuilder()
      .setNavigation(navigation);
  return actionResponse.build();
}

/**
 * Truncate a message to fit in the cat image.
 * @param {string} message The message to truncate.
 * @return {string} The truncated message.
 */
function truncate(message) {
  if (message.length > MAX_MESSAGE_LENGTH) {
    message = message.slice(0, MAX_MESSAGE_LENGTH);
    message = message.slice(0, message.lastIndexOf(' ')) + '...';
  }
  return message;
}

    Gmail.gs

      /**
 * Callback for rendering the card for a specific Gmail message.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onGmailMessage(e) {
  console.log(e);
  // Get the ID of the message the user has open.
  var messageId = e.gmail.messageId;

  // Get an access token scoped to the current message and use it for GmailApp
  // calls.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Get the subject of the email.
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getThread().getFirstMessageSubject();

  // Remove labels and prefixes.
  subject = subject
      .replace(/^([rR][eE]|[fF][wW][dD])\:\s*/, '')
      .replace(/^\[.*?\]\s*/, '');

  // If neccessary, truncate the subject to fit in the image.
  subject = truncate(subject);

  return createCatCard(subject);
}

/**
 * Callback for rendering the card for the compose action dialog.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onGmailCompose(e) {
  console.log(e);
  var header = CardService.newCardHeader()
      .setTitle('Insert cat')
      .setSubtitle('Add a custom cat image to your email message.');
  // Create text input for entering the cat's message.
  var input = CardService.newTextInput()
      .setFieldName('text')
      .setTitle('Caption')
      .setHint('What do you want the cat to say?');
  // Create a button that inserts the cat image when pressed.
  var action = CardService.newAction()
      .setFunctionName('onGmailInsertCat');
  var button = CardService.newTextButton()
      .setText('Insert cat')
      .setOnClickAction(action)
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED);
  var buttonSet = CardService.newButtonSet()
      .addButton(button);
  // Assemble the widgets and return the card.
  var section = CardService.newCardSection()
      .addWidget(input)
      .addWidget(buttonSet);
  var card = CardService.newCardBuilder()
      .setHeader(header)
      .addSection(section);
  return card.build();
}

/**
 * Callback for inserting a cat into the Gmail draft.
 * @param {Object} e The event object.
 * @return {CardService.UpdateDraftActionResponse} The draft update response.
 */
function onGmailInsertCat(e) {
  console.log(e);
  // Get the text that was entered by the user.
  var text = e.formInput.text;
  // Use the "Cat as a service" API to get the cat image. Add a "time" URL
  // parameter to act as a cache buster.
  var now = new Date();
  var imageUrl = 'https://cataas.com/cat';
  if (text) {
    // Replace forward slashes in the text, as they break the CataaS API.
    var caption = text.replace(/\//g, ' ');
    imageUrl += Utilities.formatString('/says/%s?time=%s',
        encodeURIComponent(caption), now.getTime());
  }
  var imageHtmlContent = '<img style="display: block; max-height: 300px;" src="'
      + imageUrl + '"/>';
  var response = CardService.newUpdateDraftActionResponseBuilder()
      .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
          .addUpdateContent(imageHtmlContent,CardService.ContentType.MUTABLE_HTML)
          .setUpdateType(CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
      .build();
  return response;
}

    Calendar.gs

      /**
 * Callback for rendering the card for a specific Calendar event.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onCalendarEventOpen(e) {
  console.log(e);
  var calendar = CalendarApp.getCalendarById(e.calendar.calendarId);
  // The event metadata doesn't include the event's title, so using the
  // calendar.readonly scope and fetching the event by it's ID.
  var event = calendar.getEventById(e.calendar.id);
  if (!event) {
    // This is a new event still being created.
    return createCatCard('A new event! Am I invited?');
  }
  var title = event.getTitle();
  // If necessary, truncate the title to fit in the image.
  title = truncate(title);
  return createCatCard(title);
}

    Drive.gs

      /**
 * Callback for rendering the card for specific Drive items.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onDriveItemsSelected(e) {
  console.log(e);
  var items = e.drive.selectedItems;
  // Include at most 5 items in the text.
  items = items.slice(0, 5);
  var text = items.map(function(item) {
    var title = item.title;
    // If neccessary, truncate the title to fit in the image.
    title = truncate(title);
    return title;
  }).join('\n');
  return createCatCard(text);
}

  8. Kliknij Ustawienia projektu Ikona ustawień projektu.

  9. Zaznacz pole wyboru Pokaż plik „appsscript.json”. plik manifestu.

  10. Kliknij Edytor .

  11. Otwórz plik appsscript.json i zastąp jego zawartość następującym fragmentem: a następnie kliknij Zapisz Ikona zapisania.

    appsscript.json

       {
  "timeZone": "America/New_York",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/script.locale"],
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Cats",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true,
      "homepageTrigger": {
        "runFunction": "onHomepage",
        "enabled": true
      },
      "universalActions": [{
        "label": "Learn more about Cataas",
        "openLink": "https://cataas.com"
      }]
    },
    "gmail": {
      "contextualTriggers": [{
        "unconditional": {
        },
        "onTriggerFunction": "onGmailMessage"
      }],
      "composeTrigger": {
        "selectActions": [{
          "text": "Insert cat",
          "runFunction": "onGmailCompose"
        }],
        "draftAccess": "NONE"
      }
    },
    "drive": {
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "calendar": {
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      }
    }
  }
}

Kopiuj numer projektu Cloud

  1. W konsoli Google Cloud otwórz menu . &gt; Administracja Administracja &gt; Ustawienia.

    Otwórz stronę Uprawnienia Ustawienia administratora

  2. Skopiuj wartość z pola Numer projektu.

Ustawianie projektu Cloud w projekcie Apps Script

  1. W projekcie Apps Script kliknij Ustawienia projektu Ikona ustawień projektu.
  2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
  3. W polu Numer projektu GCP wklej numer projektu Google Cloud.
  4. Kliknij Set project (Ustaw projekt).

Instalowanie wdrożenia testowego

  1. W projekcie Apps Script kliknij Edytor.
  2. Kliknij Wdróż &gt; Testuj wdrożenia.
  3. Kliknij Zainstaluj &gt; Gotowe.

Uruchamianie skryptu

  1. Otwórz Gmail.
  2. Aby otworzyć dodatek, w prawym panelu bocznym kliknij Koty .
  3. Jeśli pojawi się taka prośba, autoryzuj dodatek.
  4. Dodatek wyświetla obraz i tekst z kotem. Aby zmienić kliknij Zmień kota.
  5. Jeśli otworzysz e-maila, gdy dodatek jest otwarty, obraz zostanie odświeżony, a tekst e-maila zmieni się na wiersz tematu e-maila (jeśli jest za długa, zostanie skrócona).

Podobne funkcje znajdziesz w Kalendarzu i Dysk. Nie musisz ponownie autoryzować aby używać go w tych aplikacjach.

Dalsze kroki