Definisci una variabile dinamica

Questa guida spiega come creare una variabile dinamica.

Se possibile, una variabile deve essere definita staticamente nel file manifest come variabile di input, variabile di output o risorsa personalizzata. Tuttavia, alcune situazioni richiedono una variabile che può essere definita solo quando l'utente configura l'agente perché la natura dell'input varia. Ad esempio, il numero di domande e risposte (e i relativi contenuti) per un Modulo Google non può essere determinato finché non viene selezionato un modulo specifico durante la configurazione dell'agente.

Le variabili dinamiche tengono conto di questi casi consentendoti di definire un input che produce un insieme dinamico di output nel file manifest e nel codice del passaggio.

Definisci la variabile di output nel file manifest

Nel file manifest, segui questi passaggi:

  • In inputs[], specifica una variabile di input che accetta un valore di input dinamico.

  • In outputs[], specifica una variabile di output che restituisce un insieme dinamico di variabili di output. Assegna a questo output un dataType di "workflowResourceDefinitionId": "dynamic_resource_id".

  • Definisci una risorsa personalizzata per gestire la variabile dinamica. Specifica workflowResourceDefinitions con "resourceType": "DYNAMIC" e "providerFunction": "onDynamicProviderFunction". id deve corrispondere a workflowResourceDefinitionId impostato in outputs[]. Per saperne di più sulle risorse personalizzate, consulta Definire una risorsa personalizzata.

  • Imposta dynamicResourceDefinitionProvider sul nome di una funzione corrispondente nel codice del passaggio, in questo esempio onDynamicDefinitionFunction(), che definisce e restituisce una scheda di configurazione che accetta un valore di input dinamico e restituisce una risorsa personalizzata.

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",
}

Definisci la variabile di output nel codice

Il codice del passaggio include le seguenti funzioni:

  • onDynamicVariableConfigFunction(), che crea e restituisce una scheda di configurazione con un widget di input dinamico. Il nome di questa funzione deve corrispondere al valore di onConfigFunction() nel file manifest. Il nome del widget di input dinamico deve corrispondere a id impostato nel file manifest. Questo widget di input dinamico consente agli utenti di impostare una variabile dinamica durante la configurazione del passaggio, ad esempio la scelta di un modulo Google.
  • onDynamicVariableExecuteFunction(), che restituisce i dati della variabile dinamica come output quando viene eseguito il passaggio. Il nome di questa funzione deve corrispondere al valore di onExecuteFunction() nel file manifest. La chiave di variableData in returnOutputVariablesAction deve corrispondere a id della variabile di output impostata nel file manifest. La risorsa dinamica si trova nell'oggetto evento all'indirizzo e.workflow.resourceFieldsDefinitionRetrieval. L'input non può fare riferimento a variabili perché tutti gli input per una risorsa dinamica devono essere disponibili al momento della configurazione.
  • onDynamicDefinitionFunction(), che recupera i dati delle variabili dinamiche dall'oggetto evento, in particolare resourceFieldsDefinitionRetrieval e restituisce resourceFieldsDefinitionRetrievedAction che fornisce il nome delle variabili di output per i passaggi successivi, nonché i selettori in modo che onDynamicProviderFunction() possa fornire il valore corrispondente a ogni variabile di output. resourceId deve corrispondere a id di un elemento dell'array workflowResourceDefinitions[] impostato nel file manifest.

  • onDynamicProviderFunction(), che fornisce un valore per ogni variabile di output utilizzando i selettori come chiavi accedendo a resourceId e 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;
}