نمایش داده‌های پیچیده با یک منبع سفارشی

برنامه آلفای جمینی: فلوز به عنوان بخشی از برنامه آلفای جمینی در دسترس است.

این راهنما نحوه تعریف منابع سفارشی برای Google Workspace Flows را توضیح می‌دهد.

منابع سفارشی، ساختارهای داده سفارشی هستند که می‌توانید برای گروه‌بندی چندین متغیر با هم تعریف کنید. به عنوان مثال، برای ایجاد یک سرنخ CRM، یک منبع سفارشی حاوی آدرس ایمیل، آدرس خیابان و نام را ارسال کنید.

این دو روش برای تعریف منابع سفارشی هستند:

• به عنوان مرجع: وقتی یک منبع سفارشی را به عنوان مرجع خروجی می‌دهید، منبع سفارشی را به جای شیء منبع سفارشی کامل، با شناسه‌اش برمی‌گردانید. این کار با کاهش داده‌های منتقل شده بین مراحل جریان، عملکرد را بهبود می‌بخشد. وقتی داده‌ها نیاز به جستجوی ثانویه دارند، بازگرداندن شناسه آن برای انجام آن جستجوها مفید است.
• به عنوان مقدار: از این متد زمانی استفاده کنید که داده‌ها باید در حین اجرا بازیابی شوند، یا زمانی که منبع سفارشی کوچک است و حاوی داده‌های حساس نیست.

خروجی یک منبع سفارشی به عنوان مرجع

با خروجی دادن یک منبع سفارشی به عنوان مرجع، می‌توانید منبع سفارشی را به جای کل شیء منبع سفارشی، با شناسه‌اش برگردانید. اگر یک منبع سفارشی بزرگ یا پیچیده باشد، ارسال فقط شناسه با کاهش داده‌های منتقل شده بین مراحل جریان، عملکرد را بهبود می‌بخشد.

برای خروجی گرفتن از یک منبع سفارشی به عنوان مرجع، فایل و کد مانیفست مربوط به هر مرحله را ویرایش کنید.

فایل مانیفست را ویرایش کنید

در فایل مانیفست:

1. یک workflowResourceDefinitions مشخص کنید و یک id ، یک آرایه fields[] و یک providerFunction به آن اختصاص دهید. workflowResourceDefinitions ساختاری است که انواع داده‌ها و محتوای منبع سفارشی را تعریف می‌کند.

2. درون آرایه fields[] ، فیلدهای منفردی که منبع سفارشی را تشکیل می‌دهند، مشخص می‌کنید که در این مثال field_1 و field_2 نامیده می‌شوند.

3. مقدار providerFunction باید با نام تابع در کد مرحله مطابقت داشته باشد. providerFunction در صورت نیاز، محتوای منبع سفارشی واقعی را بازیابی می‌کند.

   جی‌سون

   {
       "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 باشد.

   جی‌سون

   "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": "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 که همان شیء رویداد مرحله (step) از نوع 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. تابع ارائه دهنده باید مقدار منبع سفارشی را با بازیابی آن با یک مکانیسم مناسب، مانند فراخوانی یک API یا خواندن یک پایگاه داده، برگرداند.

3. برای بازیابی و بازگرداندن یک منبع سفارشی بر اساس شناسه (ID)، آن را به صورت 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 مشخص کنید و به آن یک شناسه (id) اختصاص دهید. workflowResourceDefinitions ساختاری است که انواع داده‌ها و محتوای منبع سفارشی را تعریف می‌کند. در workflowResourceDefinitions ، فیلدهای جداگانه‌ای را که منبع سفارشی را تشکیل می‌دهند، مشخص می‌کنید که در این مثال field_1 و field_2 نامیده می‌شوند.

2. یک providerFunction مشخص کنید که مقدار آن نام یک تابع در کد مرحله باشد. providerFunction در صورت نیاز، محتوای منبع سفارشی واقعی را بازیابی می‌کند.

   جی‌سون

   {
       "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 باشد.

   جی‌سون

   {
       "outputs": [
           {
               "id": "resource_data",
               "description": "Resource Data",
               "cardinality": "SINGLE",
               "dataType": {
                   "resourceValues": {
                       "value1": "value one"
                   }
               }
           }
       ]
   }
   

در اینجا یک فایل مانیفست کامل وجود دارد که یک منبع سفارشی را تعریف می‌کند:

جی‌سون

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

مباحث مرتبط

• متغیرهای ورودی
• اعتبارسنجی یک متغیر ورودی
• متغیرهای خروجی
• ثبت فعالیت‌ها و خطاها
• شیء رویداد جریان