تمثيل البيانات المعقّدة باستخدام مورد مخصّص

يوضّح هذا الدليل كيفية تحديد مراجع مخصّصة في Google Workspace Studio.

الموارد المخصّصة هي بنى بيانات مخصّصة يمكنك تحديدها لتجميع عدة متغيرات معًا. عندما يكون لناتج إحدى الخطوات بنية ثابتة، مثِّله باستخدام مورد مخصّص. على سبيل المثال، لإنشاء عميل محتمل في نظام إدارة علاقات العملاء، يتطلّب الناتج عدّة متغيرات:

• عنوان البريد الإلكتروني
• عنوان الشارع
• الاسم

لضمان توفّر جميع البيانات المطلوبة لإنشاء عميل محتمل في نظام إدارة علاقات العملاء، أخرِج موردًا مخصّصًا يحتوي على عنوان بريد إلكتروني وعنوان شارع واسم.

إخراج مرجع لمورد مخصّص

من خلال إخراج مرجع لمورد مخصّص، يمكنك عرض المورد المخصّص باستخدام معرّفه بدلاً من كائن المورد المخصّص الكامل. إذا كان أحد الموارد المخصّصة كبيرًا أو معقّدًا، سيؤدي تمرير المعرّف فقط إلى تحسين الأداء من خلال تقليل البيانات المنقولة بين الخطوات.

لعرض مرجع لمورد مخصّص، عدِّل ملف البيان والرمز الخاصين بالخطوة.

تعديل ملف البيان

في ملف البيان:

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 الخاصة بعنصر الحدث للخطوة، وتضبط منه معرّف المورد المخصّص.

   برمجة التطبيقات

   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. يجب أن تعرض دالة الموفّر قيمة المورد المخصّص من خلال استردادها باستخدام آلية مناسبة، مثل استدعاء واجهة برمجة تطبيقات أو قراءة قاعدة بيانات.

3. لاسترداد مورد مخصّص وعرضه حسب معرّفه، يجب عرضه على النحو التالي: returnOutputVariablesAction، كما هو موضّح في onExecuteResourceFunction().

   برمجة التطبيقات

   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();
   }
   

في ما يلي مثال كامل:

برمجة التطبيقات

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