דף זה תורגם על ידי Cloud Translation API.

פיתוח תוסף ל-Google Workspace באמצעות Apps Script

במדריך הזה ליצירת תוסף ראשון, ניצור תוסף פשוט ל-Google Workspace שמציג דפי בית, טריגרים הקשריים וחיבור לממשקי API של צד שלישי.

התוסף יוצר ממשקים הקשריים ולא הקשריים ב-Gmail, ביומן וב-Drive. תוסף שמציג תמונה אקראית של חתול עם טקסט שמופיע מעל התמונה. הטקסט סטטי בדפי הבית או שהוא נלקח מההקשר של אפליקציית המארח עבור טריגרים הקשריים.

מטרות

מגדירים את הסביבה.
מגדירים את הסקריפט.
מריצים את הסקריפט.

דרישות מוקדמות

כדי להשתמש בדוגמה הזו, צריך לעמוד בדרישות המוקדמות הבאות:

חשבון Google (יכול להיות שחשבונות Google Workspace ידרשו אישור אדמין).
דפדפן אינטרנט עם גישה לאינטרנט.
פרויקט ב-Google Cloud.

הגדרת הסביבה

פותחים את פרויקט Cloud במסוף Google Cloud

אם הוא לא פתוח, פותחים את פרויקט Cloud שבו רוצים להשתמש בדוגמה הזו:

נכנסים לדף Select a project במסוף Google Cloud.
בוחרים פרויקט ב-Cloud
בוחרים את הפרויקט ב-Google Cloud שבו רוצים להשתמש. לחלופין, לוחצים על יצירת פרויקט ופועלים לפי ההוראות במסך. אם יוצרים פרויקט ב-Google Cloud, יכול להיות שיהיה צורך להפעיל את החיוב בפרויקט.

הגדרת מסך ההסכמה של OAuth

כדי להשתמש בתוספים ל-Google Workspace, צריך להגדיר מסך הסכמה. הגדרת מסך ההסכמה של OAuth בתוסף קובעת מה Google מציגה למשתמשים.

במסוף Google Cloud, עוברים אל תפריט > > Branding.
מעבר לדף 'מיתוג'
אם כבר הגדרתם את , תוכלו להגדיר את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים מיתוג, קהל וגישה לנתונים. אם מופיעה ההודעה עדיין לא הוגדר, לוחצים על תחילת העבודה:

בקטע App Information (פרטי האפליקציה), בשדה App name (שם האפליקציה), מזינים שם לאפליקציה.
בקטע כתובת אימייל לתמיכה במשתמשים, בוחרים כתובת אימייל לתמיכה שדרכה משתמשים יכולים ליצור איתכם קשר אם יש להם שאלות לגבי ההסכמה שלהם.
לוחצים על הבא.
בקטע קהל, בוחרים באפשרות פנימי.
לוחצים על הבא.
בקטע פרטים ליצירת קשר, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
לוחצים על הבא.
בקטע סיום, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, מסמנים את התיבה אני מסכים/ה למדיניות של Google בנושא נתוני משתמשים בשירותי API.
לוחצים על המשך.
לוחצים על יצירה.

בינתיים, אפשר לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון Google Workspace שלכם, תצטרכו לשנות את סוג המשתמש לחיצוני. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

הגדרת הסקריפט

יצירת פרויקט Apps Script

כדי ליצור פרויקט חדש ב-Apps Script, עוברים אל script.new.
לוחצים על פרויקט ללא שם.
משנים את השם של פרויקט Apps Script‏ Cats ולוחצים על Rename (שינוי שם).
לצד הקובץ 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);
}

לוחצים על Project Settings (הגדרות הפרויקט) .
מסמנים את התיבה הצגת קובץ המניפסט 'Appscript.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"
      }
    }
  }
}

העתקת מספר הפרויקט ב-Cloud

במסוף Google Cloud, נכנסים לתפריט > IAM & Admin ‏(IAM ומנהל מערכת) > Settings (הגדרות).
כניסה לדף IAM & Admin Settings
מעתיקים את הערך בשדה מספר הפרויקט.

הגדרת פרויקט Cloud לפרויקט Apps Script

בפרויקט Apps Script, לוחצים על הגדרות הפרויקט .
בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.
בשדה מספר פרויקט GCP, מדביקים את מספר הפרויקט ב-Google Cloud.
לוחצים על הגדרת פרויקט.

התקנת פריסת בדיקה

בפרויקט Apps Script, לוחצים על עורך .
לוחצים על פריסה > בדיקת פריסות.
לוחצים על התקנה > סיום.

הפעלת הסקריפט

עוברים אל Gmail.
כדי לפתוח את התוסף, בחלונית הצדדית השמאלית, לוחצים על סמל החתולים .
אם מוצגת בקשה, מאשרים את התוסף.
התוסף מציג תמונה של חתול וטקסט. כדי לשנות את התמונה, לוחצים על שינוי התמונה.
אם פותחים אימייל בזמן שהתוסף פתוח, התמונה מתרעננת והטקסט משתנה לשורת הנושא של האימייל (הוא ייחתך אם הוא ארוך מדי).

אפשר לראות פונקציונליות דומה ביומן וב-Drive. לא צריך לתת הרשאה מחדש לתוסף כדי להשתמש בו באפליקציות המארחות האלה.

פיתוח תוסף ל-Google Workspace באמצעות Apps Script קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.