このガイドでは、Google Workspace Studio のステップでユーザーがカスタマイズして入力を行える構成カードを作成する方法について説明します。
一般に、構成カードをビルドするには、他の Google Workspace アドオンと同様にカード インターフェースをビルドします。構成カード インターフェースの作成については、以下をご覧ください。
- カード作成ツール: カードの作成と定義に役立つインタラクティブなツール。
- Google Workspace アドオン API リファレンス ドキュメントの Card。
- カードサービス: スクリプトでカードを構成して作成できる 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 ...
}
カードに関する考慮事項と制限事項
- Workspace Studio を拡張するアドオンでは、
popCard()、pushCard()、updateCard()などのカード ナビゲーションはサポートされていません。