ساخت کارت پیکربندی برای یک مرحله

این راهنما نحوه ساخت یک کارت پیکربندی را توضیح می‌دهد که به کاربران امکان می‌دهد ورودی‌ها را برای یک مرحله در Google Workspace Flows سفارشی‌سازی و ارائه دهند.

به طور کلی، برای ساخت یک کارت پیکربندی، شما یک رابط کارت مانند هر افزونه‌ی دیگر Google Workspace می‌سازید. برای کمک به ساخت رابط‌های کارت پیکربندی، به موارد زیر مراجعه کنید:

  • سازنده کارت ، ابزاری تعاملی که به شما در ساخت و تعریف کارت‌ها کمک می‌کند.
  • کارت در مستندات مرجع API افزونه‌های Google Workspace.
  • سرویس کارت ، یک سرویس اسکریپت برنامه‌ها که به اسکریپت‌ها اجازه می‌دهد کارت‌ها را پیکربندی و بسازند.
  • رابط‌های مبتنی بر کارت در مستندات توسعه‌دهندگان افزونه‌های Google Workspace.

برخی از ویجت‌های کارت، قابلیت‌ها و ویژگی‌های خاص Workspace Flows را دارند که در این راهنما به تفصیل شرح داده شده‌اند.

تعریف کارت پیکربندی

یک کارت پیکربندی را هم در مانیفست Apps Script و هم در کد تعریف کنید.

مثال زیر نحوه ساخت یک کارت پیکربندی را نشان می‌دهد که از کاربران می‌خواهد یک فضای چت گوگل را انتخاب کنند.

فایل مانیفست را ویرایش کنید

در فایل مانیفست، workflowElements تعریف کنید.

جی‌سون 

{
  "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"
          }
        }
      ]
    }
  }
}

کد را ویرایش کنید

در کد برنامه، یک کارت را برگردانید.

اسکریپت برنامه‌ها 

/**
* 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 پیشنهاد دهد. شما می‌توانید تا ۱۰۰ مورد را به طور خودکار تکمیل کنید.

پیشنهادهای تکمیل خودکار می‌توانند از منابع داده زیر باشند:

  • تکمیل خودکار سمت سرور: پیشنهادات از یک منبع داده شخص ثالث یا خارجی که شما تعریف می‌کنید، پر می‌شوند.
  • داده‌های Google Workspace: پیشنهادها از منابع Google Workspace، مانند کاربران Google Workspace یا فضاهای Google Chat، پر می‌شوند.

تکمیل خودکار سمت سرور

شما می‌توانید ویجت SelectionInput را طوری پیکربندی کنید که پیشنهادات را از یک منبع داده خارجی به صورت خودکار تکمیل کند. به عنوان مثال، می‌توانید به کاربران کمک کنید تا از لیست سرنخ‌های فروش از یک سیستم مدیریت ارتباط با مشتری (CRM) انتخاب کنند.

برای پیاده‌سازی تکمیل خودکار سمت سرور، باید:

  1. تعریف منبع داده: در ویجت SelectionInput ، یک DataSourceConfig اضافه کنید که یک RemoteDataSource را مشخص می‌کند. این پیکربندی به یک تابع Apps Script اشاره می‌کند که پیشنهادات تکمیل خودکار را دریافت می‌کند.
  2. پیاده‌سازی تابع تکمیل خودکار: این تابع زمانی فعال می‌شود که کاربر در فیلد ورودی تایپ کند. این تابع باید بر اساس ورودی کاربر، از منبع داده خارجی شما پرس‌وجو کند و لیستی از پیشنهادات را برگرداند.

مثال زیر نحوه پیکربندی ویجت SelectionInput را برای تکمیل خودکار سمت سرور نشان می‌دهد:

اسکریپت برنامه‌ها 

// 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. حداکثر ۱۰۰ پیشنهاد را در قالب مورد نیاز ارسال کنید.

مثال زیر نحوه پیاده‌سازی تابع handleAutocompleteRequest() را برای بازگرداندن پیشنهادات بر اساس پرس‌وجوی کاربر نشان می‌دهد:

اسکریپت برنامه‌ها 

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 جمع کنید.
  • فضاهای چت گوگل: فضاهای چت گوگل را که کاربر عضو آن است، پر کنید.

برای پیکربندی این مورد، PlatformDataSource در ویجت SelectionInput تنظیم کنید و WorkflowDataSourceType به صورت USER یا SPACE مشخص کنید.

اسکریپت برنامه‌ها 

// 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 ایجاد می‌کند و تکمیل خودکار سمت سرور، کاربر و فضا را نشان می‌دهد:

اسکریپت برنامه‌ها 

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 دارای این ویژگی‌های مختص Workspace Flows هستند:

  • includeVariables : یک ویژگی بولی که به کاربران اجازه می‌دهد متغیرها را از مراحل قبلی انتخاب کنند.
  • type : یک مقدار شمارشی که پیشنهادات را به صورت خودکار تکمیل می‌کند. مقادیر پشتیبانی شده عبارتند از:
    • USER : پیشنهادهای تکمیل خودکار را برای افراد موجود در مخاطبین کاربر ارائه می‌دهد.
    • SPACE : پیشنهادهای تکمیل خودکار برای فضاهای چت گوگل که کاربر عضو آنهاست، ارائه می‌دهد.

وقتی هر دو includeVariables و type تنظیم شوند، فیلد ورودی تجربیات آنها را ترکیب می‌کند. کاربران می‌توانند متغیری با type منطبق را از منوی کشویی انتخاب کنند و پیشنهادات تکمیل خودکار را برای آن مشاهده کنند.

  • پیشنهادهای تکمیل خودکار برای فضای چت گوگل.
    شکل ۱: یک کاربر هنگام انتخاب یک فضا، پیشنهادات تکمیل خودکار را بررسی می‌کند.
  • منوی متغیرها به کاربران اجازه می‌دهد متغیرهای خروجی را از مراحل قبلی انتخاب کنند.
    شکل ۲: کاربر متغیر خروجی مرحله قبل را از منوی کشویی ➕Variables انتخاب می‌کند.

ملاحظات و محدودیت‌های کارت

  • پیمایش کارت‌ها مانند popCard() ، pushCard() و updateCard() در افزونه‌هایی که Flows را بسط می‌دهند پشتیبانی نمی‌شوند.

  • وقتی SelectionInput در یک انتخابگر متغیر استفاده می‌شود، ویجت‌ها فقط از "type": "MULTI_SELECT" پشتیبانی می‌کنند. در جای دیگر کارت‌های پیکربندی، SelectionInput از تمام مقادیر SelectionType پشتیبانی می‌کند.