Usar tokens em etapas de trabalho
Aplica-se a:
SQL ServerAzure SQL Managed Instance
Importante
Em Instância Gerenciada do SQL do Azure, a maioria dos recursos do SQL Server Agent, mas não todos, são suportados no momento. Consulte as diferenças de T-SQL entre a Instância Gerida do SQL do Azure e o SQL Server para obter detalhes.
O SQL Server Agent permite que possa usar tokens nos scripts de passos de trabalho do Transact-SQL. O uso de tokens quando você escreve suas etapas de trabalho oferece a mesma flexibilidade que as variáveis fornecem quando você escreve programas de software. Depois de inserir um token em um script de etapa de trabalho, o SQL Server Agent substitui o token em tempo de execução, antes que a etapa de trabalho seja executada pelo subsistema Transact-SQL.
Entenda o uso de tokens
Importante
Qualquer usuário do Windows com permissões de gravação no Log de Eventos do Windows pode acessar etapas de trabalho ativadas por alertas do SQL Server Agent ou alertas WMI. Para evitar esse risco de segurança, os tokens do SQL Server Agent que podem ser usados em trabalhos ativados por alertas são desabilitados por padrão. Esses tokens são: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGe WMI(propriedade). Nesta versão, o uso de tokens é estendido a todos os alertas.
Se você precisar usar esses tokens, primeiro verifique se apenas os membros de grupos de segurança confiáveis do Windows, como o grupo Administradores, têm permissões de gravação no Log de Eventos do computador onde o SQL Server reside. Em seguida, clique com o botão direito do rato em SQL Server Agent no Pesquisador de Objetos, selecione Propriedadese, na página Sistema de Alerta, selecione Substituir tokens para todas as respostas de trabalhos a alertas para habilitar estes tokens.
A substituição de token do SQL Server Agent é simples e eficiente: o SQL Server Agent substitui um valor de cadeia de caracteres literal exato para o token. Todos os tokens diferenciam maiúsculas de minúsculas. Suas etapas de trabalho devem levar isso em conta e citar corretamente os tokens que você usa ou converter a cadeia de caracteres de substituição para o 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 apropriado do banco de dados. A macro de escape escapa de quaisquer aspas simples que possam ser passadas inadvertidamente na cadeia de caracteres de substituição de 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 passada para substituir o 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, as aspas simples extras fazem 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 única aspas, nenhum caractere será escapado e a etapa de trabalho que contém o token será executada conforme pretendido.
Para depurar o uso do token em suas etapas de trabalho, use instruções de impressão como PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' e salve a saída da etapa 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 suportados pelo SQL Server Agent.
SQL Server Agent Identificadores
| Símbolo | Descrição |
|---|---|
| (A-DBN) | Nome do banco de dados. Se o trabalho for executado por um alerta, o valor do nome do banco de dados substituirá automaticamente esse token na etapa do trabalho. |
| (A-SVR) | Nome do servidor. Se o trabalho for executado através de um alerta, o valor do nome do servidor substituirá automaticamente esse token no passo do trabalho. |
| (A-ERR) | Número do erro. Se o trabalho for executado por um alerta, o valor do número de erro substituirá automaticamente esse token na etapa do trabalho. |
| (A-SEV) | Gravidade do erro. Se o trabalho for executado por um alerta, o valor de gravidade do erro substituirá automaticamente esse token na etapa do trabalho. |
| (A-MSG) | Texto da mensagem. Se o trabalho for executado por um alerta, o valor de texto da mensagem substituirá automaticamente esse token na etapa do trabalho. |
| (JOBNAME) | O nome do trabalho. Esse token só está disponível no SQL Server 2016 e superior. |
| (STEPNAME) | O nome da etapa. Esse token só está disponível no SQL Server 2016 e superior. |
| (DATA) | Data atual (no formato AAAAMMDD). |
| (INST) | Nome da instância. Para uma instância padrão, esse token tem o nome de instância padrão: MSSQLSERVER. |
| (JOBID) | ID do trabalho. |
| (MACH) | Nome do computador. |
| (MSSA) | Domine o serviço denominado SQLServerAgent. |
| (OSCMD) | Prefixo para o programa usado para executar CmdExec etapas de trabalho. |
| (SQLDIR) | O diretório no qual o SQL Server está instalado. Por padrão, esse valor é C:\Arquivos de Programas\Microsoft SQL Server\MSSQL. |
| (SQLLOGDIR) | Token de substituição para o caminho da pasta de logs de erro do SQL Server - por exemplo, $(ESCAPE_SQUOTE(SQLLOGDIR)). Esse token só está disponível no SQL Server 2014 e superior. |
| (STEPCT) | Uma contagem do número de vezes que esta etapa foi executada (excluindo tentativas). Pode ser usado pelo comando step para forçar a terminação de um loop de várias etapas. |
| (STEPID) | ID do passo. |
| (SRVR) | Nome do computador que executa o SQL Server. Se a instância do SQL Server for uma instância nomeada, isso incluirá o nome da instância. |
| (TEMPO) | Hora atual (em formato HHMMSS). |
| (STRTTM) | A hora (no formato HHMMSS) em que o trabalho começou a ser executado. |
| (STRTDT) | A data (no formato AAAAMMDD) em que o trabalho começou a ser executado. |
| (WMI(propriedade)) | Para trabalhos que são executados em resposta a alertas WMI, o valor da propriedade especificado pela propriedade . Por exemplo, $(WMI(DatabaseName)) fornece o valor da propriedade DatabaseName para o evento WMI que causou a execução do alerta. |
Macros de Escape do Agente SQL Server
| Macros de fuga | Descrição |
|---|---|
| $(ESCAPE_SQUOTE(token_name)) | Escapa de aspas simples (') na cadeia de caracteres de substituição de token. Substitui uma aspa simples por duas aspas simples. |
| $(ESCAPE_DQUOTE(token_name)) | Escapa aspas duplas (") na string de substituição de token. Substitui uma aspa dupla por duas aspas duplas. |
| $(ESCAPE_RBRACKET(token_name)) | Escapa dos colchetes direitos (]) na cadeia de caracteres de substituição de token. Substitui um parêntese direito por dois parênteses direitos. |
| $(ESCAPE_NONE(token_name)) | Substitui o token sem escapar de nenhum caractere na cadeia de caracteres. Esta macro é fornecida para oferecer suporte à compatibilidade retroativa em ambientes onde as cadeias 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 tarefas para usar macros
A tabela a seguir descreve como a substituição de token é tratada pelo SQL Server Agent. Para ativar ou desativar a substituição de tokens de alerta, clique com o botão direito SQL Server Agent no Explorador de Objetos, selecione Propriedadese, na página Sistema de Alerta, marque ou desmarque a caixa de seleção Substituir tokens para respostas a alertas de todos os trabalhos.
| Sintaxe do token | Substituição do token de alerta em | Substituição do token de alerta desativada |
|---|---|---|
| Macro ESCAPE usada | Todos os tokens em trabalhos são substituídos com sucesso. | Os tokens ativados por alertas não são substituídos. Esses tokens são 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 | Todos os trabalhos que contêm tokens falham. | Todos os trabalhos que contêm tokens falham. |
Exemplos de atualização de sintaxe de token
Abaixo estão exemplos de sintaxe de token para ajudar a ilustrar como usar esses comandos.
Um. Usar tokens em cadeias de caracteres não aninhadas
O exemplo a seguir mostra como atualizar um script simples não aninhado com a macro de escape apropriada. Antes de executar o script de atualização, o seguinte script de tarefa usa um token de tarefa para exibir o nome de banco de dados apropriado.
PRINT N'Current database name is $(A-DBN)' ;
Depois de executar o script de atualização, uma macro ESCAPE_NONE é inserida antes do token A-DBN. Como aspas simples são usadas para delimitar a cadeia de caracteres de impressão, você deve 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 os tokens são usados em cadeias de caracteres ou instruções aninhadas, as instruções aninhadas devem ser reescritas como várias instruções antes de inserir as macros de escape apropriadas.
Por exemplo, considere a seguinte etapa de trabalho, que usa o token A-MSG e não foi atualizada com uma macro de escape:
PRINT N'Print ''$(A-MSG)''' ;
Depois de executar o script de atualização, uma macro ESCAPE_NONE é inserida com o token. No entanto, neste caso, deverás reescrever o script sem usar aninhamento, como se segue, e inserir a macro ESCAPE_SQUOTE para escapar corretamente dos delimitadores que podem ser passados na string 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 de 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 preencher a variável @JobID, que foi declarada anteriormente no script como um tipo de dados binário.
Observação
Como nenhum delimitador é necessário para tipos de dados binários, a macro ESCAPE_NONE é usada com o token JOBID. Você não precisaria atualizar essa etapa de trabalho depois de executar o script de atualização.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
Isso atribui diretamente o valor do token JOBID ao @JobID, eliminando consultas desnecessárias ao banco de dados e conversões implícitas, abordando as preocupações levantadas na seção C.