Przedstawianie złożonych danych za pomocą zasobu niestandardowego

Z tego przewodnika dowiesz się, jak definiować zasoby niestandardowe w przypadku przepływów Google Workspace.

Zasoby niestandardowe to struktury danych, które możesz zdefiniować, aby grupować ze sobą wiele zmiennych. Aby na przykład utworzyć potencjalnego klienta w systemie CRM, przekaż niestandardowy zasób zawierający adres e-mail, adres i imię.

Zasoby niestandardowe można zdefiniować na 2 sposoby:

  • Jako odwołanie: gdy wyświetlasz zasób niestandardowy jako odwołanie, zwracasz go za pomocą identyfikatora zamiast pełnego obiektu zasobu niestandardowego. Zwiększa to wydajność, ponieważ zmniejsza ilość danych przesyłanych między poszczególnymi krokami przepływu. Gdy dane wymagają dodatkowych wyszukiwań, zwracanie ich identyfikatora jest przydatne do przeprowadzania tych wyszukiwań.
  • Jako wartość: użyj tej metody, gdy dane muszą być pobierane podczas wykonywania lub gdy zasób niestandardowy jest mały i nie zawiera danych wrażliwych.

Wyświetlanie niestandardowego zasobu jako odwołania

Wyprowadzając zasób niestandardowy jako odniesienie, możesz zwrócić zasób niestandardowy według jego identyfikatora zamiast całego obiektu zasobu niestandardowego. Jeśli zasób niestandardowy jest duży lub złożony, przekazywanie tylko identyfikatora zwiększa wydajność, ponieważ zmniejsza ilość danych przesyłanych między krokami przepływu.

Aby wygenerować niestandardowy zasób jako odwołanie, edytuj plik manifestu kroku i kod.

Edytowanie pliku manifestu

W pliku manifestu:

  1. Określ workflowResourceDefinitions i przypisz do niego id, tablicę fields[] i providerFunction. workflowResourceDefinitions to struktura, która określa typy danych i zawartość zasobu niestandardowego.

  2. W tablicy fields[] określasz poszczególne pola, które składają się na zasób niestandardowy, w tym przykładzie o nazwach field_1 i field_2.

  3. Wartość parametru providerFunction musi odpowiadać nazwie funkcji w kodzie kroku. providerFunction pobiera w razie potrzeby rzeczywistą zawartość zasobu niestandardowego.

    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. W outputs[] określ zmienną wyjściową, która zwraca dynamiczny zbiór zmiennych wyjściowych. Zmienna wyjściowa ma dataType z właściwością resourceType. Wartość cardinality musi wynosić SINGLE.

    JSON

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

Oto pełny plik manifestu, który definiuje zasób niestandardowy:

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

Edytuj kod

W kodzie aplikacji:

  1. Zaimplementuj funkcję providerFunction, która w tym przykładzie ma nazwę onMessageResourceFunction() i w razie potrzeby pobiera zawartość zasobu niestandardowego. Pobiera dane wejściowe e, czyli ładunek JSON obiektu zdarzenia kroku, i na jego podstawie ustawia niestandardowy identyfikator zasobu.

    Google 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. Funkcja dostawcy musi zwracać wartość zasobu niestandardowego, pobierając ją za pomocą odpowiedniego mechanizmu, np. wywołując interfejs API lub odczytując bazę danych.

  3. Aby pobrać i zwrócić zasób niestandardowy według jego identyfikatora, zwróć go jako returnOutputVariablesAction, jak pokazano w onExecuteResourceFunction().

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

Oto pełny przykład:

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

Wyświetlanie zasobu niestandardowego jako wartości

Gdy wygenerujesz niestandardowy zasób jako odwołanie, zwrócisz go według identyfikatora zamiast pełnego obiektu niestandardowego zasobu. Jeśli musisz przekazać cały obiekt zasobu, możesz to zrobić za pomocą resourceValues.

W sekcji resourceValues określasz dane wyjściowe kroku.

Aby wygenerować zasób niestandardowy jako wartość, zmień plik manifestu i kod kroku.

Edytowanie pliku manifestu

W pliku manifestu:

  1. Określ workflowResourceDefinitions i przypisz mu identyfikator.workflowResourceDefinitions to struktura, która definiuje typy danych i zawartość zasobu niestandardowego. W workflowResourceDefinitions określasz poszczególne pola, które składają się na zasób niestandardowy. W tym przykładzie są to pola field_1 i field_2.

  2. Określ providerFunction, którego wartością jest nazwa funkcji w kodzie kroku. providerFunction pobiera w razie potrzeby rzeczywistą zawartość zasobu niestandardowego.

    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. W polu outputs[] określ zmienną wyjściową, która zwraca wartość resourceValues. Wartość cardinality musi wynosić SINGLE.

    JSON

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

Oto pełny plik manifestu, który definiuje zasób niestandardowy:

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

Edytuj kod

W kodzie aplikacji zaimplementuj funkcję providerFunction, która w tym przykładzie nazywa się onExecuteResourceAsValuesFunction(). Definiuje ona i zwraca niestandardowy zasób w formacie JSON, który w tym przykładzie jest abstrakcyjnie oznaczony jako resourceJSON:

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