Usar tokens em etapas de trabalho
Aplica-se a: 
SQL Server Instância Gerenciada de SQL do Azure
Importante
Atualmente, na Instância Gerenciada de SQL do Azure, a maioria dos recursos do SQL Server Agent é compatível, mas não todos. Confira Diferenças entre o T-SQL da Instância Gerenciada de SQL do Azure e o SQL Server para obter detalhes.
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
Importante
Qualquer usuário Windows com permissões de gravação no Log de Eventos do Windows pode acessar etapas de trabalho ativadas pelos alertas do SQL Server Agent ou alertas do WMI. Para evitar riscos de segurança, os tokens do SQL Server Agent que podem ser usados em trabalhos ativados por alertas encontram-se desabilitados por padrão. Eles são: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGe WMI(propriedade) . Nesta versão, o uso de tokens foi estendido a todos os alertas.
Se tiver que usar esses tokens, garanta, primeiro, que apenas membros dos grupos de segurança confiáveis do Windows, como o grupo Administradores, tenham permissões de gravação no Log de Eventos do computador em que reside o SQL Server . Depois, clique com o botão direito do mouse em SQL Server Agent no Pesquisador de Objetos, selecione Propriedadese, na página Sistema de Alerta , selecione Substituir tokens de todas as respostas de trabalho aos alertas para habilitar esses 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
| Token | Descrição |
|---|---|
| (A-DBN) | nome do banco de dados. Se o trabalho é executado por um alerta, o valor de nome de banco de dados substitui este token automaticamente na etapa de trabalho. |
| (A-SVR) | Nome de servidor. Se o trabalho é executado por um alerta, o valor de nome de servidor substitui este token automaticamente na etapa de trabalho. |
| (A-ERR) | Número de erro. Se o trabalho é executado por um alerta, o valor de número de erro substitui este token automaticamente na etapa de trabalho. |
| (A-SEV) | Severidade do erro. Se o trabalho é executado por um alerta, o valor de severidade do erro substitui este token automaticamente na etapa de trabalho. |
| (A-MSG) | Texto de mensagem. Se o trabalho é executado por um alerta, o valor de texto de mensagem substitui este token automaticamente na etapa de trabalho. |
| (JOBNAME) | O nome do trabalho. Esse token só está disponível no SQL Server 2016 e posterior. |
| (STEPNAME) | O nome da etapa. Esse token só está disponível no SQL Server 2016 e posterior. |
| (DATE) | Data atual (em formato AAAAMMDD). |
| (INST) | Nome da instância. Para uma instância padrão, este token tem o nome da instância padrão: MSSQLSERVER. |
| (JOBID) | ID do trabalho. |
| (MACH) | Nome do computador. |
| (MSSA) | Nome do serviço do SQLServerAgent mestre. |
| (OSCMD) | Prefixo do programa usado para executar etapas de trabalho do CmdExec . |
| (SQLDIR) | O diretório no qual o SQL Server está instalado. Por padrão, este valor é C:\Arquivos de Programas\Microsoft SQL Server\MSSQL. |
| (SQLLOGDIR) | Token de substituição para o caminho da pasta de log de erros do SQL Server – por exemplo, $(ESCAPE_SQUOTE(SQLLOGDIR)). Esse token só está disponível no SQL Server 2014 e posterior. |
| (STEPCT) | Contagem do número de vezes que a etapa foi executada (excluídas novas tentativas). Pode ser usado pelo comando de etapa para forçar terminação de um loop com várias etapas. |
| (STEPID) | ID da etapa. |
| (SRVR) | Nome do computador que executa o SQL Server. Se a instância do SQL Server for uma instância nomeada, incluirá o nome da instância. |
| (TIME) | Hora atual (em formato HHMMSS). |
| (STRTTM) | A hora (em formato HHMMSS) em que o trabalho começou a ser executado. |
| (STRTDT) | A data (em formato AAAAMMDD) em que o trabalho começou a ser executado. |
| (WMI (propriedade)) | Em trabalhos executados em resposta a alertas do WMI, o valor da propriedade especificado por propriedade. Por exemplo, $(WMI(DatabaseName)) fornece o valor da propriedade DatabaseName do evento WMI que provocou a execução do alerta. |
Macros de fuga do SQL Server Agent
| Macros de fuga | Descrição |
|---|---|
| $(ESCAPE_SQUOTE(token_name)) | Ignora aspas simples (') na cadeia de caracteres de substituição do token. Substitui um aspa simples por duas aspas simples. |
| $(ESCAPE_DQUOTE(token_name)) | Ignora aspas duplas (") na cadeia de caracteres de substituição do token. Substitui um aspa dupla por duas aspas duplas. |
| $(ESCAPE_RBRACKET(token_name)) | Ignora colchetes de fechamento (]) na cadeia de caracteres de substituição do token. Substitui um colchete de fechamento por dois colchetes de fechamento. |
| $(ESCAPE_NONE(token_name)) | Substitui o token sem ignorar nenhum caractere da cadeia. Esta macro é fornecida para dar suporte a compatibilidade retroativa em ambientes nos quais cadeias de caracteres de substituição de tokens são esperadas apenas de usuários confiáveis. Para obter mais informações, consulte "Atualizando etapas de trabalho para usar macros", mais adiante, neste tópico. |
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 .
| Sintaxe do token | Substituição do token de alerta ativada | Substituição do token de alerta desativada |
|---|---|---|
| Macro ESCAPE usada | Todos os tokens em trabalhos são substituídos com êxito. | Não são substituídos tokens ativados por alertas. São eles: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGe WMI(propriedade) . Outros tokens estáticos são substituídos com êxito. |
| Nenhuma macro ESCAPE usada | Todo trabalho contendo tokens falha. | Todo trabalho contendo tokens falha. |
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;
Observação
Neste exemplo, a função QUOTENAME define o caractere aspas.
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.
Observação
Como não são necessários delimitadores para tipos de dados binários, a macro ESCAPE_NONE é usada com o token JOBID. Você não precisaria atualizar esta etapa de trabalho após executar o script de atualização.
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.