איך יוצרים כרטיס הגדרה לשלב

תוכנית Gemini אלפא: התכונה 'זרימות' זמינה כחלק מתוכנית Gemini אלפא.

במדריך הזה מוסבר איך ליצור כרטיס הגדרה שמאפשר למשתמשים להתאים אישית שלב ב-Google Workspace Flows ולספק לו קלט.

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

• הכלי ליצירת כרטיסים, כלי אינטראקטיבי שעוזר ליצור ולהגדיר כרטיסים.
• כרטיס במאמרי העזרה של Google Workspace Add-ons API.
• ‫Card Service, שירות של Apps Script שמאפשר לסקריפטים להגדיר וליצור כרטיסים.
• ממשקים מבוססי-כרטיסים במסמכי התיעוד למפתחים של תוספים ל-Google Workspace.

חלק מווידג'טים של כרטיסים כוללים פונקציות ותכונות מיוחדות שספציפיות ל-Workspace Flows, שמפורטות במדריך הזה.

הגדרת כרטיס הגדרה

הגדרת כרטיס הגדרה במניפסט של Apps Script ובקוד.

בדוגמה הבאה מוצג איך ליצור כרטיס הגדרה שמבקש מהמשתמשים לבחור מרחב ב-Google Chat.

עריכת קובץ המניפסט

בקובץ המניפסט, מגדירים את workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

עריכת הקוד

מחזירים כרטיס בקוד של האפליקציה.

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

הגדרת השלמה אוטומטית לרכיבי קלט

אתם יכולים להגדיר השלמה אוטומטית לווידג'טים של SelectionInput כדי לעזור למשתמשים לבחור מתוך רשימת אפשרויות. לדוגמה, אם משתמש מתחיל להקליד Atl לתפריט שמאכלס ערים בארצות הברית, הרכיב יכול להציע אוטומטית Atlanta לפני שהמשתמש מסיים להקליד. אפשר להשלים אוטומטית עד 100 פריטים.

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

• השלמה אוטומטית בצד השרת: ההצעות מאוכלסות ממקור נתונים חיצוני או של צד שלישי שאתם מגדירים.
• נתונים מ-Google Workspace: ההצעות מגיעות ממקורות ב-Google Workspace, כמו משתמשי Google Workspace או מרחבים ב-Google Chat.

השלמה אוטומטית בצד השרת

אתם יכולים להגדיר את הווידג'ט SelectionInput כך שיציג הצעות להשלמה אוטומטית ממקור נתונים חיצוני. לדוגמה, אתם יכולים לעזור למשתמשים לבחור מתוך רשימה של לידים למכירות ממערכת לניהול קשרי לקוחות (CRM).

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

1. מגדירים את מקור הנתונים: בווידג'ט SelectionInput מוסיפים DataSourceConfig שמציין RemoteDataSource. ההגדרה הזו מצביעה על פונקציית Apps Script שמביאה הצעות להשלמה אוטומטית.
2. הטמעה של פונקציית ההשלמה האוטומטית: הפונקציה הזו מופעלת כשהמשתמש מקליד בשדה הקלט. הפונקציה צריכה לשלוח שאילתה למקור הנתונים החיצוני על סמך הקלט של המשתמש ולהחזיר רשימה של הצעות.

בדוגמה הבאה אפשר לראות איך מגדירים ווידג'ט SelectionInput להשלמה אוטומטית בצד השרת:

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

טיפול בבקשה להשלמה אוטומטית

הפונקציה שצוינה ב-setFunctionName (למשל, ‫getAutocompleteResults) מקבל אובייקט של אירוע כשהמשתמש מקליד בשדה. הפונקציה הזו צריכה:

1. בודקים את event.workflow.elementUiAutocomplete.invokedFunction כדי לוודא שהוא תואם לשם הפונקציה הצפוי.
2. מקבלים את הקלט של המשתמש מ-event.workflow.elementUiAutocomplete.query.
3. שולחים שאילתה למקור הנתונים החיצוני באמצעות השאילתה.
4. הפונקציה מחזירה עד 100 הצעות בפורמט הנדרש.

בדוגמה הבאה מוצג אופן ההטמעה של הפונקציה handleAutocompleteRequest() כדי להחזיר הצעות על סמך השאילתה של המשתמש:

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

השלמה אוטומטית של נתוני Google Workspace

אפשר גם למלא הצעות להשלמה אוטומטית מנתונים בסביבת Google Workspace של המשתמש:

• משתמשי Google Workspace: מאכלסים משתמשים באותו ארגון Google Workspace.
• מרחבים ב-Google Chat: מאכלסים את המרחבים ב-Google Chat שהמשתמש חבר בהם.

כדי להגדיר את האפשרות הזו, צריך להגדיר את הפרמטר PlatformDataSource בווידג'ט SelectionInput, ולציין את הפרמטר WorkflowDataSourceType כ-USER או כ-SPACE.

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

דוגמה: שילוב של סוגי השלמה אוטומטית

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

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

תכונות ספציפיות ל-Workspace Flows

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

TextInput ו-SelectionInput

לווידג'טים TextInput ו-SelectionInput יש את התכונות הספציפיות הבאות של Workspace Flows:

• ‫includeVariables: מאפיין בוליאני שמאפשר למשתמשים לבחור משתנים משלבים קודמים.
• ‫type: ערך ממוספר שמשלים אוטומטית הצעות. הערכים הנתמכים כוללים:
  • ‫USER: מספק הצעות להשלמה אוטומטית של אנשים שנמצאים באנשי הקשר של המשתמש.
  • ‫SPACE: מספק הצעות להשלמה אוטומטית של מרחבים ב-Google Chat שהמשתמש חבר בהם.

אם גם includeVariables וגם type מוגדרים, שדה הקלט משלב את החוויות שלהם. המשתמשים יכולים לבחור משתנה של ההתאמה type מתוך תפריט נפתח ולראות הצעות להשלמה אוטומטית שלו.

• 

  איור 1: משתמש בודק את ההצעות להשלמה אוטומטית כשהוא בוחר מרחב.

• 

  איור 2: משתמש בוחר את משתנה הפלט של שלב קודם מהתפריט הנפתח ➕משתנים.

שיקולים ומגבלות לגבי כרטיסים

• ניווט בכרטיסים כמו popCard(), pushCard() ו- updateCard() לא נתמך בתוספים שמרחיבים את התכונה 'זרימות'.

• כשמשתמשים ב-SelectionInput בכלי לבחירת משתנים, הווידג'טים תומכים רק ב-"type": "MULTI_SELECT". במקומות אחרים בכרטיסי ההגדרות, SelectionInput תומך בכל הערכים של SelectionType.

נושאים קשורים

• איך יוצרים שלב
• משתני קלט
• אימות משתנה קלט
• משתני פלט
• רישום פעילות ושגיאות ביומן
• אובייקט האירוע של Flows