Esta página foi traduzida pela API Cloud Translation.

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

Este guia de início rápido ensina a criar uma etapa personalizada para o Workspace Studio 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.

Um usuário configura a etapa da calculadora como parte de um agente.

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

Objetivos

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

Pré-requisitos

Uma Conta do Google com acesso ao Workspace Studio.

Configurar o script

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

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

Abrir o projeto
Clique em Visão geral.
Na página de visão geral, clique em Fazer uma cópia.
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.
2. Em Título do projeto, digite 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 seu agente. 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"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculateFunction",
            "onExecuteFunction": "onExecuteCalculateFunction"
          }
        }
      ]
    }
  }
}

Calculator.gs

Define uma etapa personalizada para o Google Workspace Studio. 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 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);
}

Implantar e testar a etapa

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

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 em Agentes. Talvez seja necessário atualizar os agentes 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.
Abra "Agentes".
Crie um agente que inclua sua etapa:
1. Clique em Novo agente.
2. Selecione como o agente vai começar. Ao testar uma etapa, escolha um gatilho que você possa acionar sozinho, como enviar um e-mail para você 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 que você criou ou atualizou, 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 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 agente está pronto para ser executado.
Execute o agente ativando o início do agente. Por exemplo, se o agente for iniciado quando você receber um e-mail, envie um e-mail para você mesmo.
Verifique se o agente é executado conforme o esperado. Para verificar os registros, acesse a guia Atividade do criador de agentes. Para saber como criar registros personalizados na guia "Atividade", consulte Registros de atividades.

Próximas etapas

Você criou e testou uma etapa personalizada para o Workspace Studio. 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 para revisar o payload JSON que os agentes enviam e recebem à medida que as etapas são executadas.

Guia de início rápido: criar uma etapa de calculadora com o Google Apps Script Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.