Representar dados complexos com um recurso personalizado

Neste guia, explicamos como definir recursos personalizados para o Google Workspace Flows.

Recursos personalizados são estruturas de dados personalizadas que você pode definir para agrupar várias variáveis. Por exemplo, para criar um lead de CRM, transmita um recurso personalizado que contenha um endereço de e-mail, um endereço físico e um nome.

Estas são as duas maneiras de definir recursos personalizados:

  • Como referência:quando você gera um recurso personalizado como referência, retorna o recurso personalizado pelo ID em vez do objeto completo. Isso melhora o desempenho ao reduzir os dados transferidos entre as etapas do fluxo. Quando os dados exigem pesquisas secundárias, retornar o ID é útil para realizar essas pesquisas.
  • Como um valor:use esse método quando os dados precisarem ser recuperados durante a execução ou quando o recurso personalizado for pequeno e não contiver dados sensíveis.

Gerar um recurso personalizado como referência

Ao gerar um recurso personalizado como referência, é possível retornar o recurso personalizado pelo ID em vez do objeto completo. Se um recurso personalizado for grande ou complexo, transmitir apenas o ID vai melhorar a performance, reduzindo os dados transferidos entre as etapas do fluxo.

Para gerar um recurso personalizado como referência, edite o arquivo de manifesto e o código da etapa.

Editar o arquivo de manifesto

No arquivo de manifesto:

  1. Especifique um workflowResourceDefinitions e atribua a ele um id, uma matriz fields[] e um providerFunction. O workflowResourceDefinitions é uma estrutura que define tipos de dados e conteúdos do recurso personalizado.

  2. Dentro da matriz fields[], especifique os campos individuais que compõem o recurso personalizado, neste exemplo chamado field_1 e field_2.

  3. O valor de providerFunction precisa corresponder ao nome de uma função no código da etapa. O providerFunction recupera o conteúdo real do recurso personalizado quando necessário.

    JSON

    {
    "workflowResourceDefinitions": [
        {
            "id": "resource_id",
            "name": "Custom Resource",
            "fields": [
                {
                    "selector": "field_1",
                    "name": "Field 1",
                    "dataType": {
                        "basicType": "STRING"
                    }
                },
                {
                    "selector": "field_2",
                    "name": "Field 2",
                    "dataType": {
                        "basicType": "STRING"
                    }
                }
            ],
            "providerFunction": "onMessageResourceFunction"
        }
    ]
}

  4. Em outputs[], especifique uma variável de saída que retorne um conjunto dinâmico de variáveis de saída. A variável de saída tem um dataType com a propriedade resourceType. O valor de cardinality precisa ser SINGLE.

    JSON

    "outputs": [{
        "id": "resource_data",
        "description": "Resource Data",
        "cardinality": "SINGLE",
        "dataType": {
          "resourceType": { "workflowResourceDefinitionId": "resource_id" }
        }
      }]

Confira um arquivo de manifesto completo que define um recurso personalizado:

JSON

{
    "timeZone": "America/Los_Angeles",
    "exceptionLogging": "STACKDRIVER",
    "runtimeVersion": "V8",
    "addOns": {
        "common": {
            "name": "Calculator",
            "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
            "useLocaleFromApp": true
        },
        "flows": {
            "workflowElements": [
                {
                    "id": "getResourceData",
                    "state": "ACTIVE",
                    "name": "Get Resource by ID",
                    "description": "Get Resource by ID",
                    "workflowAction": {
                        "outputs": [
                            {
                                "id": "resource_data",
                                "description": "Resource Data",
                                "cardinality": "SINGLE",
                                "dataType": {
                                    "resourceType": {
                                        "workflowResourceDefinitionId": "resource_id"
                                    }
                                }
                            }
                        ],
                        "onConfigFunction": "onConfigResourceFunction",
                        "onExecuteFunction": "onExecuteResourceFunction"
                    }
                }
            ],
            "workflowResourceDefinitions": [
                {
                    "id": "resource_id",
                    "name": "Custom Resource",
                    "fields": [
                        {
                            "selector": "field_1",
                            "name": "Field 1",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        },
                        {
                            "selector": "field_2",
                            "name": "Field 2",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        }
                    ],
                    "providerFunction": "onMessageResourceFunction"
                }
            ]
        }
    }
}

Editar o código

No código do aplicativo:

  1. Implemente o providerFunction, chamado onMessageResourceFunction() neste exemplo, que recupera o conteúdo do recurso personalizado quando necessário. Ele usa a entrada e, que é o payload JSON do objeto de evento da etapa, e define o ID do recurso personalizado.

    Apps Script

    function onMessageResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  var field_1 = ...;
  var field_2 = ...;

  return {
    "hostAppAction": {
      "workflowAction": {
        "resourceRetrievedAction": {
          "resourceJson": JSON.stringify({
            "field_1": field_1,
            "field_2": field_2,
          })
        }
      }
    }
  };
}

  2. A função de provedor precisa retornar o valor do recurso personalizado recuperando-o com um mecanismo adequado, como chamar uma API ou ler um banco de dados.

  3. Para recuperar e retornar um recurso personalizado pelo ID, retorne-o como returnOutputVariablesAction, conforme mostrado em onExecuteResourceFunction().

    Apps Script

    function onExecuteResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceReferences" : [ resource_id ]
            }
          }]
        }
      }
    }
  };
}

Confira um exemplo completo:

Apps Script

function onMessageResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  var field_1 = ...;
  var field_2 = ...;

  return {
    "hostAppAction": {
      "workflowAction": {
        "resourceRetrievedAction": {
          "resourceJson": JSON.stringify({
            "field_1": field_1,
            "field_2": field_2,
          })
        }
      }
    }
  };
}

function onExecuteResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceReferences" : [ resource_id ]
            }
          }]
        }
      }
    }
  };
}

Gerar um recurso personalizado como um valor

Ao gerar um recurso personalizado como uma referência, você retorna o recurso personalizado pelo ID em vez do objeto completo. Se você precisar transmitir o objeto de recurso inteiro, use resourceValues.

Em resourceValues, você define a saída de uma etapa.

Para gerar um recurso personalizado como um valor, edite o arquivo de manifesto e o código da etapa.

Editar o arquivo de manifesto

No arquivo de manifesto:

  1. Especifique um workflowResourceDefinitions e atribua um ID a ele.O workflowResourceDefinitions é uma estrutura que define tipos de dados e conteúdo do recurso personalizado. Em workflowResourceDefinitions, especifique os campos individuais que compõem o recurso personalizado, neste exemplo chamado field_1 e field_2.

  2. Especifique um providerFunction cujo valor seja o nome de uma função no código da etapa. O providerFunction recupera o conteúdo real do recurso personalizado quando necessário.

    JSON

    {
    "workflowResourceDefinitions": [
        {
            "id": "resource_id",
            "name": "Custom Resource",
            "fields": [
                {
                    "selector": "field_1",
                    "name": "Field 1",
                    "dataType": {
                        "basicType": "STRING"
                    }
                },
                {
                    "selector": "field_2",
                    "name": "Field 2",
                    "dataType": {
                        "basicType": "STRING"
                    }
                }
            ],
            "providerFunction": "onExecuteResourceAsValuesFunction"
        }
    ]
}

  3. Em outputs[], especifique uma variável de saída que retorne resourceValues. O valor de cardinality precisa ser SINGLE.

    JSON

    {
    "outputs": [
        {
            "id": "resource_data",
            "description": "Resource Data",
            "cardinality": "SINGLE",
            "dataType": {
                "resourceValues": {
                    "value1": "value one"
                }
            }
        }
    ]
}

Confira um arquivo de manifesto completo que define um recurso personalizado:

JSON

{
    "timeZone": "America/Los_Angeles",
    "exceptionLogging": "STACKDRIVER",
    "runtimeVersion": "V8",
    "addOns": {
        "common": {
            "name": "Calculator",
            "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
            "useLocaleFromApp": true
        },
        "flows": {
            "workflowElements": [
                {
                    "id": "getResourceData",
                    "state": "ACTIVE",
                    "name": "Get Resource by ID",
                    "description": "Get Resource by ID",
                    "workflowAction": {
                        "outputs": [
                            {
                                "id": "resource_data",
                                "description": "Resource Data",
                                "cardinality": "SINGLE",
                                "dataType": {
                                    "resourceValues": {
                                        "value1": "value one"
                                    }
                                }
                            }
                        ],
                        "onConfigFunction": "onConfigResourceFunction",
                        "onExecuteFunction": "onExecuteResourceFunction"
                    }
                }
            ],
            "workflowResourceDefinitions": [
                {
                    "id": "resource_id",
                    "name": "Custom Resource",
                    "fields": [
                        {
                            "selector": "field_1",
                            "name": "Field 1",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        },
                        {
                            "selector": "field_2",
                            "name": "Field 2",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        }
                    ],
                    "providerFunction": "onExecuteResourceAsValuesFunction"
                }
            ]
        }
    }
}

Editar o código

No código do aplicativo, implemente o providerFunction, chamado onExecuteResourceAsValuesFunction() neste exemplo, que define e retorna o recurso personalizado como JSON, aqui abstraído como resourceJSON:

Apps Script

function onExecuteResourceAsValuesFunction() {
  var field_1 = "value 1";
  var field_2 = "value 2";
  var resourceJSON = JSON.stringify({
    "field_1": field_1,
    "field_2": field_2,
  });
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceValues" : [ resourceJSON ]
            }
          }]
        }
      }
    }
  };
}