Kurzanleitung: Google Workspace-Add-on für Cats

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

 l10n-placeholder7=

Führen Sie die Schritte aus, die im Folgenden auf dieser Seite beschrieben werden. In etwa 10 Minuten können Sie ein Google Workspace Add-on erstellen. In diesem Beispiel-Add-on werden einige Funktionen vonGoogle Workspace Add-ons demonstriert, z. B. Startseiten, kontextabhängige Trigger und die Verbindung mit APIs von Drittanbietern.

Mit diesem Add-on werden kontext- und nicht kontextbezogene Seitenleisten in Gmail, Google Kalender und Google Drive erstellt. Die Seitenleiste zeigt ein zufälliges Bild einer Katze, die von Text überlagert wird. Der Text ist entweder statisch (für Startseiten) oder stammt aus dem Kontext der Hostanwendung (für kontextbezogene Trigger).

In den folgenden Schritten wird beschrieben, wie Sie dieses Add-on selbst erstellen:




Schritt 1: Skriptprojekt erstellen

Erstellen Sie zuerst ein neues Skriptprojekt und füllen Sie es mit dem Add-on-Code aus:

  1. Erstellen Sie ein neues eigenständiges Apps Script-Projekt.
  2. Klicken Sie links oben auf Unbenanntes Projekt.
  3. Benennen Sie das Apps Script-Projekt in Cats um und klicken Sie auf Umbenennen.
  4. Klicken Sie links neben „Code.gs“ auf das Dreipunkt-Menü > Umbenennen.
  5. Benennen Sie die Datei „&codet;“ in Common um und drücken Sie die Eingabetaste.
  6. Klicken Sie oben neben „Dateien“ auf „Datei hinzufügen“ > Skript.
  7. Geben Sie den neuen Dateinamen Gmail ein und drücken Sie die Eingabetaste.
  8. Wiederholen Sie die obigen Schritte, um eine weitere Skriptdatei mit dem Namen Google Kalender und dann noch einmal eine Datei mit dem Namen Drive zu erstellen. Wenn Sie fertig sind, sollten Sie vier separate Skriptdateien haben.
  9. Ersetzen Sie den Inhalt der einzelnen Dateien durch den folgenden Inhalt:

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

    Kalender.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 neccessary, truncate the title to fit in the image.
      title = truncate(title);
      return createCatCard(title);
    }
    
      

    Drive-Dateien

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

  10. Klicken Sie oben auf „Projekt speichern“ .

Wenn Sie den Add-on-Code in vier Skriptdateien aufteilen, haben Sie eine logische Unterteilung für die Add-ons erstellt, die auf den Funktionen des Add-ons basiert. Dies hilft bei der langfristigen Wartung von Add-ons.

Schritt 2: Skriptmanifest aktualisieren

Aktualisieren Sie nun die Manifestdatei des Add-ons, um es zu konfigurieren. In diesem Schritt werden die Startseite und die kontextbezogenen Trigger Ihres Add-ons konfiguriert. Außerdem werden andere Informationen wie der Name und die Bereiche des Add-ons festgelegt.

  1. Klicken Sie links auf Projekteinstellungen .
  2. Klicken Sie das Kästchen „'appsscript.json' Manifestdatei im Editor“ an.
  3. Löschen Sie den Inhalt des Manifests und ersetzen Sie es durch Folgendes:

       {
      "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"
          }
        }
      }
    }
    
       

  4. Klicken Sie oben auf „Projekt speichern“ .

Schritt 3: Unveröffentlichtes Add-on installieren

Das Add-on kann getestet werden. Installieren Sie sie zu Testzwecken so:

  1. Klicken Sie rechts oben auf Bereitstellungen bereitstellen.
  2. Klicken Sie im Dialogfeld „Testbereitstellungen“ auf Installieren > Fertig.

Schritt 4: Ausprobieren

Sie können das Add-on jetzt verwenden:

  1. Öffnen Sie Ihr Gmail-Konto oder aktualisieren Sie den Gmail-Tab, falls Sie ihn bereits geöffnet haben. Das Katzen-Add-on wird in der rechten Seitenleiste Ihres Gmail-Posteingangs angezeigt.
  2. Klicken Sie in der rechten Seitenleiste auf „Katzen“ , um das Add-on zu öffnen.
  3. Wenn Sie über das Add-on informiert werden, dass es nicht autorisiert wurde, klicken Sie auf Zugriff autorisieren und folgen Sie der Anleitung auf dem Bildschirm.
  4. Nach der Autorisierung wird das Add-on neu geladen und kann verwendet werden.

Das Add-on zeigt ein Bild und eine Katze. Sie können das Bild ändern, indem Sie auf Katze ändern klicken. Klicken Sie auf Weitere Aktionen, um die Seite zu aktualisieren und mehr über die Drittanbieter-API zu erfahren, mit der die Katzenbilder bereitgestellt werden.

Wenn Sie eine Gmail-Nachricht öffnen, während das Add-on geöffnet ist, wird das Bild aktualisiert und der Text ändert sich in die Betreffzeile der Nachricht (abgeschnitten, wenn sie zu lang ist). Wenn Sie zum Gmail-Posteingang zurückkehren, gelangen Sie zurück zur Add-on-Startseite.

Sie können ähnliche Vorgänge in Google Kalender und Google Drive sehen, sowohl für die Startseite als auch für den Kontextinhalt. Sie müssen das Add-on in diesen Hosts nicht noch einmal autorisieren, um es zu verwenden.

Veröffentlichen

Da dies ein Beispiel-Add-on ist, endet unsere Anleitung hier. Wenn Sie ein echtes Add-on entwickelt haben, besteht der letzte Schritt darin, es für andere Personen zu veröffentlichen, damit sie es finden und installieren können.

Weitere Informationen

Weitere Informationen zur Erweiterung vonGoogle Workspace mit Apps Script finden Sie in den folgenden Ressourcen: