Konfigurationskarte für einen Schritt erstellen

In diesem Leitfaden wird erläutert, wie Sie eine Konfigurationskarte erstellen, mit der Nutzer Eingaben für einen Schritt in Google Workspace Studio anpassen und bereitstellen können.

Im Allgemeinen erstellen Sie eine Kartenoberfläche wie für jedes andere Google Workspace-Add-on. Weitere Informationen zum Erstellen von Konfigurationskartenoberflächen finden Sie hier:

  • Der Card Builder, ein interaktives Tool, mit dem Sie Karten erstellen und definieren können.
  • Karte in der API-Referenzdokumentation für Google Workspace-Add-ons.
  • Card Service, ein Apps Script-Dienst, mit dem Skripts Karten konfigurieren und erstellen können.
  • Kartenbasierte Oberflächen in der Entwicklerdokumentation für Google Workspace-Add-ons.

Einige Karten-Widgets haben spezielle Workspace Studio-spezifische Funktionen, die in diesem Leitfaden beschrieben werden.

Konfigurationskarte definieren

Definieren Sie eine Konfigurationskarte sowohl im Apps Script-Manifest als auch im Code.

Im folgenden Beispiel wird gezeigt, wie Sie eine Konfigurationskarte erstellen, auf der Nutzer einen Google Chat-Gruppenbereich auswählen können.

Manifestdatei bearbeiten

Definieren Sie in der Manifestdatei workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

Code bearbeiten

Geben Sie im Anwendungscode eine Karte zurück.

Apps Script

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

Automatische Vervollständigung für Eingabe-Widgets einrichten

Sie können die automatische Vervollständigung für SelectionInput Widgets konfigurieren, damit Nutzer aus einer Liste von Optionen auswählen können. Wenn ein Nutzer beispielsweise Atl für ein Menü eingibt, in dem Städte in den Vereinigten Staaten angezeigt werden, kann Ihr Element Atlanta automatisch vorschlagen, bevor der Nutzer die Eingabe beendet. Sie können bis zu 100 Elemente automatisch vervollständigen.

Vorschläge für die automatische Vervollständigung können aus den folgenden Datenquellen stammen:

  • Serverseitige automatische Vervollständigung:Vorschläge werden aus einer von Ihnen definierten externen Datenquelle oder einer Datenquelle eines Drittanbieters generiert.
  • Google Workspace-Daten:Vorschläge werden aus Google Workspace-Quellen wie Google Workspace-Nutzern oder Google Chat-Gruppenbereichen generiert.

Serverseitige automatische Vervollständigung

Sie können ein SelectionInput Widget so konfigurieren, dass Vorschläge aus einer externen Daten quelle automatisch vervollständigt werden. So können Sie Nutzern beispielsweise helfen, aus einer Liste von Leads aus einem CRM-System (Customer Relationship Management) auszuwählen.

So implementieren Sie die serverseitige automatische Vervollständigung:

  1. Datenquelle definieren: Fügen Sie dem SelectionInput-Widget eine DataSourceConfig hinzu, die eine RemoteDataSource angibt. Diese Konfiguration verweist auf eine Apps Script-Funktion, die Vorschläge für die automatische Vervollständigung abruft.
  2. Funktion für die automatische Vervollständigung implementieren: Diese Funktion wird ausgelöst, wenn der Nutzer in das Eingabefeld tippt. Die Funktion sollte die externe Daten quelle basierend auf der Eingabe des Nutzers abfragen und eine Liste mit Vorschlägen zurückgeben.

Im folgenden Beispiel wird gezeigt, wie Sie ein SelectionInput Widget für die serverseitige automatische Vervollständigung konfigurieren:

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

Anfrage für automatische Vervollständigung verarbeiten

Die in setFunctionName angegebene Funktion (z. B. getAutocompleteResults) empfängt ein Ereignisobjekt, wenn der Nutzer in das Feld tippt. Diese Funktion muss folgende Aufgaben ausführen:

  1. Prüfen Sie event.workflow.elementUiAutocomplete.invokedFunction, um sicherzustellen, dass sie mit dem erwarteten Funktionsnamen übereinstimmt.
  2. Rufen Sie die Eingabe des Nutzers aus event.workflow.elementUiAutocomplete.query ab.
  3. Fragen Sie die externe Datenquelle mit der Abfrage ab.
  4. Geben Sie bis zu 100 Vorschläge im erforderlichen Format zurück.

Im folgenden Beispiel wird gezeigt, wie Sie die Funktion handleAutocompleteRequest implementieren, um Vorschläge basierend auf der Abfrage des Nutzers zurückzugeben:

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Überlegungen und Einschränkungen für Karten