このページは Cloud Translation API によって翻訳されました。

クイックスタート: Google Apps Script を使用して計算機ステップを作成する

このクイックスタートでは、Google Apps Script を使用して Workspace フローのカスタムステップを作成する方法について説明します。カスタムステップは、2 つの数値と算術演算を入力として受け取り、計算を実行して結果を出力します。

ユーザーがフローの一部として計算ステップを構成します。

図 1: ユーザーがフローの一部として計算ステップを構成する。

目標

Google Apps Script を使用して、Workspace フローのカスタムステップを作成します。
カスタムステップを独自の Google Workspace 組織にデプロイします。
Workspace Flows でカスタムフローのステップをテストします。

前提条件

Gemini アルファ版プログラムを通じて Workspace Flows にアクセスできる Google アカウント。

スクリプトを設定する

スクリプトを設定するには、新しい Apps Script プロジェクトを作成して、Cloud プロジェクトに接続します。

次のボタンをクリックして、フロー計算ツールのクイックスタート Apps Script プロジェクトを開きます。

プロジェクトを開く
[概要] をクリックします。
概要ページで、 [コピーを作成] をクリックします。
Apps Script プロジェクトのコピーに名前を付けます。
1. [Copy of Flows calculator quickstart] をクリックします。
2. [プロジェクトのタイトル] に「Flows calculator quickstart」と入力します。
3. [名前を変更] をクリックします。

省略可: クイックスタートコードを確認する

前のセクションでは、フローのカスタムステップに必要なすべてのアプリケーションコードを含む 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"
                }
              },
              {
                "id": "log",
                "description": "Logged result of flow event.",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculateFunction",
            "onExecuteFunction": "onExecuteCalculateFunction"
          }
        }
      ]
    }
  }
}

Calculator.gs

Google Workspace Flows のカスタムステップを定義します。「Calculate」という名前のステップは、2 つの数値と演算を入力として受け取り、計算結果を返します。

`Calculator.gs` コードを表示する

/**
 * This script defines a custom step for Google Workspace Flows.
 * 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/workflows/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 workflow.
 *
 * This function generates a button definition that, when clicked, triggers
 * a save action for the current workflow 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 workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 * This function is called when the user adds or edits the "Calculate" step in the Flows 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];
}

/**
 * Executes the calculation action based on the inputs from a workflow event.
 *
 * This function retrieves input values ("value1", "value2") and the "operation"
 * from the workflow event, performs the calculation, and returns the "result" and
 * "log" as output variables.
 * This function is called when the workflow execution reaches this custom step.
 * @param {Object} event The event object passed by the Flows runtime.
 * @return {Object} The output variables object.
 */
function onExecuteCalculateFunction(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = getIntValue(event.workflow.actionInvocation.inputs["value1"]);
  var value2 = getIntValue(event.workflow.actionInvocation.inputs["value2"]);
  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;
  }
  var renderAction = {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variableValues" : [
            {
              "variableId": "result",
              "integerValues": [
                calculatedValue
              ]
            }
          ]
        }
      }
    }
  };
}

ステップをデプロイしてテストする

ステップをテストするには、アドオンのテスト用デプロイを設定し、フローにステップを追加して、フローを実行します。

アドオンのテスト用デプロイを設定します。
1. Apps Script エディタでスクリプトプロジェクトを開きます。
2. [デプロイ] > [デプロイをテスト] をクリックします。
3. [インストール] をクリックします。
4. 下部にある [完了] をクリックします。
他のユーザーにアドオンをテストしてもらうには、Apps Script プロジェクトをそのユーザーのアカウントと共有します（編集権限が必要です）。その後、お客様に上記の手順をご案内します。

インストールすると、アドオンはフローですぐに使用できるようになります。アドオンが表示される前に、フローを更新する必要がある場合があります。アドオンを使用する前に、アドオンを承認する必要もあります。

テストデプロイの詳細については、未公開のアドオンをインストールするをご覧ください。
[フロー] を開きます。
ステップを含むフローを作成します。
1. 新しいフローをクリックします。
2. フローの開始方法を選択します。ステップをテストするときは、自分で開始できるスターター（自分宛にメールを送信するなど）を選択します。ステップに入力変数が必要な場合は、スターターの出力の一部として入力変数を構成します。
3. [ステップを追加] をクリックします。作成または更新したステップ（[Calculate]）を選択します。
4. ステップを構成します。計算ステップでは、2 つの値と算術演算を選択します。手順は自動的に保存されます。
5. ステップの出力をテストするには、別のステップを追加します。たとえば、メールメッセージに出力を追加するには、Gmail の [メッセージを送信] ステップを追加します。[メッセージ] で、 [変数] をクリックし、ステップの出力を選択します。計算ステップで、[変数] > [ステップ 2: 計算結果] > [計算結果] を選択します。変数は [メッセージ] フィールドにチップとして表示されます。
6. [有効にする] をクリックします。フローの実行準備が整いました。
フローの開始条件をトリガーして、フローを実行します。たとえば、メールを受信したときにフローが開始される場合は、自分宛てにメールを送信します。
フローが想定どおりに実行されることを確認します。ログを確認するには、フロービルダーの [アクティビティ] タブにアクセスします。[アクティビティ] タブでカスタムログを作成する方法については、アクティビティログをご覧ください。

次のステップ

Workspace フローのカスタムフローステップを作成して正常にテストできました。以下の操作を行えます。

Gemini にプロンプトを入力して、より複雑なロジックの実装をサポートしてもらい、手順のカスタマイズを続けます。
構成カードをビルドして、ステップ構成をカスタマイズします。
アクティビティとエラーをログに記録して、ステップ実行を記録し、トラブルシューティングします。
フローイベントオブジェクトを確認するで、フローの実行時にフローが送受信する JSON ペイロードを確認します。

クイックスタート: Google Apps Script を使用して計算機ステップを作成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標