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 input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
    .setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("First Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const secondInput = CardService.newTextInput()
    .setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("Second Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  let card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

Sprawdź zmienną wejściową

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