Partilhar via

Parâmetros de relatório paginado no Report Builder

  • Artigo

Aplica-se a: SQL Server 2016 (13.x) Reporting Services e versões posteriores SharePoint

Aplica-se a: SQL Server 2016 (13.x) Reporting Services e versões posteriores

Este artigo descreve os usos comuns dos parâmetros de relatório paginado, as propriedades que você pode definir e muito mais. Parâmetros de relatório o habilitam a controlar dados de relatório, conectar relatórios relacionados e variar a apresentação do relatório. Use parâmetros de relatório em relatórios paginados criados no Report Builder e no Report Designer. Você também pode usar parâmetros de relatório em relatórios móveis criados no Publicador de Relatórios Móveis do Microsoft SQL Server. Para obter mais informações sobre parâmetros, confira Conceitos de parâmetros de relatório em relatórios paginados (Report Builder).

Observação

O Publicador de Relatórios Móveis do SQL Server foi preterido em todas as versões do SQL Server Reporting Services posteriores ao SQL Server Reporting Services 2019. Ele foi descontinuado a partir do SQL Server Reporting Services 2022 e do Servidor de Relatórios do Power BI.

Para adicionar um parâmetro a um relatório, confira Conceitos de parâmetros de relatório em relatórios paginados (Report Builder).

Usos comuns de parâmetros

Alguns comuns de parâmetros:

Controle Paginado e dados do relatório móvel

O Report Builder e o Report Designer fornecem opções para filtrar dados com base no tipo de dados que você tem:

  • Filtre dados de relatório paginado na fonte de dados escrevendo consultas de conjunto de dados que contenham variáveis.

  • Filtre os dados de um conjunto de dados compartilhado. Ao adicionar um conjunto de dados compartilhado a um relatório paginado, não é possível alterar a consulta. No relatório, é possível adicionar um filtro de conjunto de dados que inclua uma referência a um parâmetro de relatório que você criou.

  • Filtre os dados de um conjunto de dados compartilhado em um relatório móvel do SQL Server. Para obter mais informações, consulte Criar relatórios móveis com o Publicador de Relatórios Móveis do SQL Server.

  • Habilite os usuários a especificar valores para personalizar os dados em um relatório paginado. Por exemplo, forneça dois parâmetros para a data de início e data de término em dados de vendas.

Utilize parâmetros para relacionar relatórios principais a relatórios detalhados, a sub-relatórios e a relatórios vinculados. Ao criar um conjunto de relatórios, geralmente você pode criar cada relatório para responder a determinadas questões. Cada relatório pode fornecer uma exibição diferente ou um nível diferente de detalhes das informações relacionadas. Para fornecer um conjunto de relatórios inter-relacionados, crie parâmetros para os dados relacionados nos relatórios de destino. Para obter mais informações, confira Relatórios de detalhamento em um relatório paginado (Report Builder), Sub-relatórios em relatórios paginados (Report Builder) e Criar um relatório vinculado.

Personalize conjuntos de parâmetros para vários usuários. Crie dois relatórios vinculados com base em um relatório de vendas no servidor de relatório. Um relatório vinculado usa valores de parâmetro predefinidos para vendedores. O segundo relatório vinculado usa valores de parâmetro predefinidos para gerentes de vendas. Os dois relatórios usam a mesma definição de relatório.

Variar apresentação do relatório

O Report Builder fornece ferramentas para variar suas apresentações:

  • Envie comandos a um servidor de relatório por meio de uma solicitação de URL, para personalizar a renderização de um relatório. Para obter mais informações, confiraAcesso à URL (SSRS) e Passar um parâmetro de relatório em uma URL.

  • É possível dar aos usuários a opção de especificar valores para que possam personalizar a aparência de um relatório. Por exemplo, forneça um parâmetro booliano para indicar se é para expandir ou recolher todos os grupos de linhas aninhados em uma tabela.

  • Permita que usuários personalizem os dados de relatório e a aparência incluindo parâmetros em uma expressão. Para obter mais informações, consulte Referências de coleção de parâmetros em um relatório paginado (Report Builder).

Exibir um relatório com parâmetros

Ao ver um relatório que tem parâmetros, o painel de Parâmetros exibe cada parâmetro de forma que você possa especificar valores de maneira interativa. A imagem a seguir mostra o painel de Parâmetros de um relatório com os parâmetros @ReportMonth, @ReportYear, @EmployeeID, @ShowAll, @ExpandTableRows, @CategoryQuota e @SalesDate.

Captura de tela que mostra o painel Parâmetros destacando diferentes parâmetros e ferramentas de interface.

  1. Painel Parâmetros: o painel de Parâmetros exibe um aviso e valor padrão para cada parâmetro. É possível personalizar o layout dos parâmetros. Para obter mais informações, confira Personalizar o painel de parâmetros em um relatório (Construtor de Relatórios).

  2. Parâmetro @SalesDate: o parâmetro @SalesDate é o tipo de dado Date/Time. O prompt Selecione a Data é exibido ao lado da caixa de texto. Para modificar a data, digite uma nova data na caixa de texto ou use o controle de calendário.

  3. Parâmetro @ShowAll: o parâmetro @ShowAll é o tipo de dados Booliano. Use os botões de opção para especificar True ou False.

  4. Identificador Mostrar ou Ocultar Área de Parâmetros: na barra de ferramentas do visualizador de relatórios, selecione essa seta para mostrar ou ocultar o painel de Parâmetros.

  5. Parâmetro @CategoryQuota O parâmetro @CategoryQuota é o tipo de dados Float, portanto, leva um valor numérico. @CategoryQuota está definido para permitir vários valores.

  6. Exibir Relatório: após inserir os valores de parâmetro, selecione Exibir Relatório para executar o relatório. Quando todos os parâmetros têm valores padrão, o relatório é executado automaticamente na primeira exibição.

Criar parâmetros

É possível parâmetros de relatório de algumas maneiras diferentes:

Observação

Nem todas as fontes de dados oferecem suporte a parâmetros.

Consulta de conjunto de dados ou procedimento armazenado com parâmetros

Adicionar uma consulta de conjunto de dados que contenha variáveis ou um procedimento armazenado de banco de dados que contenha parâmetros de entrada. Um parâmetro de conjunto de dados é criado para cada variável ou parâmetro de entrada e um parâmetro de relatório é criado para cada parâmetro de conjunto de dados.

Captura de tela que mostra o Report Builder realçando o painel Dados do Relatório, o painel Parâmetros e a caixa de diálogo Propriedades do Conjunto de Dados.

Esta imagem do Construtor de Relatórios mostra:

  1. Os parâmetros do relatório no painel Dados do Relatório.

  2. O conjunto de dados com os parâmetros.

  3. O painel Parâmetros.

  4. Os parâmetros listados na caixa de diálogo Propriedades do Conjunto de Dados.

O conjunto de dados pode ser inserido ou compartilhado. Ao adicionar um conjunto de dados compartilhado a um relatório, os parâmetros de conjunto de dados marcados como internos não poderão ser substituídos no relatório. É possível substituir os parâmetros de conjunto de dados que não estiverem marcados como internos.

Para obter mais informações, confira Consulta de conjunto de dados.

Criar um parâmetro manualmente

Crie um parâmetro manualmente por meio do painel Dados do Relatório. É possível configurar os parâmetros de relatório de forma que um usuário possa inserir valores interativamente para ajudar a personalizar o conteúdo ou a aparência de um relatório. É possível também configurar parâmetros de relatório de forma que um usuário não possa alterar os valores pré-configurados.

Observação

Como os parâmetros são gerenciados de maneira independente no servidor, a nova publicação de um relatório principal com novas configurações de parâmetros não substitui as configurações de parâmetros existentes no relatório.

Parte de relatório com um parâmetro

Observação

As partes de relatório são preteridas para todas as versões de SQL Server Reporting Services, começando com o SQL Server Reporting Services 2019, e para todas as versões do Servidor de Relatórios do Power BI, começando com o Servidor de Relatórios do Power BI de setembro de 2022.

Adicione uma parte de relatório que contenha referências a um parâmetro ou a um conjunto de dados compartilhado que contém variáveis.

As partes de relatório são armazenadas no servidor de relatório e disponibilizadas para uso em relatórios de outras pessoas. As partes de relatório que são parâmetros não podem ser gerenciados de um servidor de relatório. É possível pesquisar parâmetros na Galeria de Partes de Relatório. Depois de adicioná-los, configure-os no relatório. Para obter mais informações, confira Partes de Relatório (Construtor de Relatórios e SSRS).

Observação

Parâmetros podem ser publicados como uma parte de relatório separada para regiões de dados que têm conjuntos de dados dependentes com parâmetros. Embora parâmetros sejam listados como parte de um relatório, você não pode acrescentar um parâmetro de parte de relatório diretamente a um relatório. Em vez disso, adicione a parte de relatório, e quaisquer parâmetros de relatório necessários serão gerados automaticamente de consultas de conjunto de dados contidas ou referenciadas pela parte de relatório. Para obter mais informações sobre partes de relatório, confira Partes de Relatório (Construtor de Relatórios e SSRS) e Partes de relatório no Designer de Relatórios (SSRS).

Valores de parâmetro

As seguintes opções servem para seleção de valores de parâmetro em um relatório:

  • Selecione um valor de parâmetro único da lista suspensa.

  • Selecione vários valores de parâmetro da lista suspensa.

  • Selecione um valor da lista suspensa para um parâmetro, o qual determina os valores que estão disponíveis na lista suspensa para outro parâmetro. Esses valores são parâmetros em cascata. Os parâmetros em cascata permitem que você filtre milhares de valores de parâmetro sucessivamente para obter um número gerenciável.

    Para obter mais informações, confira Adicionar parâmetros em cascata a um relatório paginado (Report Builder).

  • Execute o relatório sem precisar primeiro selecionar um valor de parâmetro porque um valor padrão já existe para o parâmetro.

Propriedades de parâmetros de relatório

Altere as propriedades de parâmetro de relatório usando a caixa de diálogo Propriedades do Relatório. A tabela a seguir resume as propriedades que você pode definir para cada parâmetro:

Propriedade Descrição
Nome Digite um nome com diferenciação de maiúsculas e minúsculas para o parâmetro. O nome precisa começar com uma letra e pode conter letras, números e um sublinhado (_). O nome não pode conter espaços. Para parâmetros gerados automaticamente, o nome corresponde ao parâmetro na consulta de conjunto de dados. Por padrão, parâmetros criados manualmente são semelhantes a ReportParameter1.
Prompt O texto que aparece ao lado do parâmetro na barra de ferramentas do visualizador de relatórios.
Tipo de dados Um parâmetro de relatório deve ser de um destes tipos de dados:

Boolean. O usuário seleciona Verdadeiro ou Falso usando um botão de opção.

DateTime. O usuário seleciona uma data usando um controle de calendário.

Integer. O usuário digita valores em uma caixa de texto.

Float. O usuário digita valores em uma caixa de texto.

Text. O usuário digita valores em uma caixa de texto.

Quando os valores disponíveis são definidos para um parâmetro, o usuário escolhe valores em uma lista suspensa, mesmo que o tipo de dados seja DateTime.

Para obter mais informações sobre os tipos de dados de relatório, confira Tipos de dados de RDL.
Permitir valor em branco Selecione esta opção quando o valor do parâmetro pode ser uma cadeia de caracteres vazia ou pode ficar em branco.

Quando você especifica valores válidos para um parâmetro e deseja que um valor em branco seja um dos valores válidos, deve incluí-lo como um dos valores que especificar. A seleção dessa opção não inclui automaticamente um espaço para os valores disponíveis.
Permitir valor nulo Selecione esta opção se o valor do parâmetro puder ser nulo.

Quando você especifica valores válidos para um parâmetro e deseja que um valor nulo seja um dos valores válidos, deve incluir nulo como um dos valores especificados. A seleção dessa opção não inclui automaticamente um nulo para os valores disponíveis.
Permitir diversos valores Forneça valores disponíveis para criar uma lista suspensa na qual seus usuários possam fazer seleções. Use esta propriedade para assegurar que somente valores válidos sejam enviados na consulta de conjunto de dados.

Selecione esta opção se o valor do parâmetro puder ter diversos valores exibidos em uma lista suspensa. Valores nulos não são permitidos. Quando essa opção é selecionada, as caixas marcadas são adicionadas à lista de valores disponíveis em uma lista suspensa de parâmetros. A parte superior da lista inclui uma caixa de seleção para Selecionar Tudo. Os usuários podem marcar os valores desejados.

Se os dados que fornecem valores forem alterados rapidamente, a lista que o usuário verá talvez não seja a mais atual.
Visible Selecione esta opção para exibir o parâmetro de relatório na parte superior do relatório quando ele for executado. Esta opção permite que os usuários selecionem valores de parâmetro em tempo de execução.
Hidden Selecione essa opção para ocultar o parâmetro no relatório publicado. Os valores de parâmetro de relatório ainda podem ser definidos em uma URL de relatório, em uma definição de assinatura ou no servidor de relatório.
Interna Selecione essa opção para ocultar o parâmetro de relatório. No relatório publicado, o parâmetro de relatório só pode ser exibido na definição do relatório.
Valores disponíveis Quando você especifica valores disponíveis para um parâmetro, os valores válidos sempre aparecem como uma lista suspensa. Por exemplo, quando você fornece valores disponíveis para um parâmetro DateTime, uma lista suspensa para datas aparece no painel de Parâmetro em vez de um controle de calendário.

Defina uma opção na fonte de dados para usar uma única transação para todas as consultas nos conjuntos de dados que forem associados a uma fonte de dados. Essa opção garante que a lista de valores seja consistente entre o relatório e os sub-relatórios.

Observação de segurança Em qualquer relatório que inclua um parâmetro do tipo de dados Text, use uma lista de valores disponíveis (também conhecida como uma lista de valores válidos) e garanta que qualquer usuário que execute o relatório tenha somente as permissões necessárias para exibir os dados no relatório. Para obter mais informações, confiraSegurança (Construtor de Relatórios).
Valores padrão Defina os valores padrão usando uma consulta ou uma lista estática.

Quando cada parâmetro tem um valor padrão válido, o relatório é executado automaticamente na primeira exibição.
Avançado Defina o atributo de definição de relatório UsedInQuery, um valor que indica se o parâmetro em questão afeta direta ou indiretamente os dados de um relatório.

Determinar automaticamente quando atualizar
Escolha esta opção para que o processador de relatório determine uma configuração para este valor. O valor será True se o processador de relatório detectar uma consulta de conjunto de dados com uma referência direta ou indireta a este parâmetro, ou se o relatório tiver sub-relatórios.

Atualizar sempre
Escolha esta opção quando o parâmetro de relatório for usado direta ou indiretamente em uma consulta de conjunto de dados ou em uma expressão de parâmetro. Esta opção define UsedInQuery como True.

Nunca atualizar
Escolha essa opção quando o parâmetro de relatório é usado direta ou indiretamente em uma expressão de parâmetro ou uma consulta de conjunto de dados. Esta opção define UsedInQuery como False.

Cuidado Use a opção Nunca Atualizar com cuidado. No servidor de relatório, UsedInQuery é usado para ajudar a controlar as opções de cache para os dados de relatórios e para relatórios renderizados, além de opções de parâmetro para relatórios de instantâneo. Se você definir incorretamente a opção Nunca Atualizar , é possível que os dados de relatórios ou os relatórios incorretos sejam armazenados em cache, ou que um relatório de instantâneo apresente dados inconsistentes. Para obter mais informações, confira Linguagem RDL (SSRS).

Consulta do conjunto de dados

Para filtrar dados na consulta de conjunto de dados, é possível incluir uma cláusula de restrição que limite os dados recuperados especificando valores a serem incluídos ou excluídos do conjunto de resultados.

Use o designer de consulta para a fonte de dados para criar uma consulta parametrizada.

  • Para consultas Transact-SQL, fontes de dados diferentes dão suporte a diferentes tipos de sintaxe para parâmetros. O suporte abrange parâmetros que são identificados na consulta por posição ou por nome. Para obter mais informações, confira os artigos sobre tipos de fontes de dados externos específicos em Conjuntos de Dados de Relatórios (SSRS). No designer de consulta relacional, você deve selecionar a opção de parâmetro para um filtro para poder criar uma consulta parametrizada. Para obter mais informações, confira Interface do usuário do designer de consultas relacionais (Report Builder).

  • Especifique se deseja criar um parâmetro com base em um filtro especificado no designer de consulta. Faça essa especificação para consultas baseadas em uma fonte de dados multidimensional como o Microsoft SQL Server Analysis Services, SAP NetWeaver BI ou Hyperion Essbase. Para saber mais, confira o artigo sobre o designer de consultas em Ferramentas de Designers de Consultas (SSRS) que corresponda à extensão de dados.

Gerenciamento de parâmetros para um relatório publicado

Quando você cria um relatório, os parâmetros de relatório são salvos na definição de relatório. Quando você publica um relatório, os parâmetros de relatório são salvos e gerenciados separadamente da definição de relatório.

Para um relatório publicado, você pode usar as seguintes ferramentas:

  • Propriedades de parâmetro de relatório: altere os valores de parâmetros de relatório diretamente no servidor de relatório, de modo independente da definição de relatório.

  • Relatórios armazenados em cache: para criar um plano de cache para um relatório, cada parâmetro deve ter um valor padrão. Para obter mais informações, consulte Relatórios de cache (SSRS).

  • Conjuntos de dados compartilhados: para criar um plano de cache para um conjunto de dados compartilhado, cada parâmetro deve ter um valor padrão. Para obter mais informações, consulte Relatórios de cache (SSRS).

  • Relatórios vinculados: você pode criar relatórios vinculados com valores de parâmetro predefinidos para filtrar dados para públicos distintos. Para obter mais informações, consulte Criar um relatório vinculado.

  • Assinaturas de relatórios: é possível especificar valores de parâmetro para filtrar dados e entregar relatórios por meio de assinaturas. Para obter mais informações, confira Assinaturas e entrega (Reporting Services).

  • Acesso da URL: é possível especificar valores de parâmetro em uma URL para um relatório. Também é possível executar relatórios e especificar valores de parâmetros usando o acesso à URL. Para obter mais informações, confira Acesso à URL (SSRS).

As propriedades de parâmetros para um relatório publicado serão preservadas se você publicar novamente a definição do relatório. Se a definição do relatório for publicada novamente como o mesmo relatório, e os nomes e tipos de dados dos parâmetros continuarem os mesmos, as configurações de propriedades serão retidas. Quando você adiciona ou exclui parâmetros da definição de relatório ou alterar o tipo de dados ou o nome de um parâmetro existente, pode ser necessário alterar as propriedades de parâmetro no relatório publicado. Talvez seja necessário alterar as propriedades para alterar o tipo de dados ou o nome de um parâmetro existente.

Nem todos os parâmetros podem ser modificados em todos os casos. Quando um parâmetro de relatório obtém um valor padrão de uma consulta de conjunto de dados, esse valor não pode ser modificado para um relatório publicado. Ele também não pode ser modificado no servidor de relatório. O valor usado no tempo de execução é determinado quando a consulta é executada. Quando você usa parâmetros baseados em expressão, eles são determinado quando a expressão é avaliada.

As opções de execução de relatório podem afetar o tipo de processamento dos parâmetros. Um relatório executado como um instantâneo não pode usar parâmetros derivados de uma consulta, a menos que a consulta inclua valores padrão para os parâmetros.

Parâmetros para uma assinatura

É possível definir uma assinatura para um relatório sob demanda ou para um instantâneo e especificar os valores de parâmetro a serem usados durante o processamento da assinatura.

  • Relatórios sob demanda: para um relatório sob demanda, é possível especificar um valor de parâmetro diferente do valor publicado para cada parâmetro listado para o relatório. Por exemplo, suponha que você tenha um relatório Serviço de Chamada que usa um parâmetro Período de Tempo para retornar solicitações de atendimento ao cliente para o dia, semana ou mês atual. Se o valor de parâmetro padrão do relatório for definido como hoje, sua assinatura poderá usar um valor de parâmetro diferente (como semana ou mês) para produzir um relatório com estatísticas semanais ou mensais.

  • Instantâneo: para um instantâneo, sua assinatura deve usar os valores de parâmetro definidos para o instantâneo. Sua assinatura não pode substituir um valor de parâmetro que está definido para um instantâneo. Por exemplo, suponha que você esteja assinando um relatório de vendas regional ocidental executado como um instantâneo de relatório e que o instantâneo especifique Ocidental como um valor de parâmetro regional. Nesse caso, se você criar uma assinatura para esse relatório, deverá usar o valor de parâmetro Ocidental em sua assinatura. Para fornecer uma indicação visual de que o parâmetro é ignorado, os campos de parâmetro da página da assinatura são definidos como campos somente leitura.

  • As opções de execução de relatório podem afetar o tipo de processamento dos parâmetros. Os relatórios parametrizados executados como instantâneos de relatório usam os valores de parâmetro definidos para o instantâneo de relatório. Os valores de parâmetro estão definidos na página de Propriedades de parâmetro do relatório. Um relatório executado como um instantâneo não pode usar parâmetros derivados de uma consulta, a menos que a consulta inclua valores padrão para os parâmetros.

  • Se um valor de parâmetro for alterado no instantâneo de relatório após a definição da assinatura, o servidor de relatório desativará a assinatura. A desativação da assinatura indica que o relatório foi modificado. Abra a assinatura e salve-a para ativá-la.

Observação

As assinaturas controladas por dados podem usar valores de parâmetro obtidos de uma fonte de dados de assinante. Para obter mais informações, consulte Usar uma fonte de dados externa para dados do assinante (assinatura controlada por dados).

Para obter mais informações, confira Assinaturas e entrega (Reporting Services).

Parâmetros e proteção de dados

Tenha cuidado ao distribuir relatórios parametrizados que contêm informações confidenciais. O usuário pode substituir facilmente um parâmetro de relatório por um valor diferente, resultando na divulgação indevida de informações.

Uma alternativa segura à definição de parâmetros para dados de funcionários ou pessoais é selecionar os dados com base nas expressões que incluem o campo UserID dos Campos Internos. O UserID fornece um meio de obter a identidade do usuário que executa o relatório e de usar essa identidade para recuperar dados específicos do usuário.

Importante

Em qualquer relatório que contenha um parâmetro do tipo String, use uma lista de valores disponíveis (também conhecida como uma lista de valores válidos) e verifique se todos os usuários que executam o relatório têm as permissões necessárias para exibir os dados do relatório apenas. Quando você define um parâmetro do tipo String, é exibida para o usuário uma caixa de texto que pode ter qualquer valor. Uma lista de valores disponíveis limita os valores que podem ser inseridos. Se o parâmetro do relatório estiver associado a um parâmetro de conjunto de dados e uma lista de valores disponíveis não for usada, um usuário do relatório poderá digitar a sintaxe SQL na caixa de texto, abrindo potencialmente o relatório e o servidor a um ataque de injeção de SQL. Se o usuário tiver permissões suficientes para executar a nova instrução SQL, resultados indesejados podem ser produzidos no servidor.

Se um parâmetro de relatório não estiver associado a um parâmetro de conjunto de dados e os valores de parâmetro forem incluídos no relatório, um usuário do relatório poderá digitar a sintaxe de expressão ou uma URL no valor de parâmetro e renderizar o relatório em Excel ou HTML. Se, em seguida, outro usuário visualizar o relatório e selecionar o conteúdo do parâmetro renderizado, o usuário poderá executar acidentalmente o script ou o link mal-intencionado.

Para reduzir o risco de execução acidental de scripts mal-intencionados, só abra relatórios renderizados de fontes confiáveis. Para obter mais informações sobre como proteger relatórios, confira Proteger relatórios e recursos.