ייצוג נתונים מורכבים באמצעות משאב בהתאמה אישית

במדריך הזה מוסבר איך מגדירים משאבים בהתאמה אישית ל-Google Workspace Flows.

משאבים מותאמים אישית הם מבני נתונים מותאמים אישית שאפשר להגדיר כדי לקבץ כמה משתנים יחד. לדוגמה, כדי ליצור ליד במערכת לניהול קשרי לקוחות (CRM), צריך להעביר משאב בהתאמה אישית שמכיל כתובת אימייל, כתובת ורחוב ושם.

אלה שתי הדרכים להגדיר משאבים בהתאמה אישית:

  • כערך הפניה: כשמוציאים משאב מותאם אישית כהפניה, מחזירים את המשאב המותאם אישית לפי המזהה שלו במקום אובייקט המשאב המותאם אישית המלא. הפעולה הזו משפרת את הביצועים כי היא מצמצמת את כמות הנתונים שמועברים בין השלבים בתהליך. כשצריך לבצע חיפושים משניים של נתונים, כדאי להחזיר את המזהה שלהם כדי לבצע את החיפושים האלה.
  • כערך: משתמשים בשיטה הזו כשצריך לאחזר את הנתונים במהלך ההפעלה, או כשמקור המידע המותאם אישית קטן ולא מכיל נתונים רגישים.

הצגת משאב מותאם אישית כהפניה

אם מוציאים משאב בהתאמה אישית כהפניה, אפשר להחזיר את המשאב בהתאמה אישית לפי המזהה שלו במקום לפי אובייקט המשאב המלא בהתאמה אישית. אם משאב מותאם אישית גדול או מורכב, העברת המזהה בלבד משפרת את הביצועים כי היא מצמצמת את כמות הנתונים שמועברת בין שלבי התהליך.

כדי להוציא משאב בהתאמה אישית כהפניה, עורכים את קובץ המניפסט ואת הקוד של השלב.

עריכת קובץ המניפסט

בקובץ המניפסט:

  1. מציינים workflowResourceDefinitions ומקצים לו id, מערך fields[] ו-providerFunction. ‫workflowResourceDefinitions הוא מבנה שמגדיר את סוגי הנתונים והתוכן של המשאב המותאם אישית.

  2. במערך fields[], מציינים את השדות הנפרדים שמרכיבים את המשאב המותאם אישית, שבדוגמה הזו נקרא field_1 ו-field_2.

  3. הערך של providerFunction צריך להיות זהה לשם של פונקציה בקוד של השלב. ‫providerFunction מאחזר תוכן בפועל של משאב בהתאמה אישית כשצריך.

    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. ב-outputs[], מציינים משתנה פלט שמחזיר קבוצה דינמית של משתני פלט. למשתנה הפלט יש מאפיין dataType עם הערך resourceType. הערך של cardinality חייב להיות SINGLE.

    JSON

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

זו דוגמה לקובץ מניפסט מלא שמגדיר משאב בהתאמה אישית:

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

עריכת הקוד

בקוד האפליקציה:

  1. מטמיעים את providerFunction, שנקרא onMessageResourceFunction() בדוגמה הזו, כדי לאחזר תוכן של משאב מותאם אישית כשצריך. היא מקבלת את הקלט e שהוא מטען ייעודי (payload) של אובייקט אירוע JSON של השלב, ומגדירה ממנו את מזהה המשאב המותאם אישית.

    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. פונקציית הספק צריכה להחזיר את הערך של המשאב המותאם אישית על ידי אחזור שלו באמצעות מנגנון מתאים, כמו קריאה ל-API או קריאה למסד נתונים.

  3. כדי לאחזר משאב מותאם אישית ולהחזיר אותו לפי המזהה שלו, מחזירים אותו כ-returnOutputVariablesAction, כמו שמוצג ב-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 ]
            }
          }]
        }
      }
    }
  };
}

דוגמה מלאה:

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

הצגת משאב מותאם אישית כערך

כשמוציאים משאב בהתאמה אישית כהפניה, מחזירים את המשאב בהתאמה אישית לפי המזהה שלו במקום לפי אובייקט המשאב המלא בהתאמה אישית. אם אתם צריכים להעביר את אובייקט המשאב כולו, אתם יכולים לעשות זאת באמצעות resourceValues.

ב-resourceValues, מגדירים את הפלט של השלב.

כדי להוציא משאב מותאם אישית כערך, צריך לערוך את קובץ המניפסט והקוד של השלב.

עריכת קובץ המניפסט

בקובץ המניפסט:

  1. מציינים workflowResourceDefinitions ומקצים לו מזהה.workflowResourceDefinitions הוא מבנה שמגדיר סוגי נתונים ותוכן של המשאב המותאם אישית. בתוך workflowResourceDefinitions, מציינים את השדות הנפרדים שמרכיבים את המשאב המותאם אישית. בדוגמה הזו, השדות נקראים field_1 ו-field_2.

  2. מציינים providerFunction שהערך שלו הוא שם של פונקציה בקוד של השלב. ‫providerFunction מאחזר תוכן בפועל של משאב בהתאמה אישית כשצריך.

    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. ב-outputs[], מציינים משתנה פלט שמחזיר את הערך resourceValues. הערך של cardinality חייב להיות SINGLE.

    JSON

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

זו דוגמה לקובץ מניפסט מלא שמגדיר משאב בהתאמה אישית:

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

עריכת הקוד

בקוד האפליקציה, מטמיעים את providerFunction, שנקרא onExecuteResourceAsValuesFunction() בדוגמה הזו, שמגדיר ומחזיר את המשאב המותאם אישית כ-JSON, שמוצג כאן בצורה מופשטת כ-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 ]
            }
          }]
        }
      }
    }
  };
}