このガイドでは、ユーザーが Google Workspace Studio のフローに追加できるステップを作成する方法について説明します。
ステップとは、フローの一連のタスクの 1 つのステップのことです。ステップからフローを開始することはできません。
たとえば、算術演算を行うステップがあるとします。ユーザーに 2 つの値と算術演算の入力を求めます。次に、値に対して算術演算を行い、結果を出力します。
ステップをビルドするには、アドオンのマニフェスト ファイルで構成し、Google Workspace アドオンのコードでアプリケーション ロジックを記述して、ステップをデプロイしてテストします。
ステップを定義する
ステップを構成するには、マニフェスト ファイルで定義し、コードでアプリケーション ロジックを記述します。
マニフェスト ファイルでステップを定義する
マニフェスト ファイル appsscript.json で、次の操作を行います。
onConfigFunctionとonExecuteFunctionを、アドオンのコード内の対応する関数の名前に設定します。この例では、関数はonConfigCalculateとonExecuteCalculateと呼ばれます。onConfigFunctionは、ステップを設定して構成します。必要に応じて、メールの送信先アドレスなど、ステップの実行に必要なデータをユーザーから収集します。このガイドの例では、2 つの値と算術演算を指定します。onExecuteFunctionは、ステップを実行します。ユーザーからデータが収集された場合、そのデータはこの関数に渡されます。該当する場合は、出力を返します。このガイドの例では、算術演算の結果を返します。
必要な入力と出力を設定します。これにより、ステップでデータを収集して、後続のステップに送信できます。この例では、
inputs[]で定義された 2 つの値と算術演算の入力をユーザーに求めます。outputs[]で定義されている計算結果を出力します。入力と出力の詳細については、 入力変数と 出力変数をご覧ください。 フローがエラーなく実行されるようにするには、 入力変数を検証します。
計算ステップのマニフェスト ファイルは次のとおりです。
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Calculator",
"logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "calculatorDemo",
"state": "ACTIVE",
"name": "Calculate",
"description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "value1",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "value2",
"description": "value2",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "operation",
"description": "operation",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"outputs": [
{
"id": "result",
"description": "Calculated result",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
}
],
"onConfigFunction": "onConfigCalculate",
"onExecuteFunction": "onExecuteCalculate"
}
}
]
}
}
}
次に、コードでステップを定義して、サポート コードを記述します。
コードでステップを定義する
アプリケーション コードで、次の操作を行います。
onConfigFunctionを記述します。この例ではonConfigCalculateと呼ばれます。ユーザーがフローにステップを追加すると、フロービルダーでステップの側面を構成できます。 必要な情報をユーザーから収集するために、onConfigFunctionは構成カードを定義します。カードは、アドオンのユーザー インターフェースの構成要素です。 カードは、定義されたレイアウト、ボタンなどのインタラクティブな UI 要素、画像などのリッチメディアをサポートしています。カードを使用すると、メールの送信に使用するメールアドレスなど、ステップの実行に必要なデータをユーザーから取得できます。
onConfigFunctionはカードを返します。このカードは、ユーザーがステップのデータを設定する UI を定義します。この例では、onConfigFunctionは、2 つの値と算術演算の入力を求めるカードをビルドします。onExecuteFunctionを記述します。この例ではonExecuteCalculateと呼ばれます。フローでステップが実行されると、onExecuteFunctionが実行されます。onConfigFunctionで定義されているように、ユーザーが構成時に設定した入力値はonExecuteFunctionに渡されます。指定された入力を使用してタスクを同期的に実行するように
onExecuteFunctionを記述します。onExecuteFunctionは、フローのマニフェストで定義されているすべての出力を返す必要があります。そうしないと、エラーが発生します。
このコードサンプルには、提供された変数をステップからの出力として構築して送信するサポート関数 outputVariables が含まれています。
ステップのテストの準備ができました。
計算ステップのコードは次のとおりです。
Apps Script
/**
* Generates and displays a configuration card for the sample calculation step.
*
* This function creates a card with input fields for two values and a drop-down
* for selecting an arithmetic operation.
*
* The input fields are configured to let the user select outputs from previous
* steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
const firstInput = CardService.newTextInput()
.setFieldName("value1")
.setTitle("First Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const secondInput = CardService.newTextInput()
.setFieldName("value2")
.setTitle("Second Value").setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const selectionInput = CardService.newSelectionInput()
.setTitle("operation")
.setFieldName("operation")
.setType(CardService.SelectionInputType.DROPDOWN)
.addItem("+", "+", false)
.addItem("-", "-", true)
.addItem("x", "x", false)
.addItem("/", "/", false);
const sections = CardService.newCardSection()
.setHeader("Action_sample: Calculate")
.setId("section_1")
.addWidget(firstInput)
.addWidget(selectionInput)
.addWidget(secondInput)
var card = CardService.newCardBuilder()
.addSection(sections)
.build();
return card;
}
/**
* Returns output variables from a step.
*
* This function constructs an object that, when returned, sends the
* provided variable values as output from the current step.
* The variable values are logged to the console for debugging purposes.
*/
function outputVariables(variableDataMap) {
const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
.setVariableDataMap(variableDataMap);
const hostAppAction = AddOnsResponseService.newHostAppAction()
.setWorkflowAction(workflowAction);
const renderAction = AddOnsResponseService.newRenderActionBuilder()
.setHostAppAction(hostAppAction)
.build();
return renderAction;
}
/**
* Executes the calculation step based on the inputs from a flow event.
*
* This function retrieves input values and the operation from the flow event,
* performs the calculation, and returns the result as an output variable.
* The function logs the event for debugging purposes.
*/
function onExecuteCalculate(event) {
console.log("output: " + JSON.stringify(event));
var calculatedValue = 0;
var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];
if (operation == "+") {
calculatedValue = value1 + value2;
} else if (operation == "-") {
calculatedValue = value1 - value2;
} else if (operation == "x") {
calculatedValue = value1 * value2;
} else if (operation == "/") {
calculatedValue = value1 / value2;
}
const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };
return outputVariables(variableDataMap);
}
ステップをテストする
ステップをテストするには、アドオンのテスト デプロイを設定し、フローにステップを追加して、フローを実行します。
アドオンのテスト デプロイを設定します。
- Apps Script エディタでスクリプト プロジェクトを開きます。
- [デプロイ] > [テスト デプロイ] をクリックします。
- [インストール] をクリックします。
- 下部にある [完了] をクリックします。
他のユーザーがアドオンをテストできるようにするには、Apps Script プロジェクトをそのアカウントと共有します（編集権限が必要です）。次に、上記の手順を行うようユーザーに促します。
インストールすると、アドオンはフローですぐに使用できるようになります。アドオンが表示される前に、フローの更新が必要になる場合があります。アドオンを使用する前に、アドオンを承認する必要があります。
テスト デプロイの詳細については、公開されていないアドオンをインストールするをご覧ください。
フローを開きます。
ステップを含むフローを作成します。
- [New flow] をクリックします。
- フローの開始方法を選択します。ステップをテストする場合は、メールを送信するなど、自分で開始できる開始条件を選択することをおすすめします。ステップに入力変数が必要な場合は、スターターの出力の一部として入力変数を構成します。
- [**ステップを追加**] をクリックします。ビルドまたは更新したステップ（[計算]）を選択します。
- ステップを構成します。計算ステップの場合は、2 つの値と算術演算を選択します。ステップは自動的に保存されます。
- ステップの出力をテストするには、別のステップを追加します。たとえば、メール メッセージに出力を追加するには、Gmail の [メッセージを送信] ステップを追加します。[**メッセージ**] で、 [**変数**] をクリックし、 ステップの出力選択します。計算ステップの場合は、 [Variables] > [Step 2: Calculated result] > [Calculated result] を選択します。変数は、[メッセージ] フィールドにチップとして表示されます。
- [有効にする] をクリックします。フローの実行準備が整いました。
フローの開始条件を開始して、フローを実行します。たとえば、メールを受信したときにフローが開始される場合は、自分にメールを送信します。
フローが想定どおりに実行されることを確認します。フロービルダーの [アクティビティ] タブにアクセスしてログを確認します。 [アクティビティ] タブでカスタムログを作成する方法については、 [アクティビティ ログ]をご覧ください。