Parâmetros de relatório paginado (Construtor de Relatórios)

Artigo
03/23/2023

Aplica-se a: SQL Server 2016 (13.x) Reporting Services e posterior SharePoint

Aplica-se a: SQL Server 2016 (13.x) Reporting Services e posterior

Este tópico 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. Você pode usar parâmetros de relatório em relatórios paginados criados no --- title: include file description: include file author: maggiesMSFT ms.author: maggies ms.date: 12/06/2018 ms.service: ms.topic: include ms.custom: include fileReport Builder e no Report Designer, e também em relatórios móveis criados no Publicador de Relatórios Móveis do SQL Server. Leia mais sobre os Conceitos de parâmetros de relatório.

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 é descontinuado a partir do Microsoft SQL Server Reporting Services 2022 e do Servidor de Relatórios do Power BI.

Para tentar adicionar um parâmetro a um relatório, confira Tutorial: Adicionar um Parâmetro ao Relatório (Construtor de Relatórios).

Usos comuns para parâmetros

Estas são as formas mais comuns de usar parâmetros.

Controle Paginado e Dados do Relatório Móvel

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, você não pode 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. Consulte Create mobile reports with SQL Server Mobile Report Publisher para obter mais informações.
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.

Conectar-se a relatórios relacionados

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 (Construtor de Relatórios e SSRS), Sub-relatórios (Construtor de Relatórios e SSRS) 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 e o outro 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

Enviar 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.
Permita que os usuários especifiquem valores para ajudar a 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.
Permitir que usuários personalizem dados e aparência de relatório incluindo os parâmetros em uma expressão.

Para obter mais informações, confiraReferências de Coleções de Parâmetros (Construtor de Relatórios e SSRS).

Exibindo um relatório com parâmetros

Ao ver um relatório que tem parâmetros, a barra de ferramentas do visualizador de relatórios exibe cada parâmetro de forma que você possa especificar valores de maneira interativa. A ilustração a seguir mostra a área de parâmetro de um relatório com os parâmetros @ReportMonth, @ReportYear, @EmployeeID, @ShowAll, @ExpandTableRows, @CategoryQuota e @SalesDate.

View report with parameters

Painel de parâmetros A barra de ferramentas do visualizador de relatórios exibe um aviso e valor padrão para cada parâmetro. Você pode personalizar o layout dos parâmetros no painel de parâmetros. Para obter mais informações, confira Personalizar o Painel de Parâmetros em um Relatório (Construtor de Relatórios).
Parâmetro @SalesDate O parâmetro @SalesDate é o tipo de dado DateTime. O prompt Selecionar uma 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.
Parâmetro ShowAll O parâmetro @ShowAll é o tipo de dados Boolean. Use os botões de opção para especificar True ou False.
Identificador Mostrar ou Ocultar Área de Parâmetros Na barra de ferramentas do visualizador de relatórios, clique nessa seta para mostrar ou ocultar o painel de parâmetros.
Parâmetro @CategoryQuota O parâmetro @CategoryQuota é o tipo de dadosFloat, portanto, leva um valor numérico. @CategoryQuota está definido para permitir vários valores.
Exibir Relatório Após inserir os valores de parâmetro, clique em Exibir Relatório para executar o relatório. Se todos os parâmetros tiverem valores padrão, o relatório será executado automaticamente na primeira exibição.

Criar parâmetros

Você pode criar 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.

Report Builder Parameter Dataset Properties

Esta imagem do Construtor de Relatórios mostra:

Os parâmetros de relatório no painel Dados do Relatório.
O conjunto de dados com os parâmetros.
O painel Parâmetros.
Os parâmetros listados na caixa de diálogo Propriedades de 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. Você poderá substituir os parâmetros de conjunto de dados que não estiverem marcados como internos.

Para obter mais informações, consulte Consulta de conjuntos de dados neste tópico.

Criar um parâmetro manualmente

Crie um parâmetro manualmente a partir do painel de 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. Você também pode 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 independentemente no servidor, a republicação de um relatório principal com novas configurações de parâmetros não substituirá 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. Você pode procurar parâmetros na Galeria de Partes de Relatório e, depois de adicioná-los, configurá-los em seu 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 dos parâmetros

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 são parâmetros em cascata. 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 (Construtor de Relatórios e SSRS).
Execute o relatório sem precisar primeiro selecionar um valor de parâmetro porque um valor padrão foi criado para o parâmetro.

Propriedades de parâmetros de relatório

É possível alterar as propriedades de parâmetros de relatório usando a caixa de diálogo de 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 deve começar com uma letra e pode conter letras, números e 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, consulte RDL Data Types.
Permitir valor em branco	Selecione esta opção se o valor do parâmetro puder ser uma cadeia de caracteres vazia ou ficar em branco. Se você especificar valores válidos para um parâmetro e desejar que um valor em branco seja um dos valores válidos, deverá incluí-lo como um dos valores que especificar. A seleção desta opção não inclui automaticamente um espaço em branco para valores disponíveis.
Permitir valor nulo	Selecione esta opção se o valor do parâmetro puder ser nulo. Se você especificar valores válidos para um parâmetro e desejar que um valor nulo seja um dos valores válidos, deverá incluir nulo como um dos valores que especificar. A seleção desta opção não inclui um valor nulo automaticamente nos 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. Essa é uma boa maneira de 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 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	Se você especificou valores disponíveis para um parâmetro, os valores válidos sempre aparecerão como uma lista suspensa. Por exemplo, se você fornecer valores disponíveis para um parâmetro DateTime , uma lista suspensa para datas aparecerá no painel de parâmetro em vez de um controle de calendário. Para assegurar que uma lista de valores seja consistente em um relatório e sub-relatórios, você poderá definir 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. 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 esta opção quando o parâmetro de relatório não 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 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, você pode 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 tópicos 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 (Construtor de Relatórios).
Para consultas baseadas em uma fonte de dados multidimensional como o Microsoft SQL Server Analysis Services, SAP NetWeaver BI ou Hyperion Essbase, você poderá especificar se um parâmetro será criado com base em um filtro que você definir no criador de consultas. Para saber mais, confira o tópico 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 o seguinte:

Propriedades de parâmetros 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, confiraRelatórios em Cache (SSRS).
Conjuntos de dados compartilhados armazenados em cache. 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, confiraRelatórios em 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ório. Você pode 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 à URL. Você pode 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. Se você adicionar ou excluir parâmetros da definição do relatório, ou alterar o tipo de dados ou o nome de um parâmetro existente, poderá ser necessário alterar as propriedades dos parâmetros no relatório publicado.

Nem todos os parâmetros podem ser modificados em todos os casos. Se um parâmetro de relatório obtiver um valor padrão de uma consulta de conjunto de dados, esse valor não poderá ser modificado para um relatório publicado e não poderá ser modificado no servidor de relatório. O valor usado em tempo de execução é determinado quando a consulta é executada ou, no caso de parâmetros baseados em expressão, 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

Você pode definir uma assinatura para um relatório sob demanda ou para um instantâneo e especificar valores de parâmetro a serem usados durante o processamento da assinatura.

Relatório sob demanda. Para um relatório sob demanda, você pode 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, confira Usar uma Fonte de Dados Externa para obter Dados de 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. Um 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 para usar parâmetros para dados de funcionários ou pessoais é selecionar os dados com base nas expressões que incluem o campo UserID da coleção Usuários. A coleção Usuários 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 outro usuário exibir o relatório e clicar no conteúdo do parâmetro renderizado, o usuário poderá executar acidentalmente o script ou 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, consulte Protegendo Relatórios e Recursos.