Usar tokens em etapas de trabalho

Aplica-se a:SQL ServerInstância Gerenciada de SQL do Azure

O SQL Server Agent permite usar tokens em scripts de etapas de trabalho Transact-SQL. O uso de tokens para escrever suas etapas de trabalho oferece a mesma flexibilidade fornecida por variáveis ao escrever programas de software. Quando você insere um token em um script de etapa de trabalho, o SQL Server Agent o substitui em tempo de execução, antes de o trabalho ser executado pelo subsistema Transact-SQL.

Entender o uso de tokens

SQL Server A substituição de tokens do Agent é simples e eficiente: o SQL Server Agent substitui o token por um valor de cadeia de caracteres literal. Todos os tokens diferenciam maiúsculas de minúsculas. Suas etapas de trabalho devem levar isto em conta e usar aspas corretamente nos tokens utilizados ou converter a cadeia de caracteres de substituição pelo tipo de dados correto.

Por exemplo, você pode usar a seguinte instrução para imprimir o nome do banco de dados em uma etapa de trabalho:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

Neste exemplo, a macro ESCAPE_SQUOTE é inserida com o token A-DBN . Em tempo de execução, o token A-DBN é substituído pelo nome de banco de dados apropriado. A macro de fuga ignora eventuais aspas simples que possam ser transmitidas inadvertidamente na cadeia de caracteres de substituição do token. O SQL Server Agent substitui uma aspa simples por duas aspas simples na cadeia de caracteres final.

Por exemplo, se a cadeia de caracteres transmitida para substituição do token for AdventureWorks2022'SELECT @@VERSION --, o comando executado pela etapa de trabalho do SQL Server Agent será:

PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;

Neste caso, a instrução inserida SELECT @@VERSION não é executada. Em vez disso, a aspa simples adicional faz com que o servidor analise a instrução inserida como uma cadeia de caracteres. Se a cadeia de caracteres de substituição do token não contiver uma aspa simples, nenhum caractere será ignorado e a etapa de trabalho que contém o token será executada conforme se pretende.

Para depurar o uso de tokens em suas etapas de trabalho, use instruções de impressão, como PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' , e salve a saída das etapas de trabalho em um arquivo ou tabela. Use a página Avançado da caixa de diálogo Propriedades da Etapa de Trabalho para especificar um arquivo ou tabela de saída da etapa de trabalho.

Tokens e macros do SQL Server Agent

As tabelas a seguir listam e descrevem os tokens e macros para os quais há suporte no SQL Server Agent.

Tokens do SQL Server Agent

Macros de fuga do SQL Server Agent

Atualizar etapas de trabalho para usar macros

A tabela a seguir descreve como a substituição de tokens é manipulada pelo SQL Server Agent. Para ativar ou desativar a substituição do token de alerta, clique com o botão direito do mouse em SQL Server Agent no Pesquisador de Objetos, selecione Propriedadese, na página Sistema de Alerta , marque ou desmarque a caixa de seleção Substituir tokens de todas as respostas de trabalho aos alertas .

Exemplos de atualização de sintaxe de token

Abaixo estão exemplos de sintaxe de token para ajudar a ilustrar como usar esses comandos.

R. Usar tokens em cadeias de caracteres não aninhadas

O exemplo a seguir mostra como atualizar um script não aninhado simples com a macro de fuga apropriada. Antes de executar o script de atualização, o seguinte script de etapa de trabalho usa um token para imprimir o nome do banco de dados apropriado:

PRINT N'Current database name is $(A-DBN)' ;

Executado o script de atualização, uma macro ESCAPE_NONE é inserida antes do token A-DBN . Como são usadas aspas simples para delimitar a cadeia de caracteres de impressão, é necessário atualizar a etapa de trabalho, inserindo a macro ESCAPE_SQUOTE da seguinte maneira:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

B. Usar tokens em cadeias de caracteres aninhadas

Em scripts de etapa de trabalho em que são usados tokens em cadeias de caracteres ou instruções aninhadas, estas devem ser rescritas como várias instruções para que possam ser inseridas as macros de fuga apropriadas.

Por exemplo, considere a seguinte etapa de trabalho, que usa o token A-MSG e não foi atualizada com uma macro de fuga:

PRINT N'Print ''$(A-MSG)''' ;

Executado o script de atualização, uma macro ESCAPE_NONE é inserida com o token. Contudo, neste caso, você teria que rescrever o script sem usar aninhamento, como segue, e inserir a macro ESCAPE_SQUOTE para ignorar adequadamente delimitadores que pudessem ser transmitidos na cadeia de caracteres de substituição do token:

DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;

C. Usar tokens com a macro ESCAPE_NONE

O exemplo a seguir é parte de um script que recupera o job_id da tabela sysjobs e usa o token JOBID para popular a variável @JobID, declarada anteriormente no script como tipo de dados binário.

DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))

Isso atribui diretamente o valor do token JOBID a @JobID, eliminando consultas desnecessárias ao banco de dados e conversões implícitas, abordando as preocupações levantadas na seção C.

Confira também

• Implementar trabalhos
• Gerenciar etapas de trabalho