الإعداد المرحلي

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

المتطلبات

يفترض هذا الدليل أنّك على دراية بإعدادات Community Connector. راجِع تحديد الإعدادات من خلال getConfig لتنشيط ذاكرتك.

نظرة عامة

يتألف الإعداد على مراحل من استدعاء مركز البيانات getConfig() عدة مرات، وإرجاع الموصل المزيد من أسئلة الإعداد في كل مرة. سيتضمّن كل طلب إلى getConfig() إجابات المستخدم عن آخر ردّ getConfig(). تستمر هذه العملية طالما أنّك تعرض ردًا يتضمّن setIsSteppedConfig(true).

الإرشادات

اضبط setIsSteppedConfig(true) إلى أن تكتمل عملية الإعداد

سيطلب

مركز البيانات بشكل متكرّر getConfig() طالما تم ضبط setIsSteppedConfig(true).بعد اكتمال عملية الإعداد، يجب أن يضبط الردّ النهائي getConfig() على setIsSteppedConfig(false).

ضبط isDynamic(true) لأسئلة الإعداد التي تحدّد الأسئلة اللاحقة

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

سيتم تمرير الإجابات التي يقدّمها المستخدم عبر request.configParams.

ستكون قيمة request.configParams هي undefined لأول getConfig() طلب يتم إرساله إلى الموصل. ستتضمّن الطلبات اللاحقة الإجابات التي يقدّمها المستخدم كعنصر يتم تحديد مفتاحه حسب أرقام تعريف الإعدادات أو undefined إذا لم يقدّم المستخدم أي إجابات.

مثال:

{
  state: 'CA',
  city: 'mountain_view'
}

الإعدادات ترافقية

يجب إضافة أسئلة الإعدادات الجديدة بعد الأسئلة الحالية.

لا يمكن تغيير الإعدادات

إذا تم طرح سؤال حول الإعدادات سابقًا، يجب أن يظهر في جميع المكالمات اللاحقة. على سبيل المثال، إذا تم طرح سؤال الإعداد أ في أول طلب إلى getConfig()، يجب تضمين أ في جميع الردود المستقبلية.

الإعدادات متكرّرة

يجب أن تؤدي طلبات getConfig() التي تتضمّن configParams نفسه إلى عرض الإعدادات نفسها.

لا يمكن إلغاء المعلّمات الديناميكية

لن يسمح "مركز البيانات" بتجاوز مَعلمات الإعداد الديناميكي.

أمثلة على عمليات الضبط

القوائم المنسدلة الديناميكية

يدفع السؤال الأول المستخدم إلى اختيار ولاية، ثم يقدّم ديناميكيًا قائمة منسدلة بالمدن استنادًا إلى الولاية المحدّدة.

var cc = DataStudioApp.createCommunityConnector();

function optionsForState(state) {
  switch (state) {
    case "IL": {
      return [["Chicago", "chicago"], ["Springfield", "springfield"]];
    }
    case "CA": {
      return [["Mountain View", "mountain_view"], ["Los Angeles", "los_angeles"]];
    }
    default: {
      cc.newUserError()
          .setText('You must either select "IL" or "CA"')
          .throwException();
    }
  }
}

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config.newSelectSingle()
      .setId("state")
      .setName("State")
  // Set isDynamic to true so any changes to State will clear the city
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel("Illinois").setValue("IL"))
      .addOption(config.newOptionBuilder().setLabel("California").setValue("CA"));

  if (!isFirstRequest) {
    var city = config.newSelectSingle()
        .setId("city")
        .setName("City");
    var cityOptions = optionsForState(configParams.state);
    cityOptions.forEach(function(labelAndValue) {
      var cityLabel = labelAndValue[0];
      var cityValue = labelAndValue[1];
      city.addOption(config.newOptionBuilder().setLabel(cityLabel).setValue(cityValue));
    });
  }
  return config.build();
}

المسارات المتفرّعة

سيؤدي ذلك إلى طرح سؤال إضافي إذا كان "البلد" المحدّد هو "الولايات المتحدة الأمريكية".

var cc = DataStudioApp.createCommunityConnector();

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config
      .newSelectSingle()
      .setId('country')
      .setName('Country')
  // Set isDynamic to true so any changes to Country will clear the state
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel('United States').setValue('USA'))
      .addOption(config.newOptionBuilder().setLabel('Canada').setValue('CA'));

  if (!isFirstRequest) {
    // validate a valid value was selected for configParams.country
    if (configParams.country === undefined) {
      cc.newUserError().setText('You must choose a country.').throwException();
    }
    switch (configParams.country) {
      case 'USA': {
        config
            .newSelectSingle()
            .setId('state')
            .setName('State')
            .addOption(config.newOptionBuilder().setLabel('New York').setValue('NY'))
            .addOption(config.newOptionBuilder().setLabel('Calfornia').setValue('CA'));
        break;
      }
      case 'CA': {
        // No additional configuration is needed for Canada.
        break;
      }
      default: {
        cc.newUserError()
            .setText('You must either select "CA" or "USA"')
            .throwException();
      }
    }
  }
  return config.build();
}