이 페이지는 Cloud Translation API를 통해 번역되었습니다.

단계의 구성 카드 빌드

이 가이드에서는 사용자가 Google Workspace Flows의 단계를 맞춤설정하고 입력을 제공할 수 있는 구성 카드를 빌드하는 방법을 설명합니다.

일반적으로 구성 카드를 빌드하려면 다른 Google Workspace 부가기능과 마찬가지로 카드 인터페이스를 빌드합니다. 구성 카드 인터페이스를 빌드하는 데 도움이 필요하면 다음을 참고하세요.

카드 빌더: 카드를 빌드하고 정의하는 데 도움이 되는 대화형 도구입니다.
Google Workspace 부가기능 API 참조 문서의 카드
카드 서비스: 스크립트에서 카드를 구성하고 빌드할 수 있는 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 Chat 스페이스와 같은 Google Workspace 소스에서 추천이 채워집니다.

서버 측 자동 완성

외부 데이터 소스의 추천을 자동 완성하도록 SelectionInput 위젯을 구성할 수 있습니다. 예를 들어 사용자가 고객 관계 관리 (CRM) 시스템의 영업 리드 목록에서 선택할 수 있도록 지원할 수 있습니다.

서버 측 자동 완성을 구현하려면 다음을 수행해야 합니다.

데이터 소스 정의: SelectionInput 위젯에서 RemoteDataSource를 지정하는 DataSourceConfig를 추가합니다. 이 구성은 자동 완성 추천을 가져오는 Apps Script 함수를 가리킵니다.
자동 완성 기능 구현: 이 기능은 사용자가 입력란에 입력할 때 트리거됩니다. 이 함수는 사용자의 입력을 기반으로 외부 데이터 소스를 쿼리하고 추천 목록을 반환해야 합니다.

다음 예시에서는 서버 측 자동 완성을 위해 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)는 사용자가 필드에 입력할 때 이벤트 객체를 수신합니다. 이 함수는 다음을 충족해야 합니다.

event.workflow.elementUiAutocomplete.invokedFunction를 확인하여 예상 함수 이름과 일치하는지 확인합니다.
event.workflow.elementUiAutocomplete.query에서 사용자의 입력을 가져옵니다.
쿼리를 사용하여 외부 데이터 소스를 쿼리합니다.
필수 형식으로 최대 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 스페이스를 채웁니다.

이를 구성하려면 SelectionInput 위젯에서 PlatformDataSource를 설정하여 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)
            ))
    );

예: 자동 완성 유형 결합

다음 예에서는 서버 측, 사용자, 스페이스 자동 완성 기능을 보여주는 세 개의 SelectionInput 위젯이 있는 카드를 만드는 onConfig 함수를 보여줍니다.

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의 모든 값을 지원합니다.

단계의 구성 카드 빌드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

구성 카드 정의

매니페스트 파일 수정

JSON

코드 수정하기

Apps Script

입력 위젯의 자동 완성 설정

서버 측 자동 완성

Apps Script

자동 완성 요청 처리

Apps Script

Google Workspace 데이터 자동 완성

Apps Script

예: 자동 완성 유형 결합

Apps Script

Workspace Flows 관련 기능

TextInput 및 SelectionInput

카드 고려사항 및 제한사항

관련 주제

단계의 구성 카드 빌드