หน้านี้ได้รับการแปลโดย Cloud Translation API

สร้างส่วนเสริมของ Google Workspace ด้วย Apps Script

คู่มือเริ่มต้นฉบับย่อนี้จะสร้างส่วนเสริม Google Workspace อย่างง่ายที่แสดง หน้าแรก ทริกเกอร์ตามบริบท และการเชื่อมต่อกับ API ของบุคคลที่สาม

ส่วนเสริมจะสร้างอินเทอร์เฟซตามบริบทและแบบไม่มีบริบท ใน Gmail, ปฏิทิน และไดรฟ์ โดยส่วนเสริมจะแสดงรูปภาพแมวแบบสุ่มพร้อมข้อความ ซ้อนทับบนรูปภาพ ข้อความจะเป็นแบบคงที่สำหรับหน้าแรกหรือนำมาจากบริบทของแอปพลิเคชันโฮสต์สำหรับทริกเกอร์ตามบริบท

วัตถุประสงค์

ตั้งค่าสภาพแวดล้อม
ตั้งค่าสคริปต์
เรียกใช้สคริปต์

ข้อกำหนดเบื้องต้น

หากต้องการใช้ตัวอย่างนี้ คุณต้องมีข้อกำหนดเบื้องต้นต่อไปนี้

บัญชี Google (บัญชี Google Workspace อาจต้องได้รับการอนุมัติจากผู้ดูแลระบบ)
เว็บเบราว์เซอร์ที่มีสิทธิ์เข้าถึงอินเทอร์เน็ต
โปรเจ็กต์ Google Cloud

ตั้งค่าสภาพแวดล้อม

เปิดโปรเจ็กต์ Cloud ใน Google Cloud Console

หากยังไม่ได้เปิด ให้เปิดโปรเจ็กต์ Cloud ที่คุณต้องการใช้ สำหรับตัวอย่างนี้

ไปที่หน้าเลือกโปรเจ็กต์ใน Google Cloud Console
เลือกโปรเจ็กต์ที่อยู่ในระบบคลาวด์
เลือกโปรเจ็กต์ Google Cloud ที่ต้องการใช้ หรือคลิกสร้างโปรเจ็กต์ แล้วทำตามวิธีการบนหน้าจอ หากสร้างโปรเจ็กต์ Google Cloud คุณอาจต้องเปิดการเรียกเก็บเงินสำหรับโปรเจ็กต์

กำหนดค่าหน้าจอขอความยินยอม OAuth

ส่วนเสริมของ Google Workspace ต้องมีการกำหนดค่าหน้าจอขอความยินยอม การกำหนดค่าหน้าจอขอความยินยอม OAuth ของส่วนเสริมจะกำหนดสิ่งที่ Google แสดงต่อผู้ใช้

ในคอนโซล Google Cloud ให้ไปที่เมนู > > การสร้างแบรนด์
ไปที่การสร้างแบรนด์
หากกำหนดค่า แล้ว คุณจะกำหนดค่าการตั้งค่าหน้าจอขอความยินยอม OAuth ต่อไปนี้ได้ในการสร้างแบรนด์ กลุ่มเป้าหมาย และการเข้าถึงข้อมูล หากเห็นข้อความที่ระบุว่า ยังไม่ได้กำหนดค่า ให้คลิกเริ่มต้นใช้งาน

ในส่วนข้อมูลแอป ให้ป้อนชื่อแอปในชื่อแอป
ในอีเมลสนับสนุนสำหรับผู้ใช้ ให้เลือกอีเมลสนับสนุนที่ผู้ใช้สามารถติดต่อคุณได้หากมีข้อสงสัยเกี่ยวกับการยินยอม
คลิกถัดไป
เลือกภายในในส่วนผู้ชม
คลิกถัดไป
ในส่วนข้อมูลติดต่อ ให้ป้อนอีเมลที่คุณต้องการรับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงในโปรเจ็กต์
คลิกถัดไป
ในส่วนเสร็จสิ้น ให้อ่านนโยบายข้อมูลผู้ใช้ของบริการ Google API และหากยอมรับ ให้เลือกฉันยอมรับนโยบายข้อมูลผู้ใช้ของบริการ Google API
คลิกต่อไป
คลิกสร้าง

ในตอนนี้ คุณข้ามการเพิ่มขอบเขตได้ ในอนาคต เมื่อสร้างแอปเพื่อใช้ภายนอกองค์กร Google Workspace คุณจะต้องเปลี่ยนประเภทผู้ใช้เป็นภายนอก จากนั้น เพิ่มขอบเขตการให้สิทธิ์ที่แอปของคุณต้องการ ดูข้อมูลเพิ่มเติมได้ที่คู่มือกำหนดค่าความยินยอม OAuth ฉบับเต็ม

ตั้งค่าสคริปต์

สร้างโปรเจ็กต์ Apps Script

หากต้องการสร้างโปรเจ็กต์ Apps Script ใหม่ ให้ไปที่ script.new
คลิกโปรเจ็กต์ที่ไม่มีชื่อ
เปลี่ยนชื่อโปรเจ็กต์ Apps Script เป็น Cats แล้วคลิกเปลี่ยนชื่อ
คลิกเพิ่มเติม ข้างCode.gsไฟล์ > เปลี่ยนชื่อ ตั้งชื่อไฟล์ Common
คลิกเพิ่มไฟล์ > สคริปต์ ตั้งชื่อไฟล์ Gmail
ทำขั้นตอนที่ 5 ซ้ำเพื่อสร้างไฟล์สคริปต์อีก 2 ไฟล์ชื่อ Calendar และ Drive เมื่อเสร็จแล้ว คุณควรมีไฟล์สคริปต์แยกกัน 4 ไฟล์

แทนที่เนื้อหาของแต่ละไฟล์ด้วยโค้ดที่เกี่ยวข้องต่อไปนี้

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

คลิกการตั้งค่าโปรเจ็กต์
เลือกช่องแสดงไฟล์ Manifest "appsscript.json" ในเครื่องมือแก้ไข
คลิกตัดต่อวิดีโอ

เปิดไฟล์ appsscript.json แล้วแทนที่เนื้อหาด้วยโค้ดต่อไปนี้ จากนั้นคลิกบันทึก

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

คัดลอกหมายเลขโปรเจ็กต์ที่อยู่ในระบบคลาวด์

ใน Google Cloud Console ให้ไปที่เมนู > IAM & Admin > การตั้งค่า
ไปที่การตั้งค่า IAM และผู้ดูแลระบบ
คัดลอกค่าในช่องหมายเลขโปรเจ็กต์

ตั้งค่าโปรเจ็กต์ Cloud ของโปรเจ็กต์ Apps Script

ในโปรเจ็กต์ Apps Script ให้ คลิกการตั้งค่าโปรเจ็กต์
ในส่วนโปรเจ็กต์ Google Cloud Platform (GCP) ให้คลิกเปลี่ยนโปรเจ็กต์
ในหมายเลขโปรเจ็กต์ GCP ให้วางหมายเลขโปรเจ็กต์ Google Cloud
คลิกตั้งค่าโปรเจ็กต์

ติดตั้งการทดสอบการติดตั้งใช้งาน

ในโปรเจ็กต์ Apps Script ให้คลิกเอดิเตอร์
คลิกทำให้ใช้งานได้ > ทดสอบการทำให้ใช้งานได้
คลิกติดตั้ง > เสร็จสิ้น

เรียกใช้สคริปต์

ไปที่ Gmail
หากต้องการเปิดส่วนเสริม ให้คลิก แมว ในแผงด้านข้างทางขวา
หากได้รับข้อความแจ้ง ให้ให้สิทธิ์ส่วนเสริม
โดยส่วนเสริมจะแสดงรูปภาพและข้อความของแมว หากต้องการเปลี่ยนรูปภาพ ให้คลิกเปลี่ยนแมว
หากเปิดอีเมลขณะที่เปิดส่วนเสริมอยู่ รูปภาพจะรีเฟรชและข้อความจะเปลี่ยนเป็นบรรทัดเรื่องของอีเมล (ระบบจะตัดข้อความหากยาวเกินไป)

คุณจะเห็นฟังก์ชันการทำงานที่คล้ายกันในปฏิทินและไดรฟ์ คุณไม่จำเป็นต้องให้สิทธิ์ ส่วนเสริมอีกครั้งเพื่อใช้ในแอปโฮสต์เหล่านั้น