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

يوضّح هذا الدليل كيفية تحديد مراجع مخصّصة في 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 an 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 an 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