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

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

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

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

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

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

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

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

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

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

جی‌سون 

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "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": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

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

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

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

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

تنظیم تکمیل خودکار برای ابزارک‌های ورودی

شما می‌توانید قابلیت تکمیل خودکار را برای ویجت‌های 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
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// 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 ...
}

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