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

يوضّح هذا الدليل كيفية تحديد موارد مخصّصة لـ 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"
           }
         }
       }
     ],
   }
   

في ما يلي ملف بيان كامل يحدّد موردًا مخصّصًا:

{
  "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