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

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

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

• כתובת אימייל
• רחוב
• שם

כדי לוודא שכל הנתונים שנדרשים ליצירת ליד במערכת 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": "Custom Resource (as reference)",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "getResourceDataReference",
          "state": "ACTIVE",
          "name": "Custom Resource (as reference)",
          "description": "Output a custom resource as a reference",
          "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 שהוא מטען ייעודי של אובייקט אירוע JSON של השלב, ומגדירה ממנו את מזהה המשאב המותאם אישית.

   Apps Script

   function onMessageResourceFunction(e) {
     console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));
   
     var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
     let fieldValue_1;
     let fieldValue_2;
   
     // Using a if-condition to mock a database call.
     if (resource_id == "sample_resource_reference_id") {
       fieldValue_1 = AddOnsResponseService.newVariableData()
         .addStringValue("value1");
       fieldValue_2 = AddOnsResponseService.newVariableData()
         .addStringValue("value2");
     } else {
       fieldValue_1 = AddOnsResponseService.newVariableData()
         .addStringValue("field_1 value not found");
       fieldValue_2 = AddOnsResponseService.newVariableData()
         .addStringValue("field_2 value not found");
     }
   
     let resourceData = AddOnsResponseService.newResourceData()
       .addVariableData("field_1", fieldValue_1)
       .addVariableData("field_2", fieldValue_2)
   
     let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
       .setResourceData(resourceData)
   
     let hostAppAction = AddOnsResponseService.newHostAppAction()
       .setWorkflowAction(workflowAction);
   
     return AddOnsResponseService.newRenderActionBuilder()
       .setHostAppAction(hostAppAction)
       .build();
   }
   

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

3. כדי לאחזר משאב מותאם אישית ולהחזיר אותו לפי המזהה שלו, מחזירים אותו כ-returnOutputVariablesAction, כמו שמוצג ב-onExecuteResourceFunction().

   Apps Script

   function onExecuteResourceFunction(e) {
     console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));
   
     let outputVariables = AddOnsResponseService.newVariableData()
       .addResourceReference("sample_resource_reference_id");
   
     let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
       .addVariableData("resource_data", outputVariables);
   
     let hostAppAction = AddOnsResponseService.newHostAppAction()
       .setWorkflowAction(workflowAction);
   
     return AddOnsResponseService.newRenderActionBuilder()
       .setHostAppAction(hostAppAction)
       .build();
   }
   

דוגמה מלאה:

Apps Script

function onConfigResourceFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextParagraph()
        .setText("This is the Custom Resource Demo card")
    );

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

  return card;
}

function onMessageResourceFunction(e) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  let fieldValue_1;
  let fieldValue_2;

  // Using a if-condition to mock a database call.
  if (resource_id == "sample_resource_reference_id") {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("value1");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("value2");
  } else {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("field_1 value not found");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("field_2 value not found");
  }

  let resourceData = AddOnsResponseService.newResourceData()
    .addVariableData("field_1", fieldValue_1)
    .addVariableData("field_2", fieldValue_2)

  let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(resourceData)

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

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

function onExecuteResourceFunction(e) {
  console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));

  let outputVariables = AddOnsResponseService.newVariableData()
    .addResourceReference("sample_resource_reference_id");

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("resource_data", outputVariables);

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

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

נושאים קשורים

• משתני קלט
• אימות משתנה קלט
• משתני פלט
• רישום פעילות ושגיאות ביומן
• אובייקטים של אירועים ב-Workspace Studio