Karmaşık verileri özel bir kaynakla temsil etme

Bu kılavuzda, Google Workspace Akışları 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. Örneğin, bir CRM potansiyel müşterisi oluşturmak için e-posta adresi, açık adres ve ad içeren özel bir kaynak iletin.

Özel kaynakları tanımlamanın iki yolu vardır:

  • Referans olarak: Özel bir kaynağı referans olarak çıkardığınızda, özel kaynak nesnesinin tamamı yerine özel kaynağı kimliğiyle döndürürsünüz. Bu, akış adımları arasında aktarılan verileri azaltarak performansı artırır. Veriler ikincil aramalar gerektirdiğinde, bu aramaları gerçekleştirmek için kimliğinin döndürülmesi faydalıdır.
  • Değer olarak: Verilerin yürütme sırasında alınması gerektiğinde veya özel kaynak küçük olduğunda ve hassas veriler içermediğinde bu yöntemi kullanın.

Özel bir 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ği iletmek, akış adımları arasında aktarılan verileri azaltarak performansı artırır.

Özel bir kaynağı referans olarak çıkarmak 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, 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": "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"
                }
            ]
        }
    }
}

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()'dir. 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) {
  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. 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()'da gösterildiği gibi returnOutputVariablesAction olarak döndürün.

    Apps Komut Dosyası

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

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

Apps Komut Dosyası

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

Özel bir kaynağı değer olarak çıkışa aktarma

Özel bir kaynağı referans olarak çıkardığınızda, özel kaynak nesnesinin tamamı yerine özel kaynağı kimliğiyle döndürürsünüz. Tüm kaynak nesnesini geçirmeniz gerekiyorsa resourceValues ile bunu yapabilirsiniz.

resourceValues bölümünde bir adımın çıktısını tanımlarsınız.

Özel bir kaynağı değer 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 kimlik atayın.workflowResourceDefinitions, veri türlerini ve özel kaynağın içeriklerini tanımlayan bir yapıdır. workflowResourceDefinitions içinde, özel kaynağı oluşturan alanları belirtirsiniz. Bu örnekte bu alanlar field_1 ve field_2 olarak adlandırılır.

  2. Değeri, adımın kodundaki bir işlevin adı olan bir providerFunction belirtin. 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": "onExecuteResourceAsValuesFunction"
        }
    ]
}

  3. outputs[] bölümünde, resourceValues değerini döndüren bir çıkış değişkeni belirtin. cardinality değeri SINGLE olmalıdır.

    JSON

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

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

Kodu düzenle

Uygulama kodunda, özel kaynağı JSON olarak tanımlayan ve döndüren providerFunction işlevini (bu örnekte onExecuteResourceAsValuesFunction() olarak adlandırılır) uygulayın. Burada resourceJSON olarak soyutlanmıştır:

Apps Komut Dosyası

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