Konfigurationskarte für einen Schritt erstellen

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

Im Allgemeinen erstellen Sie zum Erstellen einer Konfigurationskarte eine Kartenschnittstelle wie für jedes andere Google Workspace-Add‑on. Hilfe beim Erstellen von Konfigurationskarten-Benutzeroberflächen finden Sie hier:

  • Card Builder: Ein interaktives Tool, mit dem Sie Karten erstellen und definieren können.
  • Card in der Referenzdokumentation zur Google Workspace-Add-ons API.
  • 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-Funktionen, die in dieser Anleitung 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-Bereich auswählen können.

Manifestdatei bearbeiten

Definieren Sie workflowElements in der Manifestdatei.

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 USA angezeigt werden, kann Ihr Element Atlanta vorschlagen, bevor der Nutzer die Eingabe abgeschlossen hat. Sie können bis zu 100 Elemente automatisch vervollständigen lassen.

Vorschläge zur automatischen Vervollständigung können aus den folgenden Datenquellen stammen:

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

Serverseitige automatische Vervollständigung

Sie können ein SelectionInput-Widget so konfigurieren, dass Vorschläge für die automatische Vervollständigung aus einer externen Datenquelle stammen. Sie können Nutzern beispielsweise helfen, aus einer Liste von Vertriebs-Leads aus einem CRM-System (Customer Relationship Management) auszuwählen.

So implementieren Sie die serverseitige automatische Vervollständigung:

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

Das folgende Beispiel zeigt, wie Sie ein SelectionInput-Widget für die serverseitige 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 ...

Autocomplete-Anfrage verarbeiten

Die in setFunctionName angegebene Funktion (z.B. getAutocompleteResults) erhält ein Ereignisobjekt, wenn der Nutzer etwas in das Feld eingibt. Diese Funktion muss:

  1. Prüfen Sie, ob event.workflow.elementUiAutocomplete.invokedFunction 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. Gibt bis zu 100 Vorschläge im erforderlichen Format zurück.

Das folgende Beispiel zeigt, wie Sie die Funktion handleAutocompleteRequest() implementieren, um Vorschläge basierend auf der Anfrage 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