Переопределяемые параметры конфигурации

С помощью переопределяемых параметров конфигурации редакторы отчетов могут изменять в источнике данных значения по умолчанию. Переопределяемые параметры делают источник данных более гибким и позволяют создавать шаблоны отчетов, которые потом смогут настраивать пользователи.

Например, коннектор, предоставляющий данные о погоде, может включать параметр "Местоположение", позволяющий запрашивать отчеты для населенного пункта, который не совпадает с установленным по умолчанию.

Ниже рассказывается, как сделать параметры переопределяемыми и разрешить их изменение, а также как пользователи могут выбирать их значения в отчетах. Подробная информация об использовании параметров в Студии данных приведена в этой статье.

Роли

Роли пользователей, упоминаемые в этой статье:

Роль Описание
Разработчик коннектора Пользователь, который создал коннектор с открытым кодом.
Владелец источника данных Пользователь, который создал источник данных и является его владельцем.
Редактор отчета Пользователь, у которого есть разрешение на изменение отчета.
Читатель отчета Пользователь, у которого есть разрешение на просмотр отчета.

Как сделать параметры переопределяемыми

Разработчик коннектора задает параметры конфигурации в функции getConfig() коннектора с открытым кодом. Чтобы сделать какой-либо из параметров переопределяемым, необходимо выполнить вызов setAllowOverride(true).

Приведенный ниже пример включает два переопределяемых параметра (zipcode и units) и один непереопределяемый (days-to-forcecast).

Скриншот: два переопределяемых параметра

function getConfig(request) {
      var config = cc.getConfig();

      // A
      config
          .newTextInput()
          .setId("zipcode")
          .setName("ZIP Code")
          .setAllowOverride(true);

      // B
      config
        .newSelectSingle()
        .setId("units")
        .setName("Units")
        .addOption(
            config
              .newOptionBuilder()
              .setLabel("Metric")
              .setValue("metric")
        )
        .addOption(
          config
            .newOptionBuilder()
            .setLabel("Imperial")
            .setValue("imperial")
        )
        .setAllowOverride(true);

      // C
      config
        .newTextInput()
        .setId("days-to-forecast")
        .setName("Days to forecast")
          .setAllowOverride(false);

      return config.build();
    }
    

Когда лучше не делать параметр переопределяемым

Рекомендуем прочитать эту статью. В ней объясняется, как коннекторы, источники данных и отчеты взаимодействуют друг с другом.

Параметр лучше не делать переопределяемым в следующих случаях:

  1. Значение параметра влияет на схему.
    • Если схема получения данных для нового значения параметра будет отличаться от установленной в источнике данных, это может привести к ошибкам в отчетах из-за отсутствующих полей.
  2. Значение параметра связано с конфиденциальной информацией. Пример: выбор аккаунта.
    • Не делайте переопределяемым параметр, если это может привести к непреднамеренному открытию доступа к конфиденциальной информации.

Разрешение на изменение параметров

Владелец источника данных указывает, какие переопределяемые параметры могут изменять редакторы отчетов. Редактор отчетов, в свою очередь, настраивает такой доступ для читателей отчетов.

Разрешение на изменение параметров для редакторов отчетов

Владелец источника данных указывает, какие параметры можно изменять в отчетах. Эта настройка выполняется при создании или изменении источника данных и доступна только для тех параметров, которые разработчик коннектора сделал переопределяемыми. В результате редакторы отчетов смогут изменять параметры.

Например, рассмотрим коннектор с двумя переопределяемыми параметрами: zipcodeи units. Владелец источника данных разрешил изменять в отчетах только zipcode. Таким образом, редакторы отчетов могут изменять значение параметра zipcode.

Включение переопределения

Разрешение на изменение параметров для читателей отчетов

Редакторы отчетов указывают, какие параметры могут изменять читатели отчетов в URL отчета.

Например, рассмотрим коннектор с двумя переопределяемыми параметрами: zipcode и units (рис. 1). Поскольку владелец источника данных разрешил изменять в отчетах zipcode (рис. 2), редакторы отчетов в свою очередь смогут разрешить читателям отчетов изменять zipcode, а не units.

Параметр Zip code включен
Рис. 1. Конфигурация коннектора.

Изменять можно только параметр Zip code
Рис. 2. Управление параметрами.

Параметры URL

Чтобы разрешить читателям отчетов изменять значения параметров в URL отчета, выполните следующие действия:

  1. Измените отчет.
  2. Выберите Ресурс > Управление параметрами URL.
  3. Используйте флажки Разрешить изменения в URL отчета, чтобы разрешить или запретить изменение значений параметров в URL отчета. Ваши правки сохранятся автоматически.
  4. Нажмите Закрыть в правом верхнем углу.

Как изменять значения параметров

Редакторы могут изменять значения параметров на панели свойств отчета, а читатели – в URL отчета.

Панель свойств отчета

О том, как редактор отчета может задавать значения параметров, читайте в этой статье.

Параметры URL отчета

Если изменения в URL отчета разрешены, то значения параметра можно задать в объекте JSON, который добавляется в URL отчета в режиме просмотра.

Чтобы добавить конфигурацию в URL, выполните указанные ниже действия.

  1. Соберите имена параметров

    1. Измените отчет.
    2. Выберите Ресурс > Управление параметрами.
    3. Запишите имена нужных параметров.

    В примере, приведенном на рисунке ниже, имя параметра – ds0.zipcode.

    Включение параметров URL

  2. Создайте объект параметра

    Параметры определяются с помощью объекта JSON. В качестве ключей для значений параметров указываются имена параметров.

    {
          "parameterName": parameterValue
        }
        

    Допустимы следующие типы значений параметров: STRING, NUMBER и BOOLEAN. Параметр, принимающий сразу несколько значений (например, для раскрывающегося меню), можно задать с помощью массива значений.

    Например, если имя параметра – ds0.zipcode, то конфигурация JSON для присвоения параметру ZIP Code значения 94094 будет выглядеть так:

    {
          "ds0.zipcode": "94094"
        }
        
  3. Закодируйте объект параметра в URL

    После того как вы создали объект параметра, используйте метод JSON.stringify(), чтобы превратить его в строку, а затем [encodeURIComponent], чтобы перевести эту строку в URL-кодировку.

    var params = {
          "ds0.zipcode": "94094"
        };
        var paramsAsString = JSON.stringify(params);
        var encodedParams = encodeURIComponent(paramsAsString)
        

    Результат будет следующим:

    "%7B%22ds0.zipcode%22%3A%2294094%22%7D"
        
  4. Создайте URL отчета

    Добавьте готовый объект параметра в URL-кодировке в URL представления, используя параметр запроса params.

    https://datastudio.google.com/reporting/REPORT_ID/page/PAGE_ID?params=%7B%22ds0.zipcode%22%3A%2294094%22%7D

    Обязательно замените REPORT_ID и PAGE_ID значениями для вашего отчета и страницы.

  5. Используйте URL

    URL отчета с добавленным фрагментом будет переопределять параметры, определенные в объекте JSON, в соответствии с правилами наследования.

Пример объекта параметра

Ниже приведен пример объекта параметра, задающего несколько параметров. Этот пример также показывает, как задать значения параметров для входных данных разного типа.

  • Параметр ds0.includeToday предназначен для настройки флажка,
  • ds0.units – выбора одиночного значения,
  • ds1.countries – выбора нескольких значений,
  • ds1.labelName – ввода текста.
  {
        "ds0.includeToday": true,
        "ds0.units": "Metric",
        "ds1.countries": ["Canada", "Mexico"],
        "ds1.labelName": "Population"
      }
    

Правила наследования параметров

Значение параметра используется в порядке приоритета (в зависимости от того, где оно задано). Значения, заданные в объектах с более высоким приоритетом, переопределяют остальные. Используется следующий порядок приоритета (по возрастанию):

  1. Источник данных (по умолчанию)
  2. URL отчета
  3. Панель свойств отчета (в соответствии с правилами наследования параметров для источника данных)