Definir uma variável dinâmica

Este guia explica como criar uma variável dinâmica.

Quando possível, uma variável precisa ser definida estaticamente no arquivo de manifesto como uma variável de entrada, uma variável de saída ou um recurso personalizado. No entanto, algumas situações exigem uma variável que só pode ser definida quando o usuário configura o agente, porque a natureza da entrada varia. Por exemplo, o número de perguntas e respostas (e o conteúdo delas) de um Google Formulários só pode ser determinado quando um formulário específico é selecionado durante a configuração do agente.

As variáveis dinâmicas consideram esses casos, permitindo que você defina uma entrada que produz um conjunto dinâmico de saídas no arquivo de manifesto e no código da etapa.

Definir a variável de saída no arquivo de manifesto

No arquivo de manifesto, siga estas etapas:

  • Em inputs[], especifique uma variável de entrada que aceite um valor de entrada dinâmico.

  • Em outputs[], especifique uma variável de saída que retorne um conjunto dinâmico de variáveis de saída. Dê a essa saída um dataType de "workflowResourceDefinitionId": "dynamic_resource_id".

  • Defina um recurso personalizado para processar a variável dinâmica. Especifique workflowResourceDefinitions com "resourceType": "DYNAMIC" e "providerFunction": "onDynamicProviderFunction". O id precisa corresponder ao workflowResourceDefinitionId definido em outputs[]. Para saber mais sobre recursos personalizados, consulte Definir um recurso personalizado.

  • Defina dynamicResourceDefinitionProvider como o nome de uma função correspondente no código da etapa. Neste exemplo, onDynamicDefinitionFunction(), que define e retorna um card de configuração que aceita um valor de entrada dinâmico e retorna um recurso personalizado.

JSON

"flows": {
  "workflowElements" : [{
    "id": "getDynamicVariable",
    "state": "ACTIVE",
    "name": "Get Dynamic Variable",
    "description": "Get Dynamic Variable",
    "workflowAction": {
    "inputs": [
      {
          "id": "dynamic_resource_input",
          "description": "Dynamic Resource Input",
          "cardinality": "SINGLE",
          "dataType": {
            "basicType": "INTEGER"
          }
       }
      ],
      "outputs": [
        {
          "id": "dynamic_resource_output",
          "description": "Dynamic Data",
          "cardinality": "SINGLE",
          "dataType": {
            "resourceType": {
              "workflowResourceDefinitionId": "resource_definition_1"
            }
          }
        }
      ],
      "onConfigFunction": "onDynamicVariableConfigFunction",
      "onExecuteFunction": "onDynamicVariableExecuteFunction"
    }
  }],
  "workflowResourceDefinitions": [{
    "id": "resource_definition_1",
    "name": "Dynamic Resource",
    "providerFunction": "onDynamicProviderFunction",
    "resourceType" : "DYNAMIC"
  }],
  "dynamicResourceDefinitionProvider" : "onDynamicDefinitionFunction",
}

Definir a variável de saída no código

O código da etapa inclui estas funções:

  • onDynamicVariableConfigFunction(), que cria e retorna um card de configuração com um widget de entrada dinâmica. O nome dessa função precisa corresponder ao valor de onConfigFunction() no arquivo de manifesto. O nome do widget de entrada dinâmica precisa corresponder ao id definido no arquivo de manifesto. Com esse widget de entrada dinâmica, os usuários podem definir uma variável dinâmica ao configurar a etapa, como escolher um Formulário Google.
  • onDynamicVariableExecuteFunction(), que retorna os dados da variável dinâmica como saída quando a etapa é executada. O nome dessa função precisa corresponder ao valor de onExecuteFunction() no arquivo de manifesto. A chave de variableData em returnOutputVariablesAction precisa corresponder ao id da variável de saída definido no arquivo de manifesto. O recurso dinâmico é encontrado no objeto de evento em e.workflow.resourceFieldsDefinitionRetrieval. A entrada não pode referenciar variáveis porque todas as entradas de um recurso dinâmico precisam estar disponíveis no momento da configuração.
  • onDynamicDefinitionFunction(), que recupera os dados da variável dinâmica do objeto de evento, especificamente resourceFieldsDefinitionRetrieval, e retorna resourceFieldsDefinitionRetrievedAction, que fornece o nome das variáveis de saída para etapas posteriores, além dos seletores para que o onDynamicProviderFunction() possa fornecer o valor correspondente a cada variável de saída. O resourceId precisa corresponder ao id de um item na matriz workflowResourceDefinitions[] definida no arquivo de manifesto.

  • onDynamicProviderFunction(), que fornece um valor para cada variável de saída usando seletores como chaves ao acessar o resourceId e o workflowResourceDefinitionId.

Apps Script

function onDynamicVariableConfigFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextInput()
        .setFieldName("dynamic_resource_input")
        .setTitle("Dynamic Resource Input")
        .setHint("Input a Integer value between 1 and 3\(inclusive\) for corresponding number of output variables")
    );

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onDynamicDefinitionFunction(e) {
  console.log("Payload in onDynamicDefinitionFunction: ", JSON.stringify(e));
  var input_value = e.workflow.resourceFieldsDefinitionRetrieval.inputs.dynamic_resource_input.integerValues[0];

  let resourceDefinitions = AddOnsResponseService.newDynamicResourceDefinition()
    .setResourceId("resource_definition_1")
    .addResourceField(
      AddOnsResponseService.newResourceField()
        .setSelector("question_1")
        .setDisplayText("Question 1")
    );

  if (input_value == 2 || input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_2")
          .setDisplayText("Question 2")
      );
  }
  if (input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_3")
          .setDisplayText("Question 3")
      );
  }

  let workflowAction = AddOnsResponseService.newResourceFieldsDefinitionRetrievedAction()
    .addDynamicResourceDefinition(resourceDefinitions);

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  let renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}

function onDynamicVariableExecuteFunction(e) {
  console.log("Payload in onDynamicVariableExecuteFunction: ", JSON.stringify(e));

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .setVariableDataMap({
      "dynamic_resource_output": AddOnsResponseService.newVariableData()
        .addResourceReference("my_dynamic_resource_id")
    });

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  let renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}

function onDynamicProviderFunction(e) {
  console.log("Payload in onDynamicProviderFunction: ", JSON.stringify(e));

  // resourceId == "my_dynamic_resource_id"
  var resourceId = e.workflow.resourceRetrieval.resourceReference.resourceId;
  // workflowResourceDefinitionId == "resource_definition_1"
  var workflowResourceDefinitionId = e.workflow.resourceRetrieval.resourceReference.resourceType.workflowResourceDefinitionId;

  const workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(
      AddOnsResponseService.newResourceData()
        .addVariableData("question_1", AddOnsResponseService.newVariableData().addStringValue("Answer 1"))
        .addVariableData("question_2", AddOnsResponseService.newVariableData().addStringValue("Answer 2"))
        .addVariableData("question_3", AddOnsResponseService.newVariableData().addStringValue("Answer 3"))
    );

  const hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  const renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}