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

Aplica-se a:Servidor SQL Tempo de execução da integração do SSIS no Azure Data Factory

Os parâmetros do Integration Services (SSIS) permitem atribuir valores a propriedades dentro de pacotes no momento da execução do pacote. Você pode criar parâmetros de projeto no nível do projeto e parâmetros de pacote no nível do pacote. Os parâmetros do projeto são usados para fornecer qualquer entrada externa que o projeto receba para um ou mais pacotes no projeto. Os parâmetros do pacote permitem que você modifique a execução do pacote sem ter que 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 SSIS. Você associa um parâmetro novo ou existente a uma propriedade de tarefa usando a caixa de diálogo Parametrizar .

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ê implanta um pacote que contém parâmetros usando o modelo de implantação de pacote e, em seguida, executa o pacote, os parâmetros não são chamados durante a execução. Se o pacote contiver parâmetros de pacote e expressões dentro do pacote use os parâmetros, os valores resultantes serão aplicados em tempo de execução. Se o pacote contiver parâmetros do projeto, a execução do pacote poderá falhar.

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

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

• Exibições (catálogo do Integration Services)

• Procedimentos armazenados (catálogo do Integration Services)

• Configurar caixa de diálogo

• Caixa de diálogo Executar pacote

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 e o parâmetro é resolvido para seu valor literal final.

A tabela a seguir lista os tipos de valores.

Você pode usar um único parâmetro para atribuir um valor a várias propriedades do pacote. Uma única propriedade de pacote pode ser atribuída a um valor somente a partir de um único parâmetro.

Execuções e valores de parâmetros

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

Quando você define explicitamente um valor de parâmetro de execução, o valor é aplicável somente a essa 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 do servidor será usado.

Quando um parâmetro é marcado como necessário, um valor de servidor ou valor de execução deve 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 design, ele nunca será usado depois 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 usado para a execução do pacote é conhecido como o valor do parâmetro de execução. Você especifica a referência de ambiente para uma execução 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 do servidor não é usado.

Para exibir as variáveis de ambiente atribuídas aos valores de parâmetro, consulte a visualização catalog.object_parameters. Para obter mais informações, consulte catalog.object_parameters (banco de dados SSISDB).

Determinando valores de parâmetros de execução

As exibições de Transact-SQL e o procedimento armazenado a seguir podem ser usados para exibir e definir valores de parâmetro.

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

catalog.get_parameter_values (Banco de Dados SSISDB) (procedimento armazenado)
Resolve e mostra os valores reais para o pacote especificado e referência de ambiente.

catalog.object_parameters (Banco de Dados SSISDB) (vista)
Exibe os parâmetros e as propriedades de todos os pacotes e projetos no catálogo do Integration Services, incluindo os valores padrão de design e de 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 SSDT (SQL Server Data Tools) para modificar o valor do parâmetro. Para obter mais informações, consulte Caixa de diálogo Executar pacote.

Você também pode usar a opção dtexec /Parameter para modificar um valor de parâmetro. Para obter mais informações, consulte dtexec Utility.

Validação de parâmetros

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

Para obter mais informações, consulte Caixa de diálogo Validar.

Exemplo de parâmetro

Este exemplo descreve um parâmetro chamado pkgOptions que é usado para especificar opções para o pacote no qual ele 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 é conhecido como o padrão de design. Se o projeto foi implantado no catálogo SSISDB e nenhum outro valor foi 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 todo o seu ciclo de vida.

Ao preparar uma instância específica de execução de pacote, um valor de 5 é atribuído ao parâmetro pkgOptions . Esse valor é conhecido como o valor de execução porque se aplica ao parâmetro somente para essa instância específica de execução. Quando a execução é iniciada, a propriedade package correspondente ao parâmetro pkgOptions recebe o valor de 5.

Criar parâmetros

Você usa o SSDT (SQL Server Data Tools) 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.

Criar parâmetros de pacote

1. Abra o pacote no SQL Server Data Tools e clique na guia Parâmetros no Designer SSIS.

   

2. Clique no botão Adicionar parâmetro na barra de ferramentas.

   

3. Insira valores para as propriedades Name, Data Type, Value, Sensitive e Required na própria lista ou na janela Properties . A tabela a seguir descreve essas propriedades.

   Propriedade	Description
   Nome	O nome do parâmetro.
   Tipo de dados	O tipo de dados do parâmetro.
   Valor predefinido	O valor padrão para o parâmetro atribuído em tempo de design. Isso também é conhecido como padrão de design.
   Sensível	Os 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	Requer que um valor, diferente do padrão de design, seja especificado antes que o pacote possa ser executado.
   Description	Para manutenção, a descrição do parâmetro. No SSDT (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.

   Observação

   Quando você implanta um projeto no catálogo, várias outras propriedades 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 ).

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

   Advertência

   Você pode editar in-loco na lista ou usar a janela Propriedades para modificar os valores das propriedades do 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 é usado somente quando você executa 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 ficará vazia e desabilitada.

Criar parâmetros do projeto

1. Abra o projeto no SQL Server Data Tools.

2. Clique com o botão direito do mouse em Project.params no Gerenciador de Soluções e clique em Abrir (OU), clique duas vezes em Project.params para abri-lo.

   

3. Clique no botão Adicionar parâmetro na barra de ferramentas.

   

4. Insira valores para as propriedades Name, Data Type, Value, Sensitive e Required .

   Propriedade	Description
   Nome	O nome do parâmetro.
   Tipo de dados	O tipo de dados do parâmetro.
   Valor predefinido	O valor padrão para o parâmetro atribuído em tempo de design. Isso também é conhecido como padrão de design.
   Sensível	Os 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	Requer que um valor, diferente do padrão de design, seja especificado antes que o pacote possa ser executado.
   Description	Para 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.

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

   Advertência

   Você pode editar in-loco na lista ou usar a janela Propriedades para modificar os valores das propriedades do 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 a caixa de diálogo Gerenciar Valores de Parâmetro , você pode especificar um valor para um parâmetro que é usado somente quando você executa o pacote no SQL Server Data Tools.

Caixa de diálogo Parametrizar

A caixa de diálogo Parametrizar permite associar um parâmetro novo ou existente a uma propriedade de uma tarefa. Para abrir a caixa de diálogo, clique com o botão direito do mouse em uma tarefa ou na guia Fluxo de controle no Designer SSIS e, em seguida, clique em Parametrizar. A lista a seguir descreve os elementos da interface do usuário na caixa de diálogo.

Opções

Property
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 utilize parâmetro
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 essa opção para criar um novo parâmetro que você deseja associar à propriedade da tarefa.

Nome
Especifique o nome do parâmetro que você deseja criar.

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

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

Scope
Especifique o escopo do parâmetro selecionando a opção Projeto ou Pacote . Os parâmetros do projeto são usados para fornecer qualquer entrada externa que o projeto receba para um ou mais pacotes no projeto. Os parâmetros do pacote permitem que você modifique a execução do pacote sem ter que editar e reimplantar o pacote.

Sensível
Especifique se o parâmetro é confidencial marcando ou desmarcando a caixa de seleção. Os 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
Especifique se o parâmetro requer que um valor, diferente do padrão de design, seja especificado antes que o pacote possa ser executado.

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

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

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

1. Selecione e clique com o botão direito do mouse no projeto no nó Integration Services .

2. Clique em Propriedades para abrir a janela de diálogo Propriedades do projeto .

3. Abra a página de parâmetros clicando em Parâmetros em Selecionar uma página.

4. Selecione o parâmetro desejado na lista Parâmetros . Nota: A coluna Container ajuda a distinguir os parâmetros do projeto dos parâmetros do pacote.

5. Na coluna Valor , especifique o valor do parâmetro padrão do servidor desejado.

Definir padrões de servidor com Transact-SQL

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