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

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

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

• آدرس ایمیل
• آدرس خیابان
• نام

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

3. برای بازیابی و بازگرداندن یک منبع سفارشی بر اساس شناسه (ID)، آن را به صورت 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();
}

مباحث مرتبط

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