Guia de início rápido: criar uma etapa de calculadora com o Google Apps Script

Programa Gemini Alpha:o recurso Fluxos está disponível como parte do programa Gemini Alpha.

Neste guia de início rápido, você vai aprender a criar uma etapa personalizada para o Workspace Flows usando o Google Apps Script. A etapa personalizada recebe dois números e uma operação aritmética como entrada, realiza o cálculo e gera o resultado.

Figura 1:um usuário configura a etapa da calculadora como parte de um fluxo.

Objetivos

• Crie uma etapa personalizada para o Workspace Flows com o Google Apps Script.
• Implante a etapa personalizada na sua organização do Google Workspace.
• Teste a etapa de fluxo personalizada no Workspace Flows.

Pré-requisitos

• Uma Conta do Google com acesso ao Workspace Flows pelo programa Gemini Alpha.

Configurar o script

Para configurar o script, crie um projeto do Apps Script e conecte-o ao seu projeto do Cloud.

1. Clique no botão a seguir para abrir o projeto do Apps Script Início rápido da calculadora de fluxos.

   Abrir o projeto

2. Clique em Visão geral.

3. Na página de visão geral, clique em Fazer uma cópia.

4. Dê um nome à sua cópia do projeto do Apps Script:

   1. Clique em Cópia do guia de início rápido da calculadora de fluxos.

   2. Em Título do projeto, digite Flows calculator quickstart.

   3. Clique em Renomear.

Opcional: revisar o código do guia de início rápido

Na seção anterior, você copiou um projeto inteiro do Apps Script que contém todo o código de aplicativo necessário para a etapa personalizada do fluxo. Portanto, não é preciso copiar e colar cada arquivo.

Se quiser, revise cada arquivo copiado na seção anterior aqui:

appsscript.json

O arquivo de manifesto. Um arquivo JSON especial que especifica informações básicas do projeto necessárias para o Apps Script executar o script.

Ver o código 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

Define uma etapa personalizada para o Google Workspace Flows. A etapa, chamada "Calcular", recebe dois números e uma operação como entrada e retorna o resultado do cálculo.

Ver o código 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
              ]
            }
          ]
        }
      }
    }
  };
}

Implantar e testar a etapa

Para testar a etapa, configure uma implantação de teste para seu complemento, adicione a etapa a um fluxo e execute o fluxo.

1. Configure uma implantação de teste para seu complemento:

   1. Abra o projeto de script no editor do Apps Script.
   2. Clique em Implantar > Testar implantações.
   3. Clique em Instalar.
   4. Na parte de baixo, clique em Concluído.

   Você pode permitir que outros usuários testem o complemento compartilhando o projeto do Apps Script com a conta deles (é necessário ter acesso de edição). Em seguida, peça para os usuários seguirem as etapas anteriores.

   Depois de instalado, o complemento fica disponível imediatamente no Flows. Talvez seja necessário atualizar o Flow antes que o complemento apareça. Você também precisa autorizar o uso do complemento.

   Para saber mais sobre implantações de teste, consulte Instalar um complemento não publicado.

2. Abra "Fluxos".

3. Crie um fluxo que inclua sua etapa:

   1. Clique em Novo fluxo.
   2. Selecione como o fluxo começa. Ao testar uma etapa, escolha um gatilho que você possa acionar, como enviar um e-mail para si mesmo. Se a etapa exigir uma variável de entrada, configure-a como parte da saída do iniciador.
   3. Clique em Adicionar etapa. Selecione a etapa criada ou atualizada, chamada Calcular.
   4. Configure a etapa. Para a etapa de cálculo, escolha dois valores e uma operação matemática. A etapa é salva automaticamente.
   5. Para testar a saída da etapa, adicione outra. Por exemplo, para adicionar uma saída a uma mensagem de e-mail, você pode adicionar a etapa Enviar uma mensagem do Gmail. Em Mensagem, clique em Variáveis e selecione a saída da etapa. Para a etapa de cálculo, selecione Variáveis > Etapa 2: resultado calculado > Resultado calculado. A variável aparece como um ícone no campo Mensagem.
   6. Clique em Ativar. Seu fluxo está pronto para ser executado.

4. Execute o fluxo ativando o início dele. Por exemplo, se o fluxo começar quando você receber um e-mail, envie um e-mail para si mesmo.

5. Verifique se o fluxo é executado conforme o esperado. Para verificar os registros, acesse a guia Atividade do criador de fluxos. Para saber como criar registros personalizados na guia "Atividade", consulte Registros de atividades.

Próximas etapas

Você criou e testou uma etapa de fluxo personalizada para o Workspace Flows. Agora você pode:

• Continue personalizando a etapa pedindo ajuda ao Gemini para implementar uma lógica mais complexa.

• Crie um card de configuração para personalizar a configuração da etapa.

• Registre atividades e erros para gravar e resolver problemas nas execuções de etapas.

• Analise os objetos de evento de fluxo para analisar o payload JSON que os fluxos enviam e recebem durante a execução.