Zbieranie danych za pomocą zmiennej wejściowej

Z tego przewodnika dowiesz się, jak utworzyć zmienną wejściową.

Aby można było wykonać kroki, wymagane są określone informacje. Na przykład wysłanie e-maila wymaga podania adresu e-mail. Aby podać te niezbędne informacje, zdefiniuj zmienne wejściowe. Po zdefiniowaniu zmienne wejściowe są zwykle ustawiane przez użytkownika na karcie konfiguracji kroku podczas jego konfigurowania.

Zdefiniuj zmienną wejściową w 2 miejscach: w pliku manifestu dodatku i w kodzie za pomocą karty konfiguracji, na której użytkownicy mogą wpisywać wartości zmiennych wejściowych.

Zdefiniuj zmienną wejściową w pliku manifestu

W pliku manifestu określ zmienne wejściowe za pomocą tablicy inputs[]. Każdy element w tablicy inputs[] ma te właściwości:

  • id: unikalny identyfikator zmiennej wejściowej. Aby umożliwić przepływowi powiązanie elementu wejściowego karty konfiguracji z tą zmienną wejściową, musi on być zgodny z nazwą odpowiedniego elementu karty.
  • description: opis zmiennej wejściowej, który będzie wyświetlany użytkownikom.
  • cardinality: ile wartości jest dozwolonych. Możliwe wartości:
    • SINGLE: dozwolona jest tylko jedna wartość.
  • dataType: typ akceptowanych wartości. dataType ma właściwość basicType, która określa typ danych. Prawidłowe wartości to:
    • STRING: ciąg alfanumeryczny.
    • INTEGER: liczba.
    • TIMESTAMP: sygnatura czasowa w formacie ISO 8601. Na przykład w formacie ISO 8601 data 15 marca 2025 r. jest zapisywana jako 2025-03-15.
    • BOOLEAN: wartość true lub false.
    • EMAIL_ADDRESS: adres e-mail w formacie dana@example.com.

W tym przykładzie zdefiniowano 3 zmienne wejściowe dla kroku kalkulatora. Pierwsze 2 zmienne wejściowe to liczby całkowite, a trzecia to działanie arytmetyczne.

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"
          }
        }
      ]
    }
  }
}

Zdefiniuj zmienną wejściową w kodzie

Kod kroku zawiera funkcję o nazwie onConfigFunction(), która zwraca kartę konfiguracji definiującą 1 widżet karty wejściowej dla każdej zmiennej wejściowej zdefiniowanej w tablicy inputs[] w pliku manifestu.

Widżety wejściowe zdefiniowane na karcie konfiguracji muszą spełniać te wymagania:

  • Wartość name każdego widżetu wejściowego musi być zgodna z odpowiednią wartością id zmiennej wejściowej w pliku manifestu.
  • Kardynalność widżetu wejściowego musi być zgodna z kardynalnością zmiennej wejściowej cardinality w pliku manifestu.
  • Typ danych widżetu wejściowego musi być zgodny z typem danych zmiennej wejściowej dataType w pliku manifestu. Jeśli zmienna wejściowa ma typ dataType, nie może zawierać ciągu znaków.

Aby uzyskać pomoc w tworzeniu interfejsów kart, skorzystaj z jednej z tych opcji:

  • Kreator kart: interaktywne narzędzie, za pomocą którego możesz tworzyć i definiować karty.
  • Karta: w dokumentacji referencyjnej interfejsu API dodatków do Google Workspace.
  • Card Service: usługa Apps Script, która umożliwia skryptom konfigurowanie i tworzenie kart.
  • Omówienie interfejsów opartych na kartach: w dokumentacji dla programistów dodatków do Google Workspace.

Poniższy przykład zwraca kartę konfiguracji dla każdego widżetu wejściowego zdefiniowanego w sekcji Zdefiniuj zmienną wejściową w pliku manifestu.

Google 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
      }]
    }
  };
}

Sprawdź zmienną wejściową

Sprawdzoną metodą jest weryfikowanie, czy użytkownik wprowadza odpowiednią wartość. Zobacz Weryfikowanie zmiennej wejściowej.