البدء السريع لإضافة Google Workspace

يؤدي هذا البدء السريع إلى إنشاء إضافة بسيطة من Google Workspace توضّح الصفحات الرئيسية وعوامل تشغيل المحتوى والربط بواجهات برمجة تطبيقات تابعة لجهات خارجية.

تعمل الإضافة على إنشاء واجهات سياقية وغير سياقية في Gmail و"تقويم Google" وDrive. تعرض الإضافة صورة عشوائية لقطة مع نص يظهر على سطح الصورة. ويكون النص إما ثابتًا للصفحات الرئيسية أو مأخوذًا من سياق تطبيق المضيف للمشغلات السياقية.

الأهداف

  • إعداد البيئة.
  • إعداد النص البرمجي.
  • شغّل النص البرمجي.

المتطلبات الأساسية

لاستخدام هذا النموذج، تحتاج إلى المتطلبات الأساسية التالية:

  • حساب Google (قد تحتاج حسابات Google Workspace إلى موافقة المشرف)

  • متصفح ويب يتمتع بإمكانية الدخول إلى الإنترنت.

  • مشروع Google Cloud

إعداد البيئة

فتح مشروعك على السحابة الإلكترونية في Google Cloud Console

إذا لم يكن مفتوحًا بالفعل، فافتح مشروع السحاب الذي تنوي استخدامه لهذا النموذج:

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى صفحة اختيار مشروع.

    اختيار مشروع على السحابة الإلكترونية

  2. اختَر مشروع Google Cloud الذي تريد استخدامه. أو انقر على إنشاء مشروع واتبع التعليمات التي تظهر على الشاشة. في حال إنشاء مشروع على Google Cloud، قد تحتاج إلى تفعيل الفوترة للمشروع.

تتطلب إضافات Google Workspace ضبط شاشة الموافقة. عند ضبط شاشة إضافة OAuth OAuth، يتم تحديد ما تعرضه Google للمستخدمين.

  1. في Google Cloud Console، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

    الانتقال إلى شاشة موافقة OAuth

  2. حدد نوع المستخدم لتطبيقك، ثم انقر على إنشاء.
  3. أكمل نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

  4. في الوقت الحالي، يمكنك تخطي إضافة نطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق للاستخدام خارج مؤسسة Google Workspace، عليك إضافة نطاقات التفويض التي يتطلبها تطبيقك والتحقّق منها.

  5. في حال اختيار خارجي لنوع المستخدم، أضِف مستخدمين تجريبيين:
    1. ضمن اختبار المستخدمين، انقر على إضافة مستخدمين.
    2. أدخِل عنوان البريد الإلكتروني وأيّ مستخدمين آخرين مُعتمَدين للاختبار، ثم انقر على حفظ ومتابعة.
  6. راجِع ملخّص تسجيل التطبيقات. لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق على ما يرام، انقر على الرجوع إلى لوحة البيانات.

إعداد النص البرمجي

إنشاء مشروع برمجة التطبيقات

  1. لإنشاء مشروع جديد لبرمجة التطبيقات، انتقِل إلى script.new.
  2. انقر على مشروع بلا عنوان.
  3. أعِد تسمية مشروع "برمجة تطبيقات Google" قطط وانقر على إعادة تسمية.
  4. بجانب ملف Code.gs، انقر على رمز المزيد > إعادة تسمية. أدخِل اسمًا للملف Common.
  5. انقر على رمز إضافة ملف > نص برمجي. أدخِل اسمًا للملف Gmail.
  6. كرِّر الخطوة 5 لإنشاء ملفَّين نصيَّين إضافيَين باسم Calendar وDrive. عند الانتهاء، من المفترض أن يكون لديك 4 ملفات نصوص برمجية منفصلة.

  7. استبدل محتوى كل ملف بالشفرة المقابلة التالية:

    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. انقر على إعدادات المشروع رمز إعدادات المشروع.

  9. ضع علامة في المربع عرض ملف البيان "appsscript.json" في المحرِّر.

  10. انقر على أداة التحرير .

  11. افتح الملف appsscript.json واستبدل المحتوى بالرمز التالي، ثم انقر على "حفظ" رمز الحفظ.

    ملف appscript.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"
      }
    }
  }
}

نسخ رقم المشروع على السحابة الإلكترونية

  1. انتقِل إلى مشروعك على Google Cloud في Google Cloud Console.
  2. انقر على الإعدادات والأدوات المساعدة > إعدادات المشروع.
  3. انسخ رقم المشروع.

إعداد مشروع السحابة الإلكترونية لمشروع برمجة التطبيقات

  1. في مشروع برمجة التطبيقات، انقر على إعدادات المشروع رمز إعدادات المشروع.
  2. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
  3. في رقم مشروع Google Cloud Platform، الصق رقم مشروع Google Cloud.
  4. انقر على تحديد المشروع.

تثبيت عملية نشر تجريبية

  1. في مشروع "برمجة تطبيقات Google"، انقر على أداة التحرير .
  2. افتح الملف Common.gs وانقر على تشغيل. فوضّح النص البرمجي عندما يُطلب منك ذلك.
  3. انقر على نشر > اختبار عمليات النشر.
  4. انقر على تثبيت > تم.

تشغيل النص البرمجي

  1. انتقِل إلى Gmail.
  2. لفتح الإضافة، انقر على رمز القطط في اللوحة الجانبية اليسرى.
  3. تفويض الإضافة، إذا طُلب منك ذلك.
  4. تعرض الإضافة صورة ونص للقطط. لتغيير الصورة، انقر على تغيير القطة.
  5. إذا فتحت رسالة إلكترونية أثناء فتح الإضافة، فسيتم تحديث الصورة ويتغير النص إلى سطر موضوع الرسالة الإلكترونية (مقتطعة إذا كانت طويلة جدًا).

يمكنك مشاهدة وظائف مشابهة في التقويم وDrive. لا تحتاج إلى إعادة تفويض الإضافة لاستخدامها في هذه التطبيقات المضيفة.

الخطوات التالية