Membangun Add-on Google Workspace dengan Apps Script

Panduan memulai ini membuat Add-on Google Workspace sederhana yang menunjukkan beranda, pemicu kontekstual, dan menghubungkan ke API pihak ketiga.

Add-on membuat konten kontekstual dan non-kontekstual antarmuka di Gmail, Kalender, dan Drive. Add-on menampilkan gambar acak kucing dengan teks yang menutupi gambar. Teksnya statis untuk beranda atau diambil dari konteks aplikasi host untuk pemicu kontekstual.

Tujuan

• Menyiapkan lingkungan Anda.
• Siapkan skrip.
• Jalankan skrip.

Prasyarat

Untuk menggunakan contoh ini, Anda memerlukan prasyarat berikut:

• Akun Google (Akun Google Workspace mungkin memerlukan persetujuan administrator).

• Browser web dengan akses ke internet.

• Project Google Cloud.

Menyiapkan lingkungan Anda

Buka project Cloud Anda di konsol Google Cloud

Jika belum terbuka, buka project Cloud yang ingin Anda gunakan untuk contoh ini:

1. Di konsol Google Cloud, buka halaman Select a project.

   Pilih project Cloud

2. Pilih project Google Cloud yang ingin Anda gunakan. Atau, klik Buat project dan ikuti petunjuk di layar. Jika membuat project Google Cloud, Anda mungkin perlu mengaktifkan penagihan untuk project tersebut.

Mengonfigurasi layar izin OAuth

Add-on Google Workspace memerlukan konfigurasi layar izin. Mengonfigurasi layar izin OAuth add-on Anda menentukan apa yang kepada pengguna.

1. Di konsol Google Cloud, buka Menu menu > API & Layanan > Layar izin OAuth.

   Buka layar izin OAuth

2. Untuk Jenis pengguna, pilih Internal, lalu klik Buat.
3. Lengkapi formulir pendaftaran aplikasi, lalu klik Simpan dan Lanjutkan.

4. Untuk saat ini, Anda dapat melewati penambahan cakupan, lalu mengklik Simpan dan Lanjutkan. Pada masa mendatang, jika Anda membuat aplikasi untuk digunakan di luar organisasi Google Workspace, Anda harus mengubah Jenis pengguna menjadi Eksternal, lalu menambahkan cakupan otorisasi yang dibutuhkan aplikasi Anda.

5. Tinjau ringkasan pendaftaran aplikasi Anda. Untuk melakukan perubahan, klik Edit. Jika aplikasi pendaftaran tampak tidak bermasalah, klik Kembali ke Dasbor.

Menyiapkan skrip

Membuat project Apps Script

1. Untuk membuat project Apps Script baru, buka script.new.
2. Klik Project tanpa judul.
3. Ganti nama project Apps Script Cats, lalu klik Rename.
4. Di samping file Code.gs, klik Lainnya more_vert > Ganti nama. Beri nama file Common.
5. Klik Tambahkan file add > Skrip. Beri nama file Gmail.
6. Ulangi langkah 5 untuk membuat 2 file skrip lagi bernama Calendar dan Drive. Setelah selesai, Anda akan memiliki 4 file skrip terpisah.

7. Ganti konten setiap file dengan kode yang sesuai berikut:

   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. Klik Project Settings .

9. Centang kotak Tampilkan "appsscript.json" file manifes dalam editor.

10. Klik Editor code.

11. Buka file appsscript.json dan ganti konten dengan yang berikut ini kode, lalu klik Simpan .

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

Salin nomor project Cloud

1. Di konsol Google Cloud, buka Menu menu > IAM & Admin > Setelan.

   Buka IAM & Setelan Admin

2. Di kolom Project number, salin nilainya.

Menetapkan project Cloud project Apps Script

1. Di project Apps Script Anda, klik Project Settings .
2. Pada Google Cloud Platform (GCP) Project, klik Change project.
3. Di GCP project number, tempel nomor project Google Cloud.
4. Klik Set project.

Menginstal deployment pengujian

1. Di project Apps Script, klik Editor code.
2. Klik Deploy > Test deployment.
3. Klik Instal > Selesai.

Jalankan skrip:

1. Buka Gmail.
2. Untuk membuka add-on, klik di panel samping kanan Kucing pets.
3. Jika diminta, izinkan add-on.
4. Add-on menampilkan gambar dan teks kucing. Untuk mengubah gambar, klik Change cat.
5. Jika Anda membuka email saat add-on terbuka, gambar akan diperbarui dan teks berubah menjadi baris subjek email (dipotong jika terlalu panjang).

Anda dapat melihat fungsionalitas serupa di Kalender dan Mengemudi. Anda tidak perlu mengizinkan ulang {i>add-on<i} untuk menggunakannya di aplikasi {i>host<i} tersebut.

Langkah berikutnya

• Memperluas Google Workspace dengan add-on
• Membuat Add-on Google Workspace
• Memublikasikan aplikasi