Esta página foi traduzida pela API Cloud Translation.

Criar um card de configuração para uma etapa

Neste guia, explicamos como criar um card de configuração que permite aos usuários personalizar e fornecer entradas para uma etapa no Google Workspace Flows.

Em geral, para criar um card de configuração, você cria uma interface de card como faria para qualquer outro complemento do Google Workspace. Para ajuda na criação de interfaces de card de configuração, consulte:

O Card Builder, uma ferramenta interativa que ajuda você a criar e definir cards.
Card na documentação de referência da API Google Workspace Add-ons.
O Card Service, um serviço do Apps Script que permite que os scripts configurem e criem cards.
Interfaces baseadas em cards na documentação para desenvolvedores de complementos do Google Workspace.

Alguns widgets de card têm funcionalidades e recursos especiais específicos do Workspace Flows, detalhados neste guia.

Definir um card de configuração

Defina um card de configuração no manifesto do Apps Script e no código.

O exemplo a seguir mostra como criar um card de configuração que pede aos usuários para selecionar um espaço do Google Chat.

Editar o arquivo de manifesto

No arquivo de manifesto, defina 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"
          }
        }
      ]
    }
  }
}

Editar o código

No código do aplicativo, retorne um card.

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

Configurar o preenchimento automático para widgets de entrada

É possível configurar o preenchimento automático para widgets de SelectionInput e ajudar os usuários a selecionar uma opção em uma lista. Por exemplo, se um usuário começar a digitar Atl em um menu que preenche cidades nos Estados Unidos, seu elemento poderá sugerir automaticamente Atlanta antes que o usuário termine de digitar. É possível usar o preenchimento automático em até 100 itens.

As sugestões de preenchimento automático podem vir das seguintes fontes de dados:

Preenchimento automático do lado do servidor:as sugestões são preenchidas com base em uma fonte de dados externa ou de terceiros definida por você.
Dados do Google Workspace:as sugestões são geradas com base em fontes do Google Workspace, como usuários do Google Workspace ou espaços do Google Chat.

Preenchimento automático do lado do servidor

É possível configurar um widget de SelectionInput para preencher automaticamente sugestões de uma fonte de dados externa. Por exemplo, você pode ajudar os usuários a selecionar em uma lista de leads de vendas de um sistema de gestão de relacionamento com o cliente (CRM).

Para implementar o preenchimento automático do lado do servidor, você precisa:

Defina a fonte de dados:no widget SelectionInput, adicione um DataSourceConfig que especifica um RemoteDataSource. Essa configuração aponta para uma função do Apps Script que busca sugestões de preenchimento automático.
Implemente a função de preenchimento automático:essa função é acionada quando o usuário digita no campo de entrada. A função precisa consultar sua fonte de dados externa com base na entrada do usuário e retornar uma lista de sugestões.

O exemplo a seguir mostra como configurar um widget SelectionInput para o preenchimento automático do lado do servidor:

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

Processar a solicitação de preenchimento automático

A função especificada em setFunctionName (por exemplo, getAutocompleteResults) recebe um objeto de evento quando o usuário digita no campo. Essa função precisa:

Verifique o event.workflow.elementUiAutocomplete.invokedFunction para garantir que ele corresponda ao nome da função esperada.
Receba a entrada do usuário de event.workflow.elementUiAutocomplete.query.
Consulte a fonte de dados externa usando a consulta.
Retorne até 100 sugestões no formato necessário.

O exemplo a seguir mostra como implementar a função handleAutocompleteRequest() para retornar sugestões com base na consulta do usuário:

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

Preenchimento automático de dados do Google Workspace

Você também pode preencher sugestões de preenchimento automático com dados do ambiente do Google Workspace do usuário:

Usuários do Google Workspace:preencha os usuários na mesma organização do Google Workspace.
Espaços do Google Chat:preenche os espaços do Google Chat de que o usuário é membro.

Para configurar isso, defina o PlatformDataSource no widget SelectionInput especificando o WorkflowDataSourceType como USER ou 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)
            ))
    );

Exemplo: combinar tipos de preenchimento automático

O exemplo a seguir mostra uma função onConfig que cria um card com três widgets SelectionInput e demonstra o preenchimento automático do servidor, do usuário e do espaço:

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

Recursos específicos do Workspace Flows

Alguns widgets de card têm funcionalidades e recursos especiais específicos do Workspace Flows, detalhados aqui.

TextInput e SelectionInput

Os widgets TextInput e SelectionInput têm estes recursos específicos do Workspace Flows:

includeVariables: uma propriedade booleana que permite aos usuários selecionar variáveis de etapas anteriores.
type: um valor enumerado que preenche automaticamente as sugestões. Os valores aceitos incluem:
- USER: oferece sugestões de preenchimento automático para pessoas nos contatos do usuário.
- SPACE: oferece sugestões de preenchimento automático para espaços do Google Chat de que o usuário participa.

Quando includeVariables e type estão definidos, o campo de entrada combina as experiências deles. Os usuários podem selecionar uma variável do type correspondente em um menu suspenso e conferir sugestões de preenchimento automático.

Figura 1:um usuário analisa as sugestões de preenchimento automático ao escolher um espaço.
Figura 2:um usuário seleciona a variável de saída de uma etapa anterior no menu suspenso ➕Variáveis.

Considerações e limitações dos cards

A navegação por cards, como popCard(), pushCard() e updateCard() não é compatível com complementos que estendem fluxos.
Quando SelectionInput é usado em um seletor de variáveis, os widgets só são compatíveis com "type": "MULTI_SELECT". Em outros cards de configuração, SelectionInput aceita todos os valores de SelectionType.

Criar um card de configuração para uma etapa Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Definir um card de configuração

Editar o arquivo de manifesto

JSON

Editar o código

Apps Script

Configurar o preenchimento automático para widgets de entrada

Preenchimento automático do lado do servidor

Apps Script

Processar a solicitação de preenchimento automático

Apps Script

Preenchimento automático de dados do Google Workspace

Apps Script

Exemplo: combinar tipos de preenchimento automático

Apps Script

Recursos específicos do Workspace Flows

TextInput e SelectionInput

Considerações e limitações dos cards

Temas relacionados

Criar um card de configuração para uma etapa