ระดับการเขียนโค้ด: ระดับกลาง
ระยะเวลา: 45 นาที
ประเภทโปรเจ็กต์: ส่วนเสริมของ Google Workspace
วัตถุประสงค์
- ทำความเข้าใจสิ่งที่โซลูชันทำ
- ทำความเข้าใจสิ่งที่บริการ Apps Script ทําภายใน โซลูชัน
- ตั้งค่าสภาพแวดล้อม
- ตั้งค่าสคริปต์
- เรียกใช้สคริปต์
เกี่ยวกับโซลูชันนี้
แสดงข้อมูล เช่น อีเมล หมายเลขโทรศัพท์ และแผนก เกี่ยวกับบุคคลที่คุณ ทำงานร่วมกันในองค์กร ขณะเดียวกันก็อยู่ใน Google Workspace คุณจะดูข้อมูลนี้ได้เมื่อตอบกลับข้อความ Gmail แก้ไขไฟล์ Google ไดรฟ์ หรือดูกิจกรรมใน Google ปฏิทิน
วิธีการทำงาน
สคริปต์จะได้รับที่อยู่อีเมลจากข้อความ ไฟล์ หรือกิจกรรมที่ใช้งานอยู่ ซึ่งอาจรวมถึงผู้รับข้อความ Gmail ทั้งนี้ขึ้นอยู่กับบริบท เครื่องมือแก้ไขไฟล์ในไดรฟ์และผู้เข้าร่วมกิจกรรมในปฏิทิน สคริปต์จะแสดงเฉพาะข้อมูลของที่อยู่อีเมลในองค์กรของคุณ
บริการ Apps Script
โซลูชันนี้ใช้บริการต่อไปนี้
- บริการขั้นสูงของไดเรกทอรี SDK ผู้ดูแลระบบ - ค้นหาผู้ที่ใช้ Directory API
- บริการพื้นฐาน - ใช้ชั้นเรียนของเซสชัน เพื่อช่วยกรองอีเมลและไม่แสดงผู้ใช้ปัจจุบันในการค้นหา รายการ
- บริการแคช - ค้นหาแคชก่อน เมื่อค้นหาบุคคลคนเดียวจาก Directory API
- บริการปฏิทิน - หาก บริบทคือกิจกรรมในปฏิทิน รับอีเมลจาก กิจกรรมที่กำลังดำเนินอยู่
- บริการบัตร - สร้างอินเทอร์เฟซผู้ใช้ ของส่วนเสริม
- บริการไดรฟ์ - หาก บริบทเป็นไฟล์ไดรฟ์ รับอีเมลของ ผู้ทำงานร่วมกันหากผู้ใช้มีสิทธิ์ดูในไฟล์ที่ใช้งานอยู่
- บริการ Gmail - หากบริบทคือ ข้อความ Gmail รับอีเมลจากที่อยู่ในช่อง "ถึง" "สำเนา" และ "จาก" ในข้อความ Gmail ที่ใช้งานอยู่
ข้อกำหนดเบื้องต้น
- เว็บเบราว์เซอร์ที่มีการเข้าถึงอินเทอร์เน็ต
- บัญชี Google Workspace (คุณอาจต้องได้รับการอนุมัติจากผู้ดูแลระบบ)
- โปรเจ็กต์ Google Cloud
ตั้งค่าสภาพแวดล้อมของคุณ
เปิดโปรเจ็กต์ที่อยู่ในระบบคลาวด์ในคอนโซล Google Cloud
หากยังไม่ได้เปิด ให้เปิดโปรเจ็กต์ที่อยู่ในระบบคลาวด์ที่ต้องการใช้ สำหรับตัวอย่างนี้
- ในคอนโซล Google Cloud ให้ไปที่หน้าเลือกโปรเจ็กต์
- เลือกโปรเจ็กต์ Google Cloud ที่ต้องการใช้ หรือคลิกสร้างโปรเจ็กต์แล้วทำตามวิธีการบนหน้าจอ หากสร้างโปรเจ็กต์ Google Cloud คุณอาจต้องเปิดการเรียกเก็บเงินสำหรับโปรเจ็กต์
เปิด Admin SDK API
การเริ่มต้นอย่างรวดเร็วนี้ใช้บริการขั้นสูงของ Admin SDK API Directory ซึ่ง เข้าถึง Admin SDK API
ก่อนใช้ Google APIs คุณต้องเปิดใช้ API เหล่านี้ในโปรเจ็กต์ Google Cloud คุณสามารถเปิด API ได้ตั้งแต่ 1 รายการขึ้นไปในโปรเจ็กต์ Google Cloud เดียวเปิด Admin SDK API ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์
กำหนดค่าหน้าจอขอความยินยอม OAuth
ส่วนเสริมของ Google Workspace ต้องมีการกำหนดค่าหน้าจอขอความยินยอม กำลังกำหนดค่า หน้าจอขอความยินยอม OAuth ของส่วนเสริมจะกำหนดสิ่งที่ Google จะแสดงต่อผู้ใช้
- ในคอนโซล Google Cloud ให้ไปที่เมนู > API และ บริการ > หน้าจอขอความยินยอม OAuth
- เลือกประเภทผู้ใช้เป็นภายใน แล้วคลิกสร้าง
- กรอกแบบฟอร์มการลงทะเบียนแอป แล้วคลิกบันทึกและดำเนินการต่อ
ในตอนนี้ คุณสามารถข้ามการเพิ่มขอบเขต แล้วคลิกบันทึกและดำเนินการต่อได้ ในอนาคต เมื่อคุณสร้างแอปสำหรับใช้นอก ในองค์กร Google Workspace คุณต้องเปลี่ยนประเภทผู้ใช้เป็นภายนอก จากนั้น เพิ่มขอบเขตการให้สิทธิ์ที่แอปของคุณต้องการ
- ตรวจสอบสรุปการลงทะเบียนแอป หากต้องการเปลี่ยนแปลง ให้คลิกแก้ไข หากแอป การลงทะเบียนถูกต้องแล้ว ให้คลิกกลับไปที่หน้าแดชบอร์ด
ตั้งค่าสคริปต์
สร้างโปรเจ็กต์ Apps Script
คลิกปุ่มต่อไปนี้เพื่อเปิด Apps Script รายชื่อทีม
เปิดโครงการคลิกภาพรวม
ในหน้าภาพรวม ให้คลิกทำสำเนา
คัดลอกหมายเลขโปรเจ็กต์ที่อยู่ในระบบคลาวด์
- ในคอนโซล Google Cloud ให้ไปที่เมนู > IAM และ ผู้ดูแลระบบ > การตั้งค่า
- คัดลอกค่าในช่องหมายเลขโปรเจ็กต์
ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของโปรเจ็กต์ Apps Script
- ในโปรเจ็กต์ Apps Script ที่คัดลอกมา
คลิกการตั้งค่าโปรเจ็กต์
- ในส่วนโครงการ Google Cloud Platform (GCP) ให้คลิกเปลี่ยนโครงการ
- วางหมายเลขโปรเจ็กต์ Google Cloud ในหมายเลขโปรเจ็กต์ GCP
- คลิกตั้งค่าโปรเจ็กต์
ติดตั้งการทดสอบการทำให้ใช้งานได้
- คลิกตัวแก้ไขในโปรเจ็กต์ Apps Script ที่คัดลอกมา
- เปิดไฟล์
Code.gs
แล้วคลิกเรียกใช้ เมื่อได้รับข้อความแจ้ง ให้สิทธิ์ สคริปต์ - คลิกทำให้ใช้งานได้ > ทดสอบการทำให้ใช้งานได้
- คลิกติดตั้ง > เสร็จสิ้น
เรียกใช้สคริปต์
- เปิดข้อความ Gmail, กิจกรรมในปฏิทิน หรือ ไฟล์ในไดรฟ์
- เปิดส่วนเสริมรายชื่อทีมในแถบด้านข้างทางขวา
- ให้สิทธิ์ส่วนเสริมหากได้รับข้อความแจ้ง
- ส่วนเสริมจะแสดงข้อมูลเกี่ยวกับ สมาชิกทีม หรือระบุว่าข้อความ กิจกรรม หรือไฟล์ไม่มีทีม
- หากต้องการค้นหาสมาชิกในทีม ให้คลิกค้นหาผู้คนแล้วป้อนชื่อหรืออีเมล ที่อยู่ คลิกค้นหา
ตรวจสอบโค้ด
หากต้องการตรวจสอบโค้ด Apps Script สำหรับโซลูชันนี้ ให้คลิก ดูซอร์สโค้ดด้านล่าง
ดูซอร์สโค้ด
Code.gs
// Copyright 2022 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // Sample Google Workspace Add-on that displays profile information about people // the user is collaborating with. Collaborators are based on the context -- // recipients of a gmail message, Drive file ACLs, or event attendees. // // Profile information is from the Directory API in the Admin SDK. As a result, // the add-on only shows information for email addresses in the same domain // as as the current user. Different strategies can be used for other use cases, // such as integration with a CRM where the focus may be on external email // addresses/customers. // See https://github.com/contributorpw/lodashgs var _ = LodashGS.load(); /** * Renders the home page for the add-on. Used in all host apps when * no context selected. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onHomePage(event) { var card = buildSearchCard_(); return [card]; } /** * Renders the contextual interface for a Gmail message. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onGmailMessageSelected(event) { var emails = extractEmailsFromMessage_(event); var people = fetchPeople_(emails); if (people.length == 0) { var card = buildSearchCard_("No team members found for current message."); return [card]; } var card = buildTeamListCard_(people) return [card]; } /** * Renders the contextual interface for a calendar event. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onCalendarEventOpen(event) { var emails = extractEmailsFromCalendarEvent_(event); var people = fetchPeople_(emails); if (people.length == 0) { var card = buildSearchCard_("No team members found for current event."); return [card]; } var card = buildTeamListCard_(people) return [card]; } /** * Renders the contextual interface for a selected Drive file. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onDriveItemsSelected(event) { // For demo, only allow single select on files. if (event.drive.selectedItems.length != 1) { var message = "To view team members collaborating on a file, select one file only."; var card = buildSearchCard_(message); return [card]; } var selectedItem = event.drive.selectedItems[0]; if (!selectedItem.addonHasFileScopePermission) { // Need file access to read ACL, ask user to authorize. var authorizeFilesAction = CardService.newAction() .setFunctionName("onAuthorizeDriveFiles") .setLoadIndicator(CardService.LoadIndicator.SPINNER) .setParameters({id: selectedItem.id}); var authorizationMessage = CardService.newTextParagraph() .setText("To view the people on your team the file is shared with, click *Authorize* to grant access."); var authorizeButton = CardService.newTextButton() .setText("Authorize") .setOnClickAction(authorizeFilesAction); var card = CardService.newCardBuilder() .addSection(CardService.newCardSection() .addWidget(authorizationMessage) .addWidget(authorizeButton)) .build(); return [card]; } // Have access, extract ACLs to find co-workers var emails = extractEmailsFromDrivePermissions_(event); var people = fetchPeople_(emails); if (people.length == 0) { var card = buildSearchCard_("No team members found for current file."); return [card]; } var card = buildTeamListCard_(people) return [card]; } /** * Handles the click for requesting drive file access. * * @param {Object} event - current add-on event * @return {ActionResponse} Request to authorize access to a drive item */ function onAuthorizeDriveFiles(event) { var id = event.parameters.id; return CardService.newDriveItemsSelectedActionResponseBuilder() .requestFileScope(id) .build(); } /** * Handles the user search request. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onSearch(event) { if (!event.formInputs || !event.formInputs.query) { var notification = CardService.newNotification() .setText("Enter a query before searching."); return CardService.newActionResponseBuilder() .setNotification(notification) .build(); } var query = event.formInputs.query[0]; var people = queryPeople_(query); if (!people || people.length == 0) { var notification = CardService.newNotification().setText("No people found."); return CardService.newActionResponseBuilder() .setNotification(notification) .build(); } var card = buildTeamListCard_(people); var navigation = CardService.newNavigation().pushCard(card); return CardService.newActionResponseBuilder() .setNavigation(navigation) .build(); } /** * Handles the drill down to view detailed information about a person. * * @param {Object} event - current add-on event * @return {Card[]} Card(s) to display */ function onShowPersonDetails(event) { var person = fetchPerson_(event.parameters.email); var card = buildPersonDetailsCard_(person); return [card] } /** * Builds a card for displaying detailed information about a team member. Currently only shows * a small subset of available information for demo purposes. * * @param {Object} person - User object from the Directory API * @return {Card} Card to display */ function buildPersonDetailsCard_(person) { var photoUrl = person.thumbnailPhotoUrl ? person.thumbnailPhotoUrl : "https://ssl.gstatic.com/s2/profiles/images/silhouette200.png"; var cardHeader = CardService.newCardHeader() .setImageUrl(photoUrl) .setImageStyle(CardService.ImageStyle.CIRCLE) .setTitle(person.name.fullName) if (person.organizations && person.organizations.length) { cardHeader.setSubtitle(person.organizations[0].title); } var section = CardService.newCardSection(); if (person.emails) { person.emails.forEach(function(email) { section.addWidget(CardService.newKeyValue() .setIcon(CardService.Icon.EMAIL) .setContent(email.address)); }); } if (person.phones) { person.phones.forEach(function(phone) { section.addWidget(CardService.newKeyValue() .setIcon(CardService.Icon.PHONE) .setContent(phone.value)); }); } if (person.organizations) { person.organizations.forEach(function(org) { section.addWidget(CardService.newKeyValue() .setIcon(CardService.Icon.MEMBERSHIP) .setContent(org.department)); }); } if (person.locations) { person.locations.forEach(function(location) { var formattedLocation = Utilities.formatString("%s<br>%s", location.area, location.buildingId); section.addWidget(CardService.newKeyValue() .setIcon(CardService.Icon.MAP_PIN) .setContent(formattedLocation)); }); } return CardService.newCardBuilder() .setHeader(cardHeader) .addSection(section) .build(); } /** * Builds a card for displaying a list of people * * @param {Object[]} people - Array of users from the Directory API * @return {Card} Card to display */ function buildTeamListCard_(people) { var resultsSection = CardService.newCardSection(); people.forEach(function(person) { var photoUrl = person.thumbnailPhotoUrl ? person.thumbnailPhotoUrl : "https://ssl.gstatic.com/s2/profiles/images/silhouette200.png"; var title = person.organizations ? person.organizations[0].title : null; var clickAction = CardService.newAction() .setFunctionName("onShowPersonDetails") .setLoadIndicator(CardService.LoadIndicator.SPINNER) .setParameters({email: person.primaryEmail}); var personSummaryWidget = CardService.newKeyValue() .setContent(person.name.fullName) .setIconUrl(photoUrl) .setOnClickAction(clickAction); if (person.organizations && person.organizations.length) { personSummaryWidget.setBottomLabel(person.organizations[0].title); } resultsSection.addWidget(personSummaryWidget); }); return CardService.newCardBuilder() .addSection(resultsSection) .build(); } /** * Builds the search interface for looking up people. * * @param {string} opt_error - Optional message to include (typically when * contextual search failed.) * @return {Card} Card to display */ function buildSearchCard_(opt_error) { var banner = CardService.newImage() .setImageUrl('https://storage.googleapis.com/gweb-cloudblog-publish/original_images/Workforce_segmentation_1.png'); var searchField = CardService.newTextInput() .setFieldName("query") .setHint("Name or email address") .setTitle("Search for people"); var onSubmitAction = CardService.newAction() .setFunctionName("onSearch") .setLoadIndicator(CardService.LoadIndicator.SPINNER); var submitButton = CardService.newTextButton() .setText("Search") .setOnClickAction(onSubmitAction); var section = CardService.newCardSection() .addWidget(banner) .addWidget(searchField) .addWidget(submitButton); if (opt_error) { var message = CardService.newTextParagraph() .setText("Note: " + opt_error); section.addWidget(message); } return CardService.newCardBuilder() .addSection(section) .build(); } /** * Extracts email addresses from the selected Gmail message. Grabs all emails * from the to/cc/from headers. * * @param {Object} event - current add-on event * @return {string[]} Array of email addresses. */ function extractEmailsFromMessage_(event) { // Fetch currently selected message var accessToken = event.messageMetadata.accessToken; var messageId = event.messageMetadata.messageId; GmailApp.setCurrentMessageAccessToken(accessToken); var message = GmailApp.getMessageById(messageId); if (!message) { return []; } // Parse/emit any email addresses in the to/cc/from headers var splitEmailsRegexp = /\b[A-Z0-9._%+-]+@(?:[A-Z0-9-]+\.)+[A-Z]{2,6}\b/gi; var emails = _.union( message.getTo().match(splitEmailsRegexp), message.getCc().match(splitEmailsRegexp), message.getFrom().match(splitEmailsRegexp) ); // Remove any +suffixes in the user name portion to get the canonical email var normalizeRegexp = /(.*)\+.*@(.*)/; emails = emails.map(function(email) { return email.replace(normalizeRegexp, "$1@$2"); }); return filterAndSortEmails_(emails); } /** * Extracts email addresses from the selected Drive item. Grabs all emails * from the file ACLs (if user has permission to view them.) * * @param {Object} event - current add-on event * @return {string[]} Array of email addresses. */ function extractEmailsFromDrivePermissions_(event) { // Make sure just 1 file selected. if (event.drive.selectedItems.length != 1) { return []; } var itemId = event.drive.selectedItems[0].id; var emails = []; var item = Drive.Files.get(itemId, {fields: "owners, sharingUser"}); if (item.sharingUser) { emails.push(item.sharingUser.emailAddress); } if (item.owners) { item.owners.forEach(function(owner) { emails.push(owner.emailAddress); }); } try { var permissions = Drive.Permissions.list(itemId, {fields: '*'}); if (permissions) { permissions.permissions.forEach(function(permission) { if (permission.type != 'domain') { emails.push(permission.emailAddress); } }); } } catch (e) { // Ignore inability to fetch permissions, may not have access console.warn(e); } return filterAndSortEmails_(emails) } /** * Extracts email addresses from the selected calendar event (attendees.) * * @param {Object} event - current add-on event * @return {string[]} Array of email addresses. */ function extractEmailsFromCalendarEvent_(event) { if (!event.calendar || !event.calendar.attendees) { return []; } var emails = event.calendar.attendees.map(function(attendee) { return attendee.email; }); return filterAndSortEmails_(emails); } /** * Filter email addresses to include only those in the same * domain and excluding the current user. * * @param {string[]} emails - Array of email addresses * @return {string[]} */ function filterAndSortEmails_(emails) { if (!emails) { return []; } var userEmail = Session.getActiveUser().getEmail(); var domain = userEmail.slice(userEmail.indexOf('@') + 1); emails = emails.filter(function(email) { return _.endsWith(email, domain) && email != userEmail; }); emails = _.uniq(emails); return emails.sort(); } /** * Look up one or more people from the Directory API. May omit items * if email addresses aren't valid domain users. * * @param {string[]} emails - Array of email addresses to fetch * @return {Object[]} Array of user objects. */ function fetchPeople_(emails) { if (!emails || emails.length == 0) { return []; } return emails.map(fetchPerson_).filter(function(item) { return item != null && item.primaryEmail; }); } /** * Look up a single person from the Directory API. * * @param {string} email - Email addresses to fetch * @return {Object} User object or null if not a valid user */ function fetchPerson_(email) { if (!email) { return null; } // Check cache first var person = CacheService.getUserCache().get(email); if (person && person.primaryEmail) { return JSON.parse(person); } try { person = AdminDirectory.Users.get( email, { projection: 'full', viewType: 'domain_public'}); CacheService.getUserCache().put(email, JSON.stringify(person)); return person; } catch (e) { // Ignore error, may not be valid domain user anymore. console.warn(e); } return null; } /** * Search for people from the Directory API by name or email address. * * @param {string} query - Name or email address to search for. * @return {Object[]} Array of user objects. */ function queryPeople_(query) { try { var options = { query: query, maxResults: 10, customer: 'my_customer', projection: 'full', viewType: 'domain_public' }; var results = AdminDirectory.Users.list(options); var cacheValues = results.users.reduce(function(map, person) { map[person.primaryEmail] = JSON.stringify(person); return map; }, {}); CacheService.getUserCache().putAll(cacheValues); return results.users; } catch (e) { // Ignore error console.warn(e); } return []; }
appsscript.json
{ "timeZone": "America/Denver", "dependencies": { "enabledAdvancedServices": [{ "userSymbol": "Drive", "serviceId": "drive", "version": "v3" }, { "userSymbol": "AdminDirectory", "serviceId": "admin", "version": "directory_v1" }], "libraries": [{ "userSymbol": "LodashGS", "libraryId": "1SQ0PlSMwndIuOAgtVJdjxsuXueECtY9OGejVDS37ckSVbMll73EXf2PW", "version": "5" }] }, "exceptionLogging": "STACKDRIVER", "oauthScopes": [ "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/admin.directory.user.readonly", "https://www.googleapis.com/auth/gmail.addons.execute", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/drive.file" ], "urlFetchWhitelist": [], "runtimeVersion": "V8", "addOns": { "common": { "name": "Team List", "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/people_black_24dp.png", "layoutProperties": { "primaryColor": "#4285f4", "secondaryColor": "#ea4335" }, "homepageTrigger": { "runFunction": "onHomePage", "enabled": true }, "universalActions": [{ "label": "Feedback", "openLink": "https://github.com/googleworkspace/add-ons-samples/issues" }], "openLinkUrlPrefixes": [ "https://github.com/googleworkspace/add-ons-samples/" ] }, "gmail": { "contextualTriggers": [{ "unconditional": { }, "onTriggerFunction": "onGmailMessageSelected" }] }, "drive": { "homepageTrigger": { "runFunction": "onHomePage", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "onDriveItemsSelected" } }, "calendar": { "homepageTrigger": { "runFunction": "onHomePage", "enabled": true }, "eventOpenTrigger": { "runFunction": "onCalendarEventOpen" }, "currentEventAccess": "READ" } } }
ผู้ร่วมให้ข้อมูล
ตัวอย่างนี้ดูแลโดย Google ด้วยความช่วยเหลือจากผู้เชี่ยวชาญของ Google Developer