Google Workspace eklentisi hızlı başlangıç kılavuzu

Bu hızlı başlangıç kılavuzu; ana sayfaları, bağlamsal tetikleyicileri ve üçüncü taraf API'lerine bağlanmayı gösteren basit bir Google Workspace eklentisi oluşturur.

Eklenti; Gmail, Takvim ve Drive'da bağlamsal ve bağlamsal olmayan arayüzler oluşturur. Eklenti, rastgele bir kedi resmi ve resmin üzerine metin yerleştirir. Metin, ana sayfalar için statiktir veya bağlamsal tetikleyiciler için ana makine uygulaması bağlamından alınır.

Hedefler

  • Ortamınızı ayarlayın.
  • Komut dosyasını ayarlayın.
  • Komut dosyasını çalıştırın.

Ön koşullar

Bu örneği kullanmak için aşağıdaki önkoşullara ihtiyacınız vardır:

  • Bir Google Hesabı (Google Workspace hesapları için yönetici onayı gerekebilir).
  • İnternete erişimi olan bir web tarayıcısı.

  • Bir Google Cloud projesi.

Ortamınızı ayarlama

Google Cloud Console'da Cloud projenizi açma

Henüz açık değilse bu örnek için kullanmayı düşündüğünüz Cloud projesini açın:

  1. Google Cloud konsolunda Proje seçin sayfasına gidin.

    Bir Cloud projesi seçin

  2. Kullanmak istediğiniz Google Cloud projesini seçin. Alternatif olarak Proje oluştur'u tıklayın ve ekrandaki talimatları uygulayın. Bir Google Cloud projesi oluşturursanız proje için faturalandırmayı etkinleştirmeniz gerekebilir.

Google Workspace eklentileri için izin ekranı yapılandırması gerekir. Eklentinizin OAuth kullanıcı rızası ekranının yapılandırılması, Google'ın kullanıcılara ne göstereceğini tanımlar.

  1. Google Cloud konsolunda Menü > API'ler ve Hizmetler > OAuth izin ekranı'na gidin.

    OAuth izin ekranına gidin

  2. Uygulamanızın kullanıcı türünü seçin, ardından Oluştur'u tıklayın.
  3. Uygulama kayıt formunu doldurup Kaydet ve Devam Et'i tıklayın.
  4. Şimdilik kapsam eklemeyi atlayıp Kaydet ve Devam Et'i tıklayabilirsiniz. Gelecekte Google Workspace kuruluşunuzun dışında kullanmak için uygulama oluşturduğunuzda, uygulamanızın gerektirdiği yetkilendirme kapsamlarını eklemeniz ve doğrulamanız gerekir.

  5. Kullanıcı türü olarak Harici seçeneğini belirlediyseniz test kullanıcılarını ekleyin:
    1. Test kullanıcıları bölümünde Kullanıcı ekle'yi tıklayın.
    2. E-posta adresinizi ve diğer yetkili test kullanıcılarınızı girip Kaydet ve Devam Et'i tıklayın.
  6. Uygulama kaydı özetinizi inceleyin. Değişiklik yapmak için Düzenle'yi tıklayın. Uygulama kaydında sorun yoksa Kontrol Paneline Dön'ü tıklayın.

Komut dosyasını ayarlayın

Apps Komut Dosyası projesini oluşturma

  1. Yeni bir Apps Komut Dosyası projesi oluşturmak için script.new adresine gidin.
  2. Adsız proje'yi tıklayın.
  3. Apps Komut Dosyası projesini Kediler olarak yeniden adlandırın ve Yeniden adlandır'ı tıklayın.
  4. Code.gs dosyasının yanındaki Diğer > Yeniden adlandır'ı tıklayın. Dosyayı Common olarak adlandırın.
  5. Dosya ekle > Komut dosyası'nı tıklayın. Dosyayı Gmail olarak adlandırın.
  6. Calendar ve Drive adlı 2 komut dosyası daha oluşturmak için 5. adımı tekrarlayın. Bu işlemi tamamladığınızda 4 ayrı komut dosyanız olmalıdır.
  7. Her dosyanın içeriğini aşağıdaki karşılık gelen kodla değiştirin:

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

    Takvim.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. Proje Ayarları'nı Proje ayarları simgesi tıklayın.

  9. "appsscript.json" manifest dosyasını düzenleyicide göster kutusunu işaretleyin.

  10. Düzenleyici'yi tıklayın.

  11. appsscript.json dosyasını açın ve içeriği aşağıdaki kodla değiştirin, ardından Kaydet'i Kaydet simgesi tıklayın.

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

Cloud proje numarasını kopyala

  1. Google Cloud Console'da Cloud projenize gidin.
  2. Ayarlar ve Yardımcı Programlar > Proje ayarları'nı tıklayın.
  3. Proje numarasını kopyalayın.

Apps Komut Dosyası projesinin Cloud projesini ayarlama

  1. Apps Komut Dosyası projenizde Proje Ayarları'nı Proje ayarları simgesi tıklayın.
  2. Google Cloud Platform (GCP) Projesi altında, Projeyi değiştir'i tıklayın.
  3. GCP proje numarası alanına Google Cloud proje numarasını yapıştırın.
  4. Proje ayarla'yı tıklayın.

Test dağıtımı yükleme

  1. Apps Komut Dosyası projenizde Düzenleyici'yi tıklayın.
  2. Common.gs dosyasını açın ve Çalıştır'ı tıklayın. İstendiğinde komut dosyasını yetkilendirin.
  3. Dağıt > Dağıtımları test et'i tıklayın.
  4. Yükle > Bitti'yi tıklayın.

Komut dosyasını çalıştırın

  1. Gmail'e gidin.
  2. Eklentiyi açmak için sağ yan panelde Kediler'i tıklayın.
  3. İstenirse eklentiyi yetkilendirin.
  4. Eklenti, bir kedi resmi ve metni görüntüler. Resmi değiştirmek için Kedi değiştir'i tıklayın.
  5. Eklenti açıkken bir e-postayı açarsanız görsel yenilenir ve metin, e-postanın konu satırında görünür (çok uzunsa kısaltılır).

Takvim ve Drive'da da benzer işlevler görebilirsiniz. Eklentiyi ana makine uygulamalarında kullanmak için yeniden yetkilendirmeniz gerekmez.

Sonraki adımlar