Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Aplica-se a:
SQL Server SSIS Integration Runtime em Azure Data Factory
As variáveis armazenam valores que um pacote do SQL Server Integration Services e seus contêineres, tarefas e manipuladores de eventos podem usar em tempo de execução. Os scripts na tarefa Script e no componente Script também podem usar variáveis. As restrições de precedência que sequenciam tarefas e contêineres em um fluxo de trabalho podem usar variáveis quando suas definições de restrição incluem expressões.
Você pode usar variáveis em pacotes do Integration Services para as seguintes finalidades:
Atualização das propriedades dos elementos do pacote em tempo de execução. Por exemplo, você pode definir dinamicamente o número de executáveis simultâneos que um contêiner Foreach Loop permite.
Incluindo uma tabela de consulta em memória. Por exemplo, um pacote pode executar uma tarefa de SQL que carrega uma variável com valores de dados.
Carregando variáveis com valores de dados e, em seguida, usando-as para especificar uma condição de pesquisa em uma cláusula WHERE. Por exemplo, o script em uma tarefa Script pode atualizar o valor de uma variável que é usada por uma instrução Transact-SQL em uma tarefa Executar SQL.
Carregar uma variável com um número inteiro e depois usar esse valor para controlar o ciclo dentro do fluxo de controlo de um pacote. Por exemplo, você pode usar uma variável na expressão de avaliação de um contêiner For Loop para controlar a iteração.
Preenchimento de valores de parâmetros para declarações Transact-SQL durante a execução. Por exemplo, um pacote pode executar uma tarefa Executar SQL e, em seguida, usar variáveis para definir dinamicamente os parâmetros em uma instrução Transact-SQL.
Criação de expressões que incluem valores variáveis. Por exemplo, a transformação Coluna derivada pode preencher uma coluna com o resultado obtido multiplicando um valor de variável por um valor de coluna.
Sistema e variáveis definidas pelo utilizador
O Integration Services oferece suporte a dois tipos de variáveis: variáveis definidas pelo usuário e variáveis do sistema. As variáveis definidas pelo usuário são definidas pelos desenvolvedores de pacotes e as variáveis do sistema são definidas pelo Integration Services. Você pode criar quantas variáveis definidas pelo usuário um pacote exigir, mas não pode criar variáveis de sistema adicionais.
Todas as variáveis - sistema e definidas pelo usuário - podem ser usadas nas associações de parâmetros que a tarefa Executar SQL usa para mapear variáveis para parâmetros em instruções SQL. Para obter mais informações, consulte Executar tarefa SQL e parâmetros e códigos de retorno na tarefa Executar SQL.
Observação
Os nomes das variáveis definidas pelo usuário e do sistema são sensíveis a maiúsculas e minúsculas.
Você pode criar variáveis definidas pelo usuário para todos os tipos de contêiner do Integration Services: pacotes, contêineres Foreach Loop, contêineres For Loop, contêineres Sequence, tarefas e manipuladores de eventos. As variáveis definidas pelo usuário são membros da coleção Variables do contêiner.
Se você criar o pacote usando o Designer SSIS, poderá ver os membros das coleções Variáveis nas pastas Variáveis na guia Explorador de Pacotes do Designer SSIS. As pastas listam variáveis definidas pelo usuário e variáveis do sistema.
Você pode configurar variáveis definidas pelo usuário das seguintes maneiras:
Forneça um nome e uma descrição para a variável.
Especifique um namespace para a variável.
Indique se a variável gera um evento quando seu valor muda.
Indique se a variável é somente leitura ou leitura/gravação.
Use o resultado da avaliação de uma expressão para definir o valor da variável.
Crie a variável no escopo do pacote ou um objeto de pacote, como uma tarefa.
Especifique o valor e o tipo de dados da variável.
A única opção configurável em variáveis de sistema é especificar se elas geram um evento quando mudam de valor.
Um conjunto diferente de variáveis do sistema está disponível para diferentes tipos de contêiner. Para obter mais informações sobre as variáveis de sistema usadas pelos pacotes e seus elementos, consulte Variáveis do sistema.
Para obter mais informações sobre cenários de uso da vida real para variáveis, consulte Usar variáveis em pacotes.
Propriedades das variáveis
Você pode configurar variáveis definidas pelo usuário definindo as seguintes propriedades na janela Variáveis ou na janela Propriedades . Determinadas propriedades estão disponíveis apenas na janela Propriedades.
Observação
A única opção configurável em variáveis de sistema é especificar se elas geram um evento quando mudam de valor.
Descrição
Especifica a descrição da variável.
EvaluateAsExpression
Quando a propriedade é definida como True, a expressão fornecida é usada para definir o valor da variável.
Expressão
Especifica a expressão atribuída à variável.
Nome
Especifica o nome da variável.
Espaço de nomes
O Integration Services fornece dois namespaces, Usuário e Sistema. Por padrão, as variáveis personalizadas estão no namespace User e as variáveis de sistema estão no namespace System . Você pode criar namespaces adicionais para variáveis definidas pelo usuário e alterar o nome do namespace User , mas não pode alterar o nome do namespace System , adicionar variáveis ao namespace System ou atribuir variáveis de sistema a um namespace diferente.
RaiseChangedEvent
Quando a propriedade é definida como True, o evento OnVariableValueChanged é gerado quando a variável altera o valor.
Apenas leitura
Quando a propriedade é definida como False, a variável é read\write.
Âmbito de aplicação
Observação
Você pode alterar essa configuração de propriedade somente clicando em Mover variável na janela Variáveis .
Uma variável é criada dentro do escopo de um pacote ou dentro do escopo de um contêiner, tarefa ou manipulador de eventos no pacote. Como o contêiner do pacote está no topo da hierarquia do contêiner, as variáveis com o escopo do pacote funcionam como variáveis globais e podem ser usadas por todos os contêineres no pacote. Da mesma forma, as variáveis definidas dentro do escopo de um contêiner, como um contêiner For Loop, podem ser usadas por todas as tarefas ou contêineres dentro do contêiner For Loop.
Se um pacote executar outros pacotes usando a tarefa Executar Pacote, as variáveis definidas no escopo do pacote de chamada ou da tarefa Executar Pacote poderão ser disponibilizadas para o pacote chamado usando o tipo de configuração Variável de Pacote Pai. Para obter mais informações, consulte Configurações de pacote.
IncludeInDebugDump
Indique se o valor da variável está incluído nos arquivos de despejo de depuração.
Para variáveis definidas pelo usuário e variáveis do sistema, o valor padrão para a opção IncludeInDebugDump é true.
No entanto, para variáveis definidas pelo usuário, o sistema redefine a opção IncludeInDebugDump como false quando as seguintes condições são atendidas:
Se a propriedade da variável EvaluateAsExpression estiver definida como true, o sistema redefinirá a opção IncludeInDebugDump como false.
Para incluir o texto da expressão como o valor da variável nos arquivos de despejo de depuração, defina a opção IncludeInDebugDump como true.
Se o tipo de dados da variável for alterado para uma cadeia de caracteres, o sistema redefinirá a opção IncludeInDebugDump como false.
Quando o sistema redefine a opção IncludeInDebugDump como false, isso pode substituir o valor selecionado pelo usuário.
Valor
O valor de uma variável definida pelo usuário pode ser um literal ou uma expressão. O valor de uma variável não pode ser nulo. As variáveis têm os seguintes valores padrão:
| Tipo de dados | Valor predefinido |
|---|---|
| Booleano | Falso |
| Tipos de dados numéricos e binários | 0 (zero) |
| Tipos de dados Char e string | (string vazia) |
| Objeto | System.Object |
Uma variável tem opções para definir o valor da variável e o tipo de dados do valor. As duas propriedades devem ser compatíveis: por exemplo, o uso de um valor de cadeia de caracteres junto com um tipo de dados inteiro não é válido.
Se a variável estiver configurada para avaliar como uma expressão, você deverá fornecer uma expressão. Em tempo de execução, a expressão é avaliada e a variável é definida como o resultado da avaliação. Por exemplo, se uma variável usa a expressão DATEPART("month", GETDATE()) , o valor da variável é o número equivalente do mês para a data atual. A expressão deve ser uma expressão válida que use a sintaxe gramatical da expressão SSIS. Quando uma expressão é usada com variáveis, a expressão pode usar literais e os operadores e funções que a gramática da expressão fornece, mas a expressão não pode fazer referência às colunas de um fluxo de dados no pacote. O comprimento máximo de uma expressão é de 4000 caracteres. Para obter mais informações, consulte Expressões dos Serviços de Integração (SSIS).
ValueType
Observação
O valor da propriedade aparece na coluna Tipo de dados na janela Variáveis .
Especifica o tipo de dados do valor da variável.
Cenários para o uso de variáveis
As variáveis são usadas de muitas maneiras diferentes nos pacotes do Integration Services. Você provavelmente descobrirá que o desenvolvimento de pacotes não progride muito antes de ter que adicionar uma variável definida pelo usuário ao seu pacote para implementar a flexibilidade e a capacidade de gerenciamento que sua solução exige. Dependendo do cenário, as variáveis do sistema também são comumente usadas.
Expressões de propriedade Use variáveis para fornecer valores nas expressões de propriedade que definem as propriedades de pacotes e objetos de pacote. Por exemplo, a expressão SELECT * FROM @varTableName inclui a variável varTableName, que atualiza a instrução SQL que uma tarefa Executar SQL realiza. A expressão, DATEPART("d", GETDATE()) == 1? @[User::varPackageFirst]:@[User::varPackageOther]", atualiza o pacote que a tarefa Executar Pacote executa, executando o pacote especificado na varPackageFirst variável no primeiro dia do mês e executando o pacote especificado na varPackageOther variável em outros dias. Para obter mais informações, consulte Uso de expressões de propriedade em pacotes.
Expressões de fluxo de dados Use variáveis para fornecer valores nas expressões que as transformações Coluna Derivada e Divisão Condicional usam para preencher colunas ou para direcionar linhas de dados para saídas de transformação diferentes. Por exemplo, a expressão @varSalutation + LastName, , concatena o valor na VarSalutation variável e na LastName coluna. A expressão, Income < @HighIncome, direciona linhas de dados nas quais o Income valor da coluna é menor que o valor na HighIncome variável para uma saída. Para obter mais informações, consulte Transformação de coluna derivada, Transformação de divisão condicional e Expressões do Integration Services (SSIS).
Expressões de restrição de precedência Forneça valores a serem usados em restrições de precedência para determinar se um executável restrito é executado. As expressões podem ser usadas em conjunto com um resultado de execução (sucesso, falha, conclusão) ou em vez de um resultado de execução. Por exemplo, se a expressão, @varMax > @varMin, for avaliada como true, o executável será executado. Para obter mais informações, consulte Adicionar expressões a restrições de precedência.
Parâmetros e códigos de retorno Forneça valores para parâmetros de entrada ou armazene os valores de parâmetros de saída e códigos de retorno. Para fazer isso, mapeie as variáveis para parâmetros e valores de retorno. Por exemplo, se você definir a variável varProductId como 23 e executar a instrução SQL, SELECT * from Production.Product WHERE ProductID = ?a consulta recuperará o produto com um ProductID de 23. Para obter mais informações, consulte Executar tarefa SQL e parâmetros e códigos de retorno na tarefa Executar SQL.
Para expressões de loop Forneça valores a serem usados nas expressões de inicialização, avaliação e atribuição do For Loop. Por exemplo, se a variável varCount é 2 e varMaxCount é 10, a expressão de inicialização é @varCount, a expressão de avaliação é @varCount < @varMaxCount, e a expressão de atribuição é @varCount =@varCount +1, então o loop se repete 8 vezes. Para obter mais informações, consulte For Loop Container.
Configurações de variáveis do pacote pai Passe valores de pacotes pai para pacotes filho. Os pacotes filho podem aceder às variáveis no pacote pai através de configurações de variáveis do pacote pai. Por exemplo, se o pacote filho deve usar a mesma data que o pacote pai, o pacote filho pode definir uma configuração de variável de pacote pai que especifica uma variável definida pela função GETDATE no pacote pai. Para obter mais informações, consulte Executar tarefa de pacote e configurações de pacote.
Tarefa de Script e Componente de Script Forneça uma lista de variáveis de apenas leitura e de leitura/gravação para a Tarefa de Script ou o Componente de Script, atualize as variáveis de leitura/gravação no script e use os valores atualizados no script ou fora dele. Por exemplo, no código, numberOfCars = CType(Dts.Variables("NumberOfCars").Value, Integer), a variável numberOfCars de script é atualizada pelo valor na variável, NumberOfCars. Para obter mais informações, consulte Usando variáveis na tarefa de script.
Adicionar uma variável
No SSDT (SQL Server Data Tools), abra o pacote do Integration Services com o qual você deseja trabalhar.
No Gerenciador de Soluções, clique duas vezes no pacote para abri-lo.
No Designer SSIS, para definir o escopo da variável, siga um destes procedimentos:
Para definir o escopo do pacote, clique em qualquer lugar na área de design da guia Fluxo de Controle.
Para definir o escopo como um manipulador de eventos, selecione um executável e um manipulador de eventos na superfície de design da guia Manipulador de Eventos .
Para definir o escopo para uma tarefa ou contêiner, na superfície de design da guia Fluxo de Controle ou da guia Manipulador de Eventos , clique em uma tarefa ou contêiner.
No menu SSIS , clique em Variáveis. Opcionalmente, você pode exibir a janela Variáveis mapeando o comando View.Variables para uma combinação de teclas de sua escolha na página Teclado da caixa de diálogo Opções .
Na janela Variáveis , clique no ícone Adicionar variável . A nova variável é adicionada à lista.
Opcionalmente, clique no ícone Opções de Grade, selecione colunas adicionais para mostrar na caixa de diálogo Opções de Grade de Variáveis e clique em OK.
Opcionalmente, defina as propriedades da variável. Para obter mais informações, consulte Definir as propriedades de uma variável User-Defined.
Para guardar o pacote atualizado, clique em Guardar itens selecionados no menu Ficheiro.
Caixa de diálogo Adicionar variável
Use a caixa de diálogo Adicionar variável para especificar as propriedades de uma nova variável.
Opções
Contentor
Selecione um contêiner na lista. O contêiner define o escopo da variável. O contêiner pode ser o pacote ou um executável no pacote.
Nome
Digite o nome da variável.
Espaço de nomes
Especifique o namespace da variável. Por padrão, as variáveis definidas pelo usuário estão no namespace User .
Tipo de valor
Selecione um tipo de dados.
Valor
Digite um valor. O valor deve ser compatível com o tipo de dados especificado na opção Tipo de valor .
somente leitura
Selecione esta opção para tornar a variável somente leitura.
Excluir uma variável
No SSDT (SQL Server Data Tools), abra o projeto Integration Services que contém o pacote desejado.
No Gerenciador de Soluções, clique com o botão direito do mouse no pacote para abri-lo.
No menu SSIS , clique em Variáveis. Opcionalmente, você pode exibir a janela Variáveis mapeando o comando View.Variables para uma combinação de teclas de sua escolha na página Teclado da caixa de diálogo Opções .
Selecione a variável a ser excluída e clique em Excluir variável.
Se não vir a variável na janela Variáveis, clique em Opções de Grelha e, em seguida, selecione Mostrar variáveis de todos os âmbitos.
Se a caixa de diálogo Confirmar exclusão de variáveis for aberta, clique em Sim para confirmar.
Para guardar o pacote atualizado, clique em Guardar itens selecionados no menu Ficheiro.
Alterar o escopo de uma variável
No SSDT (SQL Server Data Tools), abra o projeto Integration Services que contém o pacote desejado.
No Gerenciador de Soluções, clique com o botão direito do mouse no pacote para abri-lo.
No menu SSIS , clique em Variáveis. Opcionalmente, você pode exibir a janela Variáveis mapeando o comando View.Variables para uma combinação de teclas de sua escolha na página Teclado da caixa de diálogo Opções .
Selecione a variável e clique em Mover variável.
Se não vir a variável na janela Variáveis, clique em Opções de Grelha e, em seguida, selecione Mostrar variáveis de todos os âmbitos.
Na caixa de diálogo Selecionar Novo Escopo , selecione o pacote ou um contêiner, tarefa ou manipulador de eventos no pacote para alterar o escopo da variável.
Para guardar o pacote atualizado, clique em Guardar itens selecionados no menu Ficheiro.
Definir as propriedades de uma variável definida pelo usuário
Para definir as propriedades de uma variável definida pelo usuário no Integration Services, você pode usar um dos seguintes recursos:
Janela de variáveis.
Janela Propriedades. A janela Propriedades lista as propriedades para configurar variáveis que não estão disponíveis na janela Variáveis : Description, EvaluateAsExpression, Expression, ReadOnly, ValueType e IncludeInDebugDump.
Observação
O Integration Services também fornece um conjunto de variáveis do sistema cujas propriedades não podem ser atualizadas, com exceção da propriedade RaiseChangedEvent.
Definir expressões em variáveis
Quando você usa a janela Propriedades para definir expressões em uma variável definida pelo usuário:
O valor de uma variável pode ser definido pela propriedade Value ou Expression. Por padrão, a propriedade EvaluateAsExpression é definida como False e o valor da variável é definido pela propriedade Value. Para usar uma expressão para definir o valor, você deve primeiro definir EvaluateAsExpression como True e, em seguida, fornecer uma expressão na propriedade Expression. A propriedade Value é definida automaticamente como o resultado da avaliação da expressão.
A propriedade ValueType contém o tipo de dados do valor presente na propriedade Value. Quando Value é definido por uma expressão, ValueType é atualizado automaticamente para um tipo de dados que é compatível com o resultado da avaliação da expressão. Por exemplo, se Value contém 0 e a propriedade ValueType contém Int32 e, em seguida, você define Expression como GETDATE(), Value contém a data e hora atuais e ValueType é definido como DateTime.
A janela Propriedades da variável fornece acesso à caixa de diálogo Construtor de Expressões . Você pode usar essa ferramenta para criar, validar e avaliar expressões. Para obter mais informações, consulte Construtor de expressões e expressões do Integration Services (SSIS).
Quando você usa a janela Variáveis para definir expressões em uma variável definida pelo usuário:
Para usar uma expressão para definir o valor da variável, primeiro confirme se o tipo de dados da variável é compatível com o resultado da avaliação da expressão e, em seguida, forneça uma expressão na coluna Expressão da janela Variáveis . A propriedade EvaluateAsExpression na janela Properties é definida automaticamente como True.
Quando você atribui uma expressão a uma variável, um marcador de ícone especial é exibido ao lado da variável. Esse marcador de ícone especial também é exibido ao lado de gerenciadores de conexões e tarefas que têm expressões definidas neles.
A janela Variáveis da variável fornece acesso à caixa de diálogo Construtor de Expressões . Você pode usar essa ferramenta para criar, validar e avaliar expressões. Para obter mais informações, consulte Construtor de expressões e expressões do Integration Services (SSIS).
Na janela Variáveis e Propriedades , se você atribuir uma expressão à variável e EvaluateAsExpression estiver definido como True, não será possível alterar o tipo de dados da variável.
Definir as propriedades Namespace e Name
Os valores das propriedades Name e Namespace devem começar com uma letra de caractere alfabético, conforme definido pelo Unicode Standard 2.0, ou um sublinhado (_). Os caracteres subsequentes podem ser letras ou números, conforme definido no Unicode Standard 2.0, ou o sublinhado (_).
Definir propriedades de variáveis na janela Variáveis
No SSDT (SQL Server Data Tools), abra o projeto Integration Services que contém o pacote desejado.
No Gerenciador de Soluções, clique com o botão direito do mouse no pacote para abri-lo.
No menu SSIS , clique em Variáveis.
Opcionalmente, você pode exibir a janela Variáveis mapeando o comando View.Variables para uma combinação de teclas de sua escolha na página Teclado da caixa de diálogo Opções .
Opcionalmente, na janela Variáveis , clique em Opções de Grade e, em seguida, selecione as colunas a serem exibidas na janela Variáveis e selecione os filtros a serem aplicados à lista de variáveis.
Selecione a variável na lista e atualize os valores nas colunas Nome, Tipo de Dados, Valor, Namespace, Aumentar Evento de Alteração, Descrição e Expressão .
Selecione a variável na lista e clique em Mover Variável para alterar o escopo.
Para salvar o pacote atualizado, no menu Arquivo , clique em Salvar Itens Selecionados.
Definir propriedades da variável na janela Propriedades
No SSDT (SQL Server Data Tools), abra o projeto Integration Services que contém o pacote desejado.
No Gerenciador de Soluções, clique com o botão direito do mouse no pacote para abri-lo.
No menu Exibir, clique em janela de Propriedades.
No Designer SSIS, clique na guia Explorador de Pacotes e expanda o nó Pacote.
Para modificar variáveis com o escopo do pacote, expanda o nó Variáveis; caso contrário, expanda os nós Manipuladores de eventos ou Executáveis até localizar o nó Variáveis que contém a variável que você deseja modificar.
Clique na variável cujas propriedades você deseja modificar.
Na janela Propriedades , atualize as propriedades da variável de leitura/gravação. Algumas propriedades são de leitura ou somente leitura para variáveis definidas pelo utilizador.
Para obter mais informações sobre as propriedades, consulte Variáveis do Integration Services (SSIS).
Para salvar o pacote atualizado, no menu Arquivo , clique em Salvar Itens Selecionados.
Atualizar uma variável dinamicamente com configurações
Para atualizar dinamicamente as variáveis, você pode criar configurações para as variáveis, implantar as configurações com o pacote e, em seguida, atualizar os valores das variáveis no arquivo de configuração ao implantar os pacotes. Em tempo de execução, o pacote usa os valores de variáveis atualizados. Para obter mais informações, consulte Criar configurações de pacote.
Tarefas relacionadas
Usar os valores de variáveis e parâmetros num pacote filho
Mapear parâmetros de consulta para variáveis em um componente de fluxo de dados