Karmaşık verileri özel bir kaynakla temsil etme

Bu kılavuzda, Google Workspace Studio için özel kaynakların nasıl tanımlanacağı açıklanmaktadır.

Özel kaynaklar, birden fazla değişkeni birlikte gruplandırmak için tanımlayabileceğiniz özel veri yapılarıdır. Bir adımın çıktısı statik bir yapıya sahip olduğunda bunu özel bir kaynakla temsil edin. Örneğin, bir CRM potansiyel müşterisi oluşturmak için çıkışınızda birden fazla değişken gerekir:

  • E-posta adresi
  • Açık adres
  • Ad

CRM potansiyel müşterisi oluşturmak için gereken tüm verilerin bulunduğundan emin olmak amacıyla e-posta adresi, açık adres ve ad içeren özel bir kaynak oluşturun.

Özel kaynağı referans olarak çıktı alma

Özel bir kaynağı referans olarak vererek, özel kaynağı tam özel kaynak nesnesi yerine kimliğiyle döndürebilirsiniz. Özel bir kaynak büyük veya karmaşıksa yalnızca kimliğin iletilmesi, adımlar arasında aktarılan verileri azaltarak performansı artırır.

Özel bir kaynağı referans olarak çıkışa aktarmak için adımın manifest dosyasını ve kodunu düzenleyin.

Manifest dosyasını düzenleme

Manifest dosyasında:

  1. Bir workflowResourceDefinitions belirtin ve buna bir id, bir fields[] dizisi ve bir providerFunction atayın. workflowResourceDefinitions, özel kaynağın veri türlerini ve içeriklerini tanımlayan bir yapıdır.

  2. fields[] dizisinde, özel kaynağı oluşturan tek tek alanları belirtirsiniz. Bu örnekte, bu alanlar field_1 ve field_2 olarak adlandırılmıştır.

  3. providerFunction değerinin, adımın kodundaki bir işlevin adıyla eşleşmesi gerekir. providerFunction, gerektiğinde gerçek özel kaynak içeriğini alır.

    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[] içinde, dinamik bir çıktı değişkenleri grubu döndüren bir çıktı değişkeni belirtin. Çıkış değişkeni, resourceType özelliğine sahip bir dataType içerir. cardinality değeri SINGLE olmalıdır.

    JSON

    {
  "outputs": [
    {
      "id": "resource_data",
      "description": "Resource Data",
      "cardinality": "SINGLE",
      "dataType": {
        "resourceType": {
          "workflowResourceDefinitionId": "resource_id"
        }
      }
    }
  ],
}

Özel bir kaynağı tanımlayan eksiksiz bir manifest dosyası aşağıda verilmiştir:

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

Kodu düzenle

Uygulama kodunda:

  1. Gerekli olduğunda özel kaynak içeriğini alan providerFunction işlevini uygulayın. Bu örnekte işlevin adı onMessageResourceFunction()'dır. Bu işlev, adımın event object JSON payload'u olan e girişini alır ve bu girişten özel kaynak kimliğini ayarlar.

    Apps Komut Dosyası

    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. Sağlayıcı işlevi, bir API'yi çağırma veya bir veritabanını okuma gibi uygun bir mekanizmayla alarak özel kaynağın değerini döndürmelidir.

  3. Özel bir kaynağı kimliğine göre almak ve döndürmek için onExecuteResourceFunction()'te gösterildiği gibi returnOutputVariablesAction olarak döndürün.

    Apps Komut Dosyası

    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();
}

Aşağıda eksiksiz bir örnek verilmiştir:

Apps Komut Dosyası

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();
}