Parâmetros de configuração substituíveis

Com esses parâmetros, você pode permitir que os editores de relatórios alterem os valores padrão em uma fonte de dados. Definir parâmetros substituíveis dá flexibilidade à fonte e oferece aos usuários uma maneira de criar modelos de relatório configuráveis.

Por exemplo, um conector que fornece dados meteorológicos pode incluir um parâmetro de local para que os visualizadores de relatórios solicitem o boletim de uma região diferente do padrão.

Este documento descreve como os parâmetros substituíveis são definidos, como a modificação deles é ativada e como os valores de parâmetro podem ser alterados pelos usuários do relatório. Para saber mais sobre como os parâmetros são usados no Looker Studio, consulte Parâmetros da fonte de dados.

Papéis

Estas são as funções de usuário mencionadas ao longo do documento:

Papel	Definição
Desenvolvedor do conector	Usuário que criou um conector da comunidade
Proprietário da fonte de dados	Usuário que criou e possui uma fonte de dados
Editor de relatórios	Usuário com acesso ao modo de edição de um relatório
Visualizador de relatórios	Usuário com acesso ao modo de visualização de um relatório

Como definir parâmetros substituíveis

O desenvolvedor do conector define os parâmetros de configuração na função getConfig() de um conector da comunidade. Para defini-lo, o conector chama setAllowOverride(true).

Observação :os parâmetros também podem ser definidos como parte de uma consulta personalizada do BigQuery.

O exemplo a seguir define dois parâmetros substituíveis (zipcode e units), além de outro que não pode ser modificado (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();
}

Observação :o valor padrão de allowOverride é false. Se você não quiser ativar a modificação de um parâmetro, omita a chamada para setAllowOverride().

Quando não definir um parâmetro como substituível

É recomendável saber como os conectores, fontes de dados e relatórios funcionam juntos. Para isso, leia o artigo Como o Looker Studio se conecta aos seus dados.

Evite definir um parâmetro como substituível nos seguintes casos:

1. Quando o valor de um parâmetro afeta o esquema.
   • Se um usuário alterar um valor de parâmetro e o esquema das novas informações retornadas for diferente do definido na fonte, qualquer relatório dependente da fonte poderá ser interrompido devido a campos ausentes.
2. Se um valor de parâmetro controla dados confidenciais. Por exemplo: seleção de conta.
   • Não defina um parâmetro como substituível se quiser impedir a visualização ou o compartilhamento não intencional de dados confidenciais.

Como ativar parâmetros para os usuários do relatório

Os proprietários da fonte de dados controlam quais parâmetros substituíveis podem ser modificados pelos editores de relatórios. Da mesma forma, os editores definem quais parâmetros podem ser alterados pelos visualizadores de relatórios.

Permitir que os editores de relatórios modifiquem os valores dos parâmetros

O proprietário da fonte de dados controla quais parâmetros podem ser modificados nos relatórios. Isso é configurado durante a criação ou edição de uma fonte e se aplica apenas aos parâmetros que foram definidos como substituíveis pelo desenvolvedor do conector. Se essa opção estiver ativada, os editores poderão alterar os parâmetros em um relatório.

No exemplo a seguir, um conector tem dois parâmetros definidos como substituíveis: zipcode e units. O proprietário da fonte de dados só permitiu que zipcode fosse modificado. No relatório, o editor pode alterar o valor do parâmetro zipcode.

Permitir que os visualizadores de relatórios modifiquem os valores dos parâmetros

Os editores de relatórios controlam quais parâmetros podem ser modificados pelos visualizadores de relatórios. Qualquer visualizador pode alterar os valores de parâmetro por meio do URL do relatório.

Observação :o editor de relatórios só consegue mudar os parâmetros autorizados pelo proprietário da fonte de dados.

Por exemplo, considere um conector que tenha dois parâmetros definidos como substituíveis: zipcode e units (figura 1). Se o proprietário da fonte de dados permitiu a modificação de zipcode nos relatórios (figura 2), os editores de relatórios só poderão permitir que zipcode seja alterado pelos visualizadores de relatórios. O editor de relatórios não terá acesso ou visibilidade para permitir que o parâmetro units seja modificado pelos leitores de relatórios.

Figura 1: configuração do conector.

Figura 2: gerenciamento de parâmetros.

Aviso: os visualizadores de relatórios poderão acessar as informações controladas pelos parâmetros. Para evitar o compartilhamento não intencional de dados sensíveis, revise e confirme se a fonte de dados e as credenciais dela estão configuradas corretamente antes de permitir a modificação de um parâmetro. Se um parâmetro permitir o acesso a dados confidenciais, use as credenciais do visualizador para garantir que o visualizador de relatórios possa ver apenas as próprias informações.

Parâmetros de URL

Para permitir que os visualizadores de relatórios editem valores de parâmetro por meio do URL do relatório, faça o seguinte:

1. Edite o relatório.
2. Selecione Recurso -> Gerenciar parâmetros de URL do relatório.
3. Use as caixas de seleção Permitir modificação no URL do relatório para autorizar ou impedir a modificação de valores de parâmetro no URL do relatório. As mudanças são salvas automaticamente.
4. Clique em Fechar no canto superior direito.

Como modificar valores de parâmetro

Os editores de relatórios podem modificar valores de parâmetro usando o painel de propriedades do relatório, enquanto os visualizadores podem alterar esses valores por meio do URL do relatório.

Painel de propriedades do relatório

Para saber como um editor de relatórios pode definir valores de parâmetro, consulte Modificar parâmetros em um relatório.

Parâmetros de URL do relatório

No caso de parâmetros substituíveis no URL do relatório, os valores podem ser definidos por meio de um objeto JSON codificado pelo URL e anexado ao URL do relatório no modo de visualização.

Para criar uma configuração de URL, faça o seguinte:

1. Reunir nomes de parâmetros

   1. Edite o relatório.
   2. Selecione Recurso -> Gerenciar parâmetros de URL do relatório.
   3. Anote o nome dos parâmetros que você pretende definir por meio do URL do relatório.

   Por exemplo, na figura abaixo, o nome é ds0.zipcode.

   

2. Crie o objeto de parâmetro.

   Os parâmetros são definidos por meio de um objeto JSON. As chaves dos valores de parâmetro são os nomes dos parâmetros.

   {
     "parameterName": parameterValue
   }
   

   Os tipos de valor de parâmetro podem ser STRING, NUMBER ou BOOLEAN. No caso de parâmetros que aceitam diversos valores (como em menus suspensos de seleção múltipla), use uma matriz de valores.

   Por exemplo, se o nome do parâmetro for ds0.zipcode, para definir o CEP como 94094, o JSON será assim:

   {
     "ds0.zipcode": "94094"
   }
   

3. Codifique o objeto de parâmetro com URL.

   Depois que você criar o objeto de parâmetro, use JSON.stringify() para transformá-lo em uma string e utilize [encodeURIComponent] para codificar com URL.

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

   O resultado será a string codificada a seguir:

   "%7B%22ds0.zipcode%22%3A%2294094%22%7D"
   

4. Crie o URL do relatório.

   Depois que você codificar o objeto de parâmetro com URL, anexe-o ao URL da visualização do relatório usando o parâmetro de consulta de params.

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

   Lembre-se de substituir REPORT_ID e PAGE_ID pelos valores do seu relatório e da página.

5. Utilize o URL.

   O URL do relatório substituirá os parâmetros, conforme definido no objeto de parâmetros JSON, baseado na herança de parâmetro.

Exemplo de objeto de parâmetro

O objeto de parâmetro a seguir mostra como definir vários parâmetros. Ela também ilustra a definição de valores de parâmetro para os diferentes tipos de entrada.

• ds0.includeToday é uma entrada de caixa de seleção.
• ds0.units é uma entrada de seleção única.
• ds1.countries é uma entrada de seleção múltipla.
• ds1.labelName é uma entrada de texto.

  {
    "ds0.includeToday": true,
    "ds0.units": "Metric",
    "ds1.countries": ["Canada", "Mexico"],
    "ds1.labelName": "Population"
  }

Herança de parâmetro

O valor usado no parâmetro segue uma ordem de preferência com base em onde o parâmetro está definido. Aqueles configurados em locais com preferência maior substituem os definidos em lugares com prioridade menor. A ordem (da menor para a maior) é a seguinte:

1. Fonte de dados (padrão)
2. URL do relatório
3. Painel de propriedades do relatório, seguindo as regras de herança de parâmetro da fonte de dados