Parâmetros de pacote e projeto do SSIS (Integration Services)

Artigo
05/23/2023

Aplica-se a:SQL Server SSIS Integration Runtime no Azure Data Factory

Os parâmetros doIntegration Services (SSIS) permitem atribuir valores às propriedades nos pacotes em tempo de execução do pacote. Você pode criar parâmetros de projeto em nível de projeto e parâmetros de pacote em nível de pacote. Os parâmetros do projeto são usados para fornecer uma entrada externa que o projeto recebe para um ou mais pacotes no projeto. Os parâmetros do pacote permitem modificar a execução do pacote sem a necessidade de editar e reimplantar o pacote.

No SQL Server Data Tools , você cria, modifica ou exclui parâmetros de projeto usando a janela Project.params . Você cria, modifica e exclui parâmetros de pacote usando a guia Parâmetros no Designer do SSIS . Você associa um novo parâmetro ou um existente à propriedade de uma tarefa usando a caixa de diálogo Parametrizar . Para saber mais sobre como usar a janela Project.params e a guia Parâmetros , consulte Create Parameters. Para obter mais informações sobre a caixa de diálogo Parametrizar , consulte Parameterize Dialog Box.

Parâmetros e modelo de implantação de pacote

Em geral, se você estiver implantando um pacote usando o modelo de implantação de pacote, deverá usar configurações em vez de parâmetros.

Quando você implantar um pacote que contém parâmetros usando o modelo de implantação de pacote e, em seguida, executar o pacote, os parâmetros não serão chamados durante a execução. Se o pacote contiver parâmetros de pacote e as expressões dentro do pacote usarem os parâmetros, os valores resultantes serão aplicados em runtime. Se o pacote contiver parâmetros de projeto, a execução de pacote poderá falhar.

Parâmetros e modelo de implantação de projeto

Quando você implantar um projeto no servidor Integration Services (SSIS), use exibições, procedimentos armazenados e a interface do usuário do SQL Server Management Studio para gerenciar o projeto e os parâmetros de pacote. Para obter mais informações, consulte os tópicos a seguir.

Valores dos parâmetros

Você pode atribuir até três tipos diferentes de valores a um parâmetro. Quando uma execução de pacote é iniciada, um único valor é usado para o parâmetro, o qual é resolvido para seu valor literal final.

A tabela a seguir lista os tipos de valores.

Nome do valor	DESCRIÇÃO	Tipo de valor
Valor de execução	O valor que é atribuído a uma instância específica da execução do pacote. Essa atribuição substitui todos os outros valores, mas se aplica apenas a uma única instância de execução do pacote.	Literal
Valor do servidor	O valor atribuído ao parâmetro dentro do escopo do projeto, depois que o projeto é implantado no servidor do Integration Services. Esse valor substitui o padrão de design.	Literal ou referência de variável de ambiente
Valor do design	O valor atribuído ao parâmetro quando o projeto é criado ou editado no SQL Server Data Tools. Esse valor persiste com o projeto.	Literal

Você pode usar um único parâmetro para atribuir um valor a várias propriedades de pacote. Uma única propriedade de pacote pode receber apenas um valor de um único parâmetro.

Execuções e valores de parâmetros

A execução é um objeto que representa uma única instância da execução do pacote. Ao criar uma execução, você especifica todos os detalhes necessários para executar um pacote, como os valores dos parâmetros de execução. Você também pode modificar os valores dos parâmetros para execuções existentes.

Quando você define explicitamente o valor de um parâmetro de execução, o valor é aplicável apenas àquela instância específica de execução. O valor de execução é usado em vez de um valor de servidor ou um valor de design. Se você não definir explicitamente um valor de execução, e um valor de servidor tiver sido especificado, o valor de servidor será usado.

Quando um parâmetro estiver marcado como obrigatório, um valor do servidor ou um valor da execução deverá ser especificado para esse parâmetro. Caso contrário, o pacote correspondente não será executado. Embora o parâmetro tenha um valor padrão em tempo de criação, ele nunca será usado assim que o projeto for implantado.

Variáveis de ambiente

Se um parâmetro fizer referência a uma variável de ambiente, o valor literal dessa variável será resolvido por meio da referência de ambiente especificada e aplicado ao parâmetro. O valor do parâmetro literal final que é usado para a execução do pacote é referenciado como o valor do parâmetro de execução. A referência de ambiente para uma execução é especificada usando a caixa de diálogo Executar

Se um parâmetro de projeto fizer referência a uma variável de ambiente e o valor literal da variável não puder ser resolvido na execução, o valor de design será usado. O valor de servidor não é usado.

Para exibir as variáveis de ambiente que são atribuídas a valores de parâmetros, consulte a exibição catalog.object_parameters. Para obter mais informações, confira catalog.object_parameters (Banco de dados SSISDB).

Determinando valores de parâmetros de execução

As seguintes exibições e procedimento armazenado Transact-SQL podem ser usados para exibir e definir valores de parâmetros.

catalog.execution_parameter_values (Banco de Dados SSISDB)(exibição)
Mostra os valores de parâmetros reais em uma execução específica.

catalog.get_parameter_values (Banco de dados SSISDB) (procedimento armazenado)
Resolve e mostra os valores reais do pacote especificado e da referência de ambiente.

catalog.object_parameters (Banco de Dados SSISDB) (exibição)
Exibe os parâmetros e as propriedades para todos os pacotes e projetos no catálogo do Integration Services , inclusive o padrão do design e os valores padrão do servidor.

catalog.set_execution_parameter_value (Banco de Dados SSISDB)
Define o valor de um parâmetro para uma instância de execução no catálogo do Integration Services .

Você também pode usar a caixa de diálogo Executar Pacote no SQL Server Data Tools (SSDT) para modificar o valor do parâmetro. Para obter mais informações, consulte Execute Package Dialog Box.

Você também pode usar a opção /Parameter do dtexec para modificar um valor de parâmetro. Para saber mais, veja dtexec Utility.

Validação de parâmetro

Se não for possível resolver os valores dos parâmetros, haverá falha na execução do pacote correspondente. Para ajudar a evitar falhas, você pode validar projetos e pacotes usando a caixa de diálogo Validar em SQL Server Data Tools (SSDT). A validação permite confirmar se todos os parâmetros têm os valores necessários ou se os valores necessários podem ser resolvidos com referências de ambiente específicas. A validação também verifica outros problemas comuns de pacotes.

Para obter mais informações, consulte Validate Dialog Box.

Exemplo de parâmetro

Este exemplo descreve um parâmetro denominado pkgOptions que é usado para especificar opções para o pacote no qual reside.

Durante o tempo de design, quando o parâmetro foi criado no SQL Server Data Tools, um valor padrão de 1 foi atribuído ao parâmetro. Esse valor padrão é referenciado como o padrão de design. Se o projeto for implantado no catálogo do SSISDB e nenhum outro valor tiver sido atribuído a esse parâmetro, a propriedade do pacote correspondente ao parâmetro pkgOptions receberá o valor de 1 durante a execução do pacote. O padrão de design persiste com o projeto durante seu ciclo de vida.

Na preparação de uma instância específica de execução do pacote, um valor 5 é atribuído ao parâmetro pkgOptions . Esse valor é referenciado como o valor de execução porque ele se aplica ao parâmetro apenas para aquela instância de execução específica. Quando a execução é iniciada, a propriedade do pacote correspondente ao parâmetro pkgOptions recebe o valor de 5.

Criar parâmetros

Use o SQL Server Data Tools (SSDT) para criar parâmetros de projeto e parâmetros de pacote. Os procedimentos a seguir fornecem instruções passo a passo para criar parâmetros de pacote/projeto.

Observação

Se você estiver convertendo um projeto criado usando uma versão anterior do Integration Services no modelo de implantação de projeto, use o Assistente de Conversão de Projeto do Integration Services para criar parâmetros com base em configurações. Para obter mais informações, consulte Implantar projetos e pacotes do SSIS (Integration Services).

Criar parâmetros de pacote

Abra o pacote no SQL Server Data Toolse clique na guia Parâmetros no SSIS Designer.
Clique no botão Adicionar Parâmetro na barra de ferramentas.

Insira valores para as propriedades Nome, Tipo de Dados, Valor, Diferenciae Obrigatório na própria lista ou na janela Propriedades . A tabela a seguir descreve essas propriedades.

Propriedade	Descrição
Nome	O nome do parâmetro.
Tipo de dados	O tipo de dados do parâmetro.
Valor padrão	O valor padrão do parâmetro atribuído em tempo de design. Também conhecido como o padrão de design.
Sigiloso	Valores de parâmetros confidenciais são criptografados no catálogo e aparecem como um valor NULL quando exibidos com o Transact-SQL ou o SQL Server Management Studio.
Obrigatório	Exige que um valor diferente do padrão de design seja especificado para que o pacote possa ser executado.
DESCRIÇÃO	Para fins de manutenção, a descrição do parâmetro. No SQL Server Data Tools (SSDT), defina a descrição do parâmetro na janela Propriedades do Visual Studio quando o parâmetro for selecionado na janela de parâmetros aplicável.

Observação

Quando você implanta um projeto no catálogo, várias propriedades adicionais são associadas ao projeto. Para ver todas as propriedades de todos os parâmetros no catálogo, use a exibição catalog.object_parameters (Banco de Dados SSISDB).

Salve o projeto para salvar as alterações nos parâmetros. Valores de parâmetros são armazenados no arquivo de projeto.

Aviso

Você pode editar no local na lista ou usar a janela Propriedades para modificar os valores de propriedades de parâmetro. Você pode excluir um parâmetro usando o botão da barra de ferramentas Excluir (X) . Usando o último botão da barra de ferramentas, você pode especificar um valor para um parâmetro que só seja usado quando você executar o pacote no SQL Server Data Tools.

Observação

Se você reabrir o arquivo de pacote sem abrir o projeto no SQL Server Data Tools, a guia Parâmetros estará vazia e desabilitada.

Criar parâmetros de projeto

Abra o projeto no SQL Server Data Tools.
Clique com o botão direito em Project.params no Gerenciador de Soluções e clique em Abrir (OU) clique duas vezes em Project.params para abri-lo.
Clique no botão Adicionar Parâmetro na barra de ferramentas.

Insira valores para as propriedades Nome, Tipo de Dados, Valor, Diferenciae Obrigatório .

Propriedade	Descrição
Nome	O nome do parâmetro.
Tipo de dados	O tipo de dados do parâmetro.
Valor padrão	O valor padrão do parâmetro atribuído em tempo de design. Também conhecido como o padrão de design.
Sigiloso	Valores de parâmetros confidenciais são criptografados no catálogo e aparecem como um valor NULL quando exibidos com o Transact-SQL ou o SQL Server Management Studio.
Obrigatório	Exige que um valor diferente do padrão de design seja especificado para que o pacote possa ser executado.
DESCRIÇÃO	Para fins de manutenção, a descrição do parâmetro. No SQL Server Data Tools, defina a descrição do parâmetro na janela Propriedades do Visual Studio quando o parâmetro for selecionado na janela de parâmetros aplicável.

Salve o projeto para salvar as alterações nos parâmetros. O valores de parâmetros são armazenados em configurações no arquivo de projeto. Salve o arquivo de projeto para confirmar em disco as alterações nos valores de parâmetros.

Aviso

Você pode editar no local na lista ou usar a janela Propriedades para modificar os valores de propriedades de parâmetro. Você pode excluir um parâmetro usando o botão da barra de ferramentas Excluir (X) . Usando o último botão da barra de ferramentas para abrir Gerenciar Valores de Parâmetro , você pode especificar um valor para um parâmetro que só seja usado quando você executar o pacote no SQL Server Data Tools.

Parameterize Dialog Box

A caixa de diálogo Parametrizar permite associar um parâmetro novo ou existente à propriedade de uma tarefa. Você abre a caixa de diálogo clicando com o botão direito em uma tarefa ou na guia Fluxo de Controle no Designer do SSIS e, em seguida, clique em Parametrizar. A lista a seguir descreve os elementos da interface de usuário na caixa de diálogo. Para obter mais informações sobre parâmetros, consulte Parâmetros do SSIS (Integration Services).

Opções

Propriedade
Selecione a propriedade da tarefa que você deseja associar a um parâmetro. Esta lista é preenchida com todas as propriedades que podem ser parametrizadas.

Usar parâmetro existente
Selecione esta opção para associar a propriedade da tarefa a um parâmetro existente e, em seguida, selecione o parâmetro na lista suspensa.

Não usar parâmetros
Selecione esta opção para remover uma referência a um parâmetro. O parâmetro não é excluído.

Criar novo parâmetro
Selecione esta opção para criar um novo parâmetro que você deseja associar à propriedade da tarefa.

Nome
Especifica o nome do parâmetro que você quer criar.

Descrição
Especifique a descrição para o parâmetro.

Valor
Especifique o valor padrão para o parâmetro. Isto também é conhecido como o padrão de design que pode ser substituído posteriormente no momento da implantação.

Escopo
Especifique o escopo do parâmetro selecionando a opção Projeto ou Pacote . Os parâmetros do projeto são usados para fornecer uma entrada externa que o projeto recebe para um ou mais pacotes no projeto. Os parâmetros do pacote permitem modificar a execução do pacote sem a necessidade de editar e reimplantar o pacote.

Confidencial
Especifique se o parâmetro é confidencial marcando ou desmarcando a caixa de seleção. Valores de parâmetros confidenciais são criptografados no catálogo e aparecem como um valor NULL quando exibidos com o Transact-SQL ou o SQL Server Management Studio.

Necessário
Especifique se o parâmetro exige que um valor diferente do padrão de design seja especificado para que o pacote possa ser executado.

Definir os valores de parâmetro após a implantação do projeto

O Assistente de Implantação permite definir valores de parâmetros padrão de servidor ao implantar seu projeto no catálogo. Depois que seu projeto estiver no catálogo, você pode usar o Pesquisador de Objetos do SQL Server Management Studio (SSMS) ou o Transact-SQL para definir valores padrão de servidor.

Definir os padrões do servidor com o Pesquisador de Objetos do SSMS

Selecione e clique com o botão direito do mouse no projeto sob o nó Integration Services.
Clique em Propriedades para abrir janela da caixa de diálogo Propriedades do Projeto.
Abra a página de parâmetros com um clique em Parâmetros sob Selecionar uma página.
Selecione o parâmetro desejado na lista Parâmetros. Observação: a coluna Contêiner ajuda a distinguir os parâmetros de projeto dos parâmetros de pacote.
Na coluna Valor, especifique o valor do parâmetro padrão de servidor desejado.

Definir os padrões do servidor com o Transact-SQL

Para definir padrões de servidor com Transact-SQL, use o procedimento armazenado catalog.set_object_parameter_value (Banco de Dados SSISDB). Para exibir os padrões atuais de servidor, confira a exibição catalog.object_parameters (Banco de Dados SSISDB). Para apagar um valor padrão de servidor, use o procedimento armazenado catalog.clear_object_parameter_value (Banco de Dados SSISDB).