פעולות ביומן

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

פעולה מצורפת לווידג'ט נתון באמצעות פונקציית ה-handler של הווידג'טים, שמגדירה גם את התנאי שמפעיל את הפעולה. כשהפעולה מופעלת, היא עורכת פונקציית קריאה חוזרת ייעודית. פונקציית הקריאה החוזרת מעבירה אובייקט אירוע שנושא מידע על האינטראקציות של המשתמש בצד הלקוח. עליכם להטמיע את פונקציית הקריאה החוזרת כדי שהיא תחזיר אובייקט תגובה ספציפי.

לדוגמה, נניח שאתם רוצים ללחוץ על לחצן ליצירה ולהצגה של כרטיס חדש. לשם כך צריך ליצור ווידג'ט חדש ללחצן ולהשתמש בפונקציית ה-handler של הלחצנים setOnClickAction(action) כדי להגדיר פיתוח כרטיסים Action. Action שמגדירים מציין פונקציית קריאה חוזרת (callback) של Apps Script, שמופעלת כשמשתמש לוחץ על הלחצן. במקרה כזה, מטמיעים את פונקציית הקריאה החוזרת כדי ליצור את הכרטיס הרצוי ולהחזיר אובייקט ActionResponse. האובייקט 'תשובה' מורה לתוסף להציג את הכרטיס שנוצר באמצעות פונקציית הקריאה החוזרת.

בדף הזה מתוארות פעולות בווידג'ט ספציפיות ליומן שאפשר לכלול בתוסף.

אינטראקציות ביומן

התוספים ל-Google Workspace שמרחיבים את יומן Google יכולים לכלול כמה פעולות נוספות לווידג'ט שהוא ספציפי ליומן. הפעולות האלה מחייבות את פונקציית הקריאה החוזרת המשויכת כדי להחזיר אובייקטים מיוחדים של תגובה:

בוצע ניסיון לפעולה	פונקציית הקריאה החוזרת אמורה לחזור
הוספת משתתפים	CalendarEventActionResponse
הגדרת הנתונים של שיחת הוועידה	CalendarEventActionResponse
הוספת קבצים מצורפים	CalendarEventActionResponse

כדי להשתמש בפעולות הווידג'ט ובאובייקטים של התגובה, כל התנאים הבאים צריכים להתקיים:

• הפעולה מופעלת בזמן שאירוע ביומן של המשתמש פתוח.
• בשדה המניפסט addOns.calendar.currentEventAccess של התוסף מוגדר הערך WRITE או READ_WRITE.
• התוסף כולל את https://www.googleapis.com/auth/calendar.addons.current.event.write ההיקף של יומן Google.

בנוסף, שינויים שבוצעו על ידי פונקציית הקריאה החוזרת לפעולה לא יישמרו עד שהמשתמש ישמור את האירוע ביומן.

הוספת משתתפים באמצעות פונקציית קריאה חוזרת

הדוגמה הבאה מראה איך ליצור לחצן שמוסיף משתתף ספציפי לאירוע ביומן שנמצא בעריכה:

  /**
   * Build a simple card with a button that sends a notification.
   * This function is called as part of the eventOpenTrigger that builds
   * a UI when the user opens an event.
   *
   * @param e The event object passed to eventOpenTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onAddAttendeesButtonClicked');
    var button = CardService.newTextButton()
        .setText('Add new attendee')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can add
    // attendees and disable the button if not.
    if (!e.calendar.capabilities.canAddAttendees) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Adds attendees to the
   * Calendar event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onAddAttendeesButtonClicked (e) {
    return CardService.newCalendarEventActionResponseBuilder()
        .addAttendees(["[e-mail]", "[e-mail]"])
        .build();
  }

הגדרת נתוני שיחת ועידה עם פונקציית קריאה חוזרת

הפעולה הזו תגדיר את הנתונים של שיחת הוועידה באירוע הפתוח. לנתוני שיחת הוועידה צריך לציין את המזהה של פתרון שיחת הוועידה, כי הפעולה לא הופעלה על ידי המשתמש שבחר בפתרון הרצוי.

תוכלו להיעזר בדוגמה הבאה כדי ליצור לחצן להגדרת נתוני שיחת ועידה לאירוע בעריכה:

  /**
   * Build a simple card with a button that sends a notification.
   * This function is called as part of the eventOpenTrigger that builds
   * a UI when the user opens a Calendar event.
   *
   * @param e The event object passed to eventOpenTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onSaveConferenceOptionsButtonClicked')
        .setParameters(
          {'phone': "1555123467", 'adminEmail': "[e-mail]"});
    var button = CardService.newTextButton()
        .setText('Add new attendee')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can set
    // conference data and disable the button if not.
    if (!e.calendar.capabilities.canSetConferenceData) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Sets conference data for the
   * Calendar event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onSaveConferenceOptionsButtonClicked(e) {
    var parameters = e.commonEventObject.parameters;

    // Create an entry point and a conference parameter.
    var phoneEntryPoint = ConferenceDataService.newEntryPoint()
      .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
      .setUri('tel:' + parameters['phone']);

    var adminEmailParameter = ConferenceDataService.newConferenceParameter()
        .setKey('adminEmail')
        .setValue(parameters['adminEmail']);

    // Create a conference data object to set to this Calendar event.
    var conferenceData = ConferenceDataService.newConferenceDataBuilder()
        .addEntryPoint(phoneEntryPoint)
        .addConferenceParameter(adminEmailParameter)
        .setConferenceSolutionId('myWebScheduledMeeting')
        .build();

    return CardService.newCalendarEventActionResponseBuilder()
        .setConferenceData(conferenceData)
        .build();
  }

הוספת קבצים מצורפים באמצעות פונקציית קריאה חוזרת

תוכלו להיעזר בדוגמה הבאה כדי ליצור לחצן שמוסיף קובץ מצורף לאירוע ביומן שנמצא בעריכה:

  /**
   * Build a simple card with a button that creates a new attachment.
   * This function is called as part of the eventAttachmentTrigger that
   * builds a UI when the user goes through the add-attachments flow.
   *
   * @param e The event object passed to eventAttachmentTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onAddAttachmentButtonClicked');
    var button = CardService.newTextButton()
        .setText('Add a custom attachment')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can add
    // attachments and disable the button if not.
    if (!e.calendar.capabilities.canAddAttachments) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Adds attachments to the Calendar
   * event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onAddAttachmentButtonClicked(e) {
    return CardService.newCalendarEventActionResponseBuilder()
             .addAttachments([
               CardService.newAttachment()
                 .setResourceUrl("https://example.com/test")
                 .setTitle("Custom attachment")
                 .setMimeType("text/html")
                 .setIconUrl("https://example.com/test.png")
             ])
        .build();
  }

הגדרת סמל הקובץ המצורף

סמל הקובץ המצורף צריך להתארח בתשתית של Google. למידע נוסף, ראו הוספת סמלים של קבצים מצורפים.