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

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

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

في ما يلي طريقتان لتحديد الموارد المخصّصة:

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

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

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

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

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

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

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

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

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

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

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

    function onExecuteResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceReferences" : [ resource_id ]
            }
          }]
        }
      }
    }
  };
}

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

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

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:

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

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