Questa pagina è stata tradotta dall'API Cloud Translation.

Crea una scheda di configurazione per un passaggio

Questa guida spiega come creare una scheda di configurazione che consenta agli utenti di personalizzare e fornire input per un passaggio in Google Workspace Flows.

In generale, per creare una scheda di configurazione, devi creare un'interfaccia della scheda come faresti per qualsiasi altro componente aggiuntivo di Google Workspace. Per assistenza nella creazione di interfacce di schede di configurazione, consulta quanto segue:

Card Builder, uno strumento interattivo che ti aiuta a creare e definire le schede.
Scheda nella documentazione di riferimento dell'API Google Workspace Add-ons.
Servizio schede, un servizio Apps Script che consente agli script di configurare e creare schede.
Interfacce basate su schede nella documentazione per gli sviluppatori di componenti aggiuntivi di Google Workspace.

Alcuni widget delle schede hanno funzionalità e caratteristiche specifiche di Workspace Flows, descritte in dettaglio in questa guida.

Definire una scheda di configurazione

Definisci una scheda di configurazione sia nel manifest di Apps Script sia nel codice.

L'esempio seguente mostra come creare una scheda di configurazione che chiede agli utenti di selezionare uno spazio Google Chat.

Modificare il file manifest

Nel file manifest, definisci workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "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": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Modifica il codice

Nel codice dell'applicazione, restituisci una scheda.

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Configurare il completamento automatico per i widget di input

Puoi configurare il completamento automatico per i widget SelectionInput per aiutare gli utenti a scegliere da un elenco di opzioni. Ad esempio, se un utente inizia a digitare Atl per un menu che popola le città degli Stati Uniti, l'elemento può suggerire automaticamente Atlanta prima che l'utente finisca di digitare. Puoi completare automaticamente fino a 100 elementi.

I suggerimenti di completamento automatico possono provenire dalle seguenti origini dati:

Completamento automatico lato server:i suggerimenti vengono compilati da un'origine dati esterna o di terze parti che definisci.
Dati di Google Workspace:i suggerimenti vengono compilati a partire da fonti di Google Workspace, come utenti di Google Workspace o spazi di Google Chat.

Completamento automatico lato server

Puoi configurare un widget SelectionInput per completare automaticamente i suggerimenti da un'origine dati esterna. Ad esempio, puoi aiutare gli utenti a selezionare un elenco di lead di vendita da un sistema di gestione dei rapporti con i clienti (CRM).

Per implementare il completamento automatico lato server, devi:

Definisci l'origine dati:nel widget SelectionInput, aggiungi un DataSourceConfig che specifica un RemoteDataSource. Questa configurazione punta a una funzione Apps Script che recupera i suggerimenti di completamento automatico.
Implementa la funzione di completamento automatico:questa funzione viene attivata quando l'utente digita nel campo di input. La funzione deve eseguire query sulla sorgente di dati esterni in base all'input dell'utente e restituire un elenco di suggerimenti.

L'esempio seguente mostra come configurare un widget SelectionInput per il completamento automatico lato server:

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 ...

Gestire la richiesta di completamento automatico

La funzione specificata in setFunctionName (ad es. getAutocompleteResults) riceve un oggetto evento quando l'utente digita nel campo. Questa funzione deve:

Controlla event.workflow.elementUiAutocomplete.invokedFunction per assicurarti che corrisponda al nome della funzione previsto.
Recupera l'input dell'utente da event.workflow.elementUiAutocomplete.query.
Esegui una query sull'origine dati esterna utilizzando la query.
Restituisci fino a 100 suggerimenti nel formato richiesto.

Il seguente esempio mostra come implementare la funzione handleAutocompleteRequest() per restituire suggerimenti in base alla query dell'utente:

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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// 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 ...
}

Completamento automatico dei dati di Google Workspace

Puoi anche compilare i suggerimenti di completamento automatico con i dati all'interno dell'ambiente Google Workspace dell'utente:

Utenti di Google Workspace:popola gli utenti all'interno della stessa organizzazione Google Workspace.
Spazi di Google Chat:popola gli spazi di Google Chat di cui l'utente è membro.

Per configurare questa impostazione, imposta PlatformDataSource nel widget SelectionInput, specificando WorkflowDataSourceType come USER o SPACE.

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

Esempio: combinazione di tipi di completamento automatico

L'esempio seguente mostra una funzione onConfig che crea una scheda con tre widget SelectionInput, che dimostrano il completamento automatico lato server, utente e spazio:

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  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)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Funzionalità specifiche di Workspace Flows

Alcuni widget delle schede hanno funzionalità specifiche di Workspace Flows, descritte qui.

TextInput e SelectionInput

I widget TextInput e SelectionInput hanno le seguenti funzionalità specifiche di Workspace Flows:

includeVariables: una proprietà booleana che consente agli utenti di selezionare le variabili dai passaggi precedenti.
type: un valore enumerato che completa automaticamente i suggerimenti. I valori supportati includono:
- USER: fornisce suggerimenti di completamento automatico per le persone nei contatti dell'utente.
- SPACE: fornisce suggerimenti di completamento automatico per gli spazi di Google Chat di cui l'utente è membro.

Quando vengono impostati sia includeVariables sia type, il campo di input combina le loro esperienze. Gli utenti possono selezionare una variabile della corrispondenza type da un menu a discesa e visualizzare i suggerimenti di completamento automatico.

Figura 1: un utente esamina i suggerimenti di completamento automatico quando sceglie uno spazio.
Figura 2: un utente seleziona la variabile di output di un passaggio precedente dal menu a discesa ➕Variabili.

Considerazioni e limitazioni relative alle carte

La navigazione tra le schede, ad esempio popCard(), pushCard() e updateCard() non è supportata nei componenti aggiuntivi che estendono i flussi.
Quando SelectionInput viene utilizzato in un selettore di variabili, i widget supportano solo "type": "MULTI_SELECT". In altre schede di configurazione, SelectionInput supporta tutti i valori di SelectionType.

Crea una scheda di configurazione per un passaggio Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Definire una scheda di configurazione

Modificare il file manifest

JSON

Modifica il codice

Apps Script

Configurare il completamento automatico per i widget di input

Completamento automatico lato server

Apps Script

Gestire la richiesta di completamento automatico

Apps Script

Completamento automatico dei dati di Google Workspace

Apps Script

Esempio: combinazione di tipi di completamento automatico

Apps Script

Funzionalità specifiche di Workspace Flows

TextInput e SelectionInput

Considerazioni e limitazioni relative alle carte

Argomenti correlati

Crea una scheda di configurazione per un passaggio