このクイックスタートでは、Google Apps Script を使用して Workspace Studio のカスタム ステップを作成する方法について説明します。カスタムステップは、2 つの数値と算術演算を入力として受け取り、計算を実行して結果を出力します。
目標
- Google Apps Script を使用して、Workspace Studio のカスタム ステップを作成します。
- カスタムステップを独自の Google Workspace 組織にデプロイします。
- Workspace Studio でカスタムステップをテストします。
前提条件
- Workspace Studio にアクセスできる Google アカウント。
スクリプトを設定する
スクリプトを設定するには、新しい Apps Script プロジェクトを作成し、Cloud プロジェクトに接続します。
次のボタンをクリックして、Calculator クイックスタートの Apps Script プロジェクトを開きます。
[概要] をクリックします。
概要ページで、
[コピーを作成] をクリックします。Apps Script プロジェクトのコピーに名前を付けます。
[Copy of Calculator quickstart] をクリックします。
[プロジェクトのタイトル] に「
Calculator quickstart」と入力します。[名前を変更] をクリックします。
省略可: クイック スタート コードを確認する
前のセクションでは、エージェントのカスタムステップに必要なすべてのアプリケーション コードを含む Apps Script プロジェクト全体をコピーしたため、各ファイルをコピーして貼り付ける必要はありません。
必要に応じて、前のセクションでコピーした各ファイルをここで確認できます。
appsscript.jsonマニフェスト ファイル。Apps Script がスクリプトを実行するために必要な基本的なプロジェクト情報を指定する特別な JSON ファイル。
appsscript.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": "actionElement", "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": "onConfigCalculateFunction", "onExecuteFunction": "onExecuteCalculateFunction" } } ] } } }
Calculator.gsGoogle Workspace Studio のカスタムステップを定義します。「Calculate」という名前のステップは、2 つの数値と演算を入力として受け取り、計算結果を返します。
Calculator.gsコードを表示する/** * This script defines a custom step for Google Workspace Studio. * The step, named "Calculate", takes two numbers and an operation as input * and returns the result of the calculation. * * The script includes functions to: * * 1. Define the configuration UI for the step using Card objects: * * - `onConfigCalculateFunction()`: Generates the main configuration card. * - Helper functions like `pushCard()`, `saveButton()` to build card components. * * 2. Handle the execution of the step. * * - `onExecuteCalculateFunction()`: Retrieves inputs, performs the calculation, * and returns outputs. * * To learn more, see the following quickstart guide: * https://developers.google.com/workspace/add-ons/studio/quickstart */ /** * Creates an action response to push a new card onto the card stack. * * This function generates an action object that, when returned, causes the * provided card to be pushed onto the card stack, making it the currently * displayed card in the configuration UI. * @param {Object} card The Card object to push. * @return {Object} The action response object. */ function pushCard(card) { return { "action": { "navigations": [{ "push_card": card } ] } }; } /** * Creates an action response to update the currently displayed card. * * This function generates an action object that, when returned, causes the * currently displayed card to be replaced with the provided card in the * configuration UI. * @param {Object} card The Card object to update. * @return {Object} The render actions object. */ function updateCard(card) { return { "render_actions": { "action": { "navigations": [{ "update_card": card } ] } } }; } /** * Creates a button configuration object for saving the step. * * This function generates a button definition that, when clicked, triggers * a save action for the current step configuration. * @return {Object} The button widget object. */ function saveButton() { return { "text": "Save", "onClick": { "hostAppAction" : { "workflowAction" : { "saveWorkflowAction" : {} } } }, }; } /** * Creates a button configuration object for a refresh action. * * This function generates a button definition that, when clicked, triggers * a function to refresh the current card. * @param {string} functionName The name of the Apps Script function to call on click. * @return {Object} The button widget object. */ function refreshButton(functionName) { return { "text": "Refresh", "onClick": { "action" : { "function" : functionName } }, }; } /** * Generates and displays a configuration card for the sample calculation action. * * This function creates a card with input fields for two values and a dropdown * for selecting an arithmetic operation. The card also includes a "Save" * button to save the action configuration for the step. * * The input fields are configured to let the user select outputs from previous * steps as input values using the `hostAppDataSource` property. * This function is called when the user adds or edits the "Calculate" step in the UI. * @return {Object} The action response object containing the card to display. */ function onConfigCalculateFunction() { var card = { "sections": [ { "header": "Action sample: Calculate", "widgets": [ { "textInput": { "name": "value1", "label": "First value", "hostAppDataSource" : { "workflowDataSource" : { "includeVariables" : true } } } }, { "selectionInput": { "name": "operation", "label": "Operation", "type": "DROPDOWN", "items": [ { "text": "+", "value": "+", }, { "text": "-", "value": "-", }, { "text": "x", "value": "x", }, { "text": "/", "value": "/", } ] } }, { "textInput": { "name": "value2", "label": "Second value", "hostAppDataSource" : { "workflowDataSource" : { "includeVariables" : true } } } } ] } ] }; return pushCard(card); } /** * Gets an integer value from variable data, handling both string and integer formats. * * This function attempts to extract an integer value from the provided variable data. * It checks if the data contains string values and, if so, parses the first string * as an integer. If integer values are present, it returns the first integer. * @param {Object} variableData The variable data object from the event. * @return {number} The extracted integer value. */ function getIntValue(variableData) { if (variableData.stringValues) { return parseInt(variableData.stringValues[0]); } return variableData.integerValues[0]; } /** * 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 action based on the inputs from an event. * * This function retrieves input values ("value1", "value2") and the "operation" * from the event, performs the calculation, and returns the "result" and * "log" as output variables. * This function is called when the agent reaches this custom step. * @param {Object} event The event object passed by the runtime. * @return {Object} The output variables object. */ function onExecuteCalculateFunction(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 プロジェクトをそのユーザーのアカウントと共有します（編集権限が必要です）。その後、お客様に上記の手順をご案内します。
インストールすると、アドオンは Agents で直ちに使用できるようになります。アドオンが表示される前に、エージェントの更新が必要になることがあります。アドオンを使用する前に、アドオンを承認する必要もあります。
テスト デプロイの詳細については、未公開のアドオンをインストールするをご覧ください。
[エージェント] を開きます。
ステップを含むエージェントを作成します。
- [New agent] をクリックします。
- エージェントの起動方法を選択します。ステップをテストするときは、自分で開始できるスターター（自分宛にメールを送信するなど）を選択します。ステップに入力変数が必要な場合は、スターターの出力の一部として入力変数を構成します。
- [ステップを追加] をクリックします。作成または更新したステップ（[Calculate]）を選択します。
- ステップを構成します。計算ステップでは、2 つの値と算術演算を選択します。手順は自動的に保存されます。
- ステップの出力をテストするには、別のステップを追加します。たとえば、メール メッセージに出力を追加するには、Gmail の [メッセージを送信] ステップを追加します。[メッセージ] で、 [変数] をクリックし、ステップの出力を選択します。計算ステップで、[変数] > [ステップ 2: 計算結果] > [計算結果] を選択します。変数は [メッセージ] フィールドにチップとして表示されます。
- [有効にする] をクリックします。エージェントを実行する準備が整いました。
エージェントのスターターを起動して、エージェントを実行します。たとえば、メールを受信したときにエージェントが起動する場合は、自分宛てにメールを送信します。
エージェントが想定どおりに実行されることを確認します。ログを確認するには、エージェント ビルダーの [アクティビティ] タブにアクセスします。[アクティビティ] タブでカスタムログを作成する方法については、アクティビティ ログをご覧ください。
次のステップ
Workspace Studio のカスタム ステップを作成してテストできました。以下の操作を行えます。
Gemini にプロンプトを送信して、より複雑なロジックの実装をサポートしてもらい、手順のカスタマイズを続けます。
構成カードを作成して、ステップ構成をカスタマイズします。
アクティビティとエラーをログに記録して、ステップ実行を記録し、トラブルシューティングします。
イベント オブジェクトを確認する: エージェントがステップの実行中に送受信する JSON ペイロードを確認します。