Coletar dados com uma variável de entrada

Este guia explica como criar uma variável de entrada.

Para serem executadas, as etapas exigem determinadas informações. Por exemplo, para enviar um e-mail, é necessário um endereço de e-mail. Para fornecer essas informações necessárias, defina variáveis de entrada. Depois de definidas, as variáveis de entrada são geralmente definidas pelo usuário no card de configuração de uma etapa enquanto ele configura a etapa.

Defina a variável de entrada em dois lugares: no arquivo de manifesto do complemento e no código com um card de configuração em que os usuários podem inserir valores para variáveis de entrada.

Definir a variável de entrada no arquivo de manifesto

No arquivo de manifesto, especifique variáveis de entrada com a matriz inputs[]. Cada item na matriz inputs[] tem estas propriedades:

  • id: identificador exclusivo de uma variável de entrada. Para permitir que o fluxo associe um elemento de entrada de card de configuração a essa variável de entrada, precisa corresponder ao nome do elemento de card correspondente.
  • description: uma descrição da variável de entrada para mostrar aos usuários finais.
  • cardinality: quantos valores são permitidos. Os valores possíveis são:
    • SINGLE: apenas um valor é permitido.
  • dataType: o tipo de valores aceitos. dataType tem a propriedade basicType, que define o tipo de dados. Alguns dos valores válidos são:
    • STRING: uma string alfanumérica.
    • INTEGER: um número.
    • TIMESTAMP: um carimbo de data/hora no formato ISO 8601. Por exemplo, na ISO 8601, 15 de março de 2025 é representado como 2025-03-15.
    • BOOLEAN: verdadeiro ou falso.
    • EMAIL_ADDRESS: um endereço de e-mail no formato dana@example.com.

O exemplo a seguir define três variáveis de entrada para uma etapa de calculadora. As duas primeiras variáveis de entrada são números inteiros, e a terceira é uma operação aritmética.

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": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Definir a variável de entrada no código

O código da etapa inclui uma função chamada onConfigFunction() que retorna um card de configuração que define um widget de card de entrada para cada variável de entrada definida na matriz inputs[] do arquivo de manifesto.

Os widgets de entrada definidos no cartão de configuração têm os seguintes requisitos:

  • O name de cada widget de entrada precisa corresponder ao id da variável de entrada correspondente no arquivo de manifesto.
  • A cardinalidade do widget de entrada precisa corresponder ao cardinality da variável de entrada no arquivo de manifesto.
  • O tipo de dados do widget de entrada precisa corresponder ao dataType da variável de entrada no arquivo de manifesto. Se a variável de entrada tiver um dataType de número inteiro, ela não poderá conter uma string.

Para receber ajuda na criação de interfaces de card, consulte uma destas opções:

  • O Card Builder: uma ferramenta interativa que você pode usar para criar e definir cards.
  • Card: na documentação de referência da API de complementos do Google Workspace.
  • Serviço de card: um serviço do Apps Script que permite que os scripts configurem e criem cards.
  • Visão geral das interfaces baseadas em cards: na documentação para desenvolvedores de complementos do Google Workspace.

O exemplo a seguir retorna um card de configuração para cada widget de entrada definido em Definir a variável de entrada no arquivo de manifesto.

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 card also includes a "Save"
 * button to save the step 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.
 */
function onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Validar a variável de entrada

Como prática recomendada, valide se o usuário inseriu um valor adequado. Consulte Validar uma variável de entrada.