이 가이드에서는 사용자가 Google Workspace Studio의 단계를 맞춤설정하고 입력할 수 있는 구성 카드를 빌드하는 방법을 설명합니다.
일반적으로 구성 카드를 빌드하려면 다른 Google Workspace 부가기능과 마찬가지로 카드 인터페이스를 빌드합니다. 구성 카드 인터페이스를 빌드하는 데 도움이 필요하면 다음을 참고하세요.
- 카드 빌더: 카드를 빌드하고 정의하는 데 도움이 되는 대화형 도구입니다.
- Google Workspace 부가기능 API 참조 문서의 카드
- 카드 서비스: 스크립트에서 카드를 구성하고 빌드할 수 있는 Apps Script 서비스입니다.
- Google Workspace 부가기능 개발자 문서의 카드 기반 인터페이스
일부 카드 위젯에는 이 가이드에 자세히 설명된 Workspace Studio 전용 기능이 있습니다.
구성 카드 정의
Apps Script 매니페스트와 코드 모두에서 구성 카드를 정의합니다.
다음 예에서는 사용자에게 Google Chat 스페이스를 선택하라는 메시지를 표시하는 구성 카드를 빌드하는 방법을 보여줍니다.
매니페스트 파일 수정
매니페스트 파일에서 workflowElements를 정의합니다.
JSON
{
"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"
}
}
]
}
}
}
코드 수정하기
애플리케이션 코드에서 카드를 반환합니다.
Apps Script
/**
* 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을 자동 추천할 수 있습니다. 최대 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
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 ...
}
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 함수를 보여줍니다.
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Autocomplete Demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "autocomplete_demo",
"state": "ACTIVE",
"name": "Autocomplete Demo",
"description": "Provide autocompletion in input fields",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "A multi-select field with autocompletion",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigAutocomplete",
"onExecuteFunction": "onExecuteAutocomplete"
}
}
]
}
}
}
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
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();
}
변수 선택기 버튼 맞춤설정
버튼 크기와 라벨을 설정하여 변수 선택기 버튼을 맞춤설정할 수 있습니다.
버튼 크기
버튼 크기를 설정하려면 다음 VariableButtonSize 열거형 중 하나와 함께 setVariableButtonSize()를 사용하세요.
UNSPECIFIED: 기본값입니다. 버튼은 측면 패널에서는 콤팩트하고 다른 컨텍스트에서는 전체 크기입니다.COMPACT: 버튼에 더하기 기호 (+)만 표시됩니다.FULL_SIZE: 버튼에 전체 텍스트 라벨이 표시됩니다.
버튼 라벨
버튼 텍스트를 설정하려면 setVariableButtonLabel()를 사용합니다.
예: 변수 선택기 맞춤설정
다음 예에서는 다양한 변수 선택기 버튼 크기와 맞춤 라벨을 사용하여 TextInput 위젯을 구성하는 방법을 보여줍니다.
-
그림 1: 웹의 변수 선택기 버튼 맞춤설정 -
그림 2: 부가기능 측면 패널의 변수 선택기 버튼 맞춤설정
변수 선택기 버튼을 맞춤설정하기 위한 매니페스트 파일은 다음과 같습니다.
JSON
{
"timeZone": "America/Los_Angeles",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/script.locale"
],
"addOns": {
"common": {
"name": "Variable button customization",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "variable_picker_customization",
"state": "ACTIVE",
"name": "Variable Picker demo",
"description": "List all possible variable picker customization options",
"workflowAction": {
"onConfigFunction": "onUpdateCardConfigFunction",
"onExecuteFunction": "onUpdateCardExecuteFunction"
}
}
]
}
}
}
다음은 변수 선택기 버튼을 맞춤설정하는 코드입니다.
Apps Script
function onUpdateCardConfigFunction(event) {
const textInput1 = CardService.newTextInput()
.setFieldName("value1")
.setTitle("Regular variable picker button")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput2 = CardService.newTextInput()
.setFieldName("value2")
.setTitle("Size: Unspecified")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput3 = CardService.newTextInput()
.setFieldName("value3")
.setTitle("Size: Full size")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
)
);
const textInput4 = CardService.newTextInput()
.setFieldName("value4")
.setTitle("Size: Compact")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
)
);
const textInput5 = CardService.newTextInput()
.setFieldName("value5")
.setTitle("Custom button label")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonLabel("New button label!")
)
);
var cardSection = CardService.newCardSection()
.addWidget(textInput1)
.addWidget(textInput2)
.addWidget(textInput3)
.addWidget(textInput4)
.addWidget(textInput5)
.setId("section_1");
var card = CardService.newCardBuilder().addSection(cardSection).build();
return card;
}
function onUpdateCardExecuteFunction(event) {
}
Workspace Studio 전용 기능
일부 카드 위젯에는 Workspace Studio 전용 기능이 있으며 자세한 내용은 여기를 참고하세요.
TextInput 및 SelectionInput
TextInput 및 SelectionInput 위젯에는 다음과 같은 Workspace Studio 전용 기능이 있습니다.
includeVariables: 사용자가 이전 단계에서 변수를 선택할 수 있도록 하는 불리언 속성입니다. 이후 단계에서 변수 선택기가 표시되려면 시작 이벤트와 하나 이상의 해당 출력 변수가 모두 변수에 매핑되어야 합니다.type: 추천을 자동 완성하는 열거형 값입니다. 지원되는 값은 다음과 같습니다.USER: 사용자 연락처에 있는 사람에 대한 자동 완성 추천을 제공합니다.SPACE: 사용자가 회원으로 속한 Google Chat 스페이스에 대한 자동 완성 제안을 제공합니다.
includeVariables와 type이 모두 설정되면 입력 필드에서 두 환경을 결합합니다. 사용자는 드롭다운 메뉴에서 일치하는 type의 변수를 선택하고 자동 완성 추천을 확인할 수 있습니다.
-
그림 3: 사용자가 스페이스를 선택할 때 자동 완성 추천을 검토합니다. -
그림 4: 사용자가 ➕변수 드롭다운에서 이전 단계의 출력 변수를 선택합니다.
더보기 메뉴를 사용하여 출력 변수를 하나만 선택
사용자가 오버플로 메뉴를 사용하여 이전 단계에서 단일 출력 변수를 선택할 수 있도록 SelectionInput 위젯을 구성할 수 있습니다.
SelectionInputType를 OVERFLOW_MENU로 설정하면 위젯이 전용 변수 선택기로 작동합니다. 변수 값을 문자열로 변환하는 TextInput와 함께 includeVariables를 사용하는 것과 달리 OVERFLOW_MENU는 선택한 변수의 원래 데이터 유형을 유지합니다.
Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
사용자가 텍스트와 출력 변수를 결합하도록 허용
setInputMode()를 사용하여 사용자가 텍스트 및 출력 변수와 상호작용하는 방식을 제어하도록 TextInput 위젯을 구성할 수 있습니다.
RICH_TEXT: 사용자가 텍스트와 출력 변수를 결합할 수 있습니다. 결과는 연결된 단일 문자열입니다.PLAIN_TEXT: 입력을 제한합니다. 사용자는 텍스트를 입력하거나 단일 출력 변수를 선택할 수 있습니다. 변수를 선택하면 기존 텍스트가 대체됩니다. 이 모드를 사용하여 매니페스트에 정의된 특정 데이터 유형을 적용합니다.
다음 이미지는 두 개의 TextInput 위젯을 보여줍니다. 첫 번째는 RICH_TEXT로 구성되며 텍스트와 출력 변수가 있습니다. 두 번째는 PLAIN_TEXT로 구성되어 있으며 출력 변수만 허용합니다.
-
그림 5: RICH_TEXT및PLAIN_TEXT로 구성된 텍스트 입력 위젯
모든 TextInput 위젯의 입력 모드를 명시적으로 설정하는 것이 좋습니다.
다음은 입력 모드가 다른 TextInput 위젯을 구성하는 매니페스트 파일입니다.
JSON
{
"timeZone": "America/Toronto",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Text and output variable demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "richTextDemo",
"state": "ACTIVE",
"name": "Rich Text Demo",
"description": "Show the difference between rich text and plain text TextInput widgets",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "First user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
},
{
"id": "value2",
"description": "Second user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfiguration",
"onExecuteFunction": "onExecution"
}
}
]
}
}
}
다음은 다양한 입력 모드로 TextInput 위젯을 구성하는 코드입니다.
Apps Script
function onConfiguration() {
const input1 = CardService.newTextInput()
.setFieldName("value1")
.setId("value1")
.setTitle("Rich Text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to RICH_TEXT to allow mixed text and variables.
.setInputMode(CardService.TextInputMode.RICH_TEXT);
const input2 = CardService.newTextInput()
.setFieldName("value2")
.setId("value2")
.setTitle("Plain text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to PLAIN_TEXT to enforce single variable selection.
.setInputMode(CardService.TextInputMode.PLAIN_TEXT);
const section = CardService.newCardSection()
.addWidget(input1)
.addWidget(input2);
const card = CardService.newCardBuilder()
.addSection(section)
.build();
return card;
}
function onExecution(e) {
}
카드 고려사항 및 제한사항
Workspace Studio를 확장하는 부가기능에서는
popCard(),pushCard(),updateCard()과 같은 카드 탐색이 지원되지 않습니다.SelectionInput이 변수 선택기에서 사용되는 경우 위젯은"type": "MULTI_SELECT"만 지원합니다. 구성 카드에서 다른 곳에서는SelectionInput가SelectionType의 모든 값을 지원합니다.