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

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

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

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

Роли

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

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

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

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

Примечание. Задать параметры можно и в пользовательском запросе BigQuery.

Приведенный ниже пример включает два переопределяемых параметра (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();
    }
    

Примечание. Значение по умолчанию для параметра allowOverride – false. Если вы не хотите делать параметр переопределяемым, опустите вызов setAllowOverride().

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

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

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

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

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

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

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

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

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

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

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

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

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

Рис. 1. Конфигурация коннектора.

Рис. 2. Управление параметрами.

Внимание! Читатели отчетов смогут просматривать все данные для установленного значения параметра. Чтобы исключить непреднамеренное открытие доступа к конфиденциальной информации, проверьте настройки источника данных и авторизации, перед тем как разрешить изменение параметра. Если параметр включает конфиденциальную информацию, рекомендуем настроить учетные данные читателей отчетов. Благодаря этому они смогут видеть только свои данные.

Параметры URL

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

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

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

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

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

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

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

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

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

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

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

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

   

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. Панель свойств отчета (в соответствии с правилами наследования параметров для источника данных)