Usare i token nei passaggi dei processi

Articolo
10/20/2023

Si applica a:SQL Server Istanza gestita di SQL di Azure

Importante

In Istanza gestita di SQL di Azure sono attualmente supportate la maggior parte delle funzionalità di SQL Server Agent, ma non tutte. Per informazioni dettagliate, vedere Differenze T-SQL tra Istanza gestita di SQL di Azure e SQL Server.

SQL Server Agent consente di usare token negli script dei passaggi di processo di Transact-SQL. L'utilizzo di token quando si scrivono passaggi di processo offre la stessa flessibilità assicurata dalle variabili quando si scrivono programmi software. Dopo aver inserito un token nello script di un passaggio di processo, SQL Server Agent sostituisce il token in fase di esecuzione, prima che il passaggio di processo venga eseguito dal sottosistema Transact-SQL.

Informazioni sull'utilizzo dei token

Importante

Qualsiasi utente di Windows con autorizzazioni di scrittura per il registro eventi di Windows può accedere ai passaggi di processo attivati dagli avvisi di SQL Server Agent o di WMI. Per evitare rischi per la sicurezza, i token di SQL Server Agent che possono essere usati in processi attivati dagli avvisi sono disabilitati per impostazione predefinita. I token interessati sono A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property). In questa versione l'utilizzo dei token è esteso a tutti gli avvisi.

Se è necessario usare questi token, verificare innanzitutto che solo i membri di gruppi di sicurezza di Windows attendibili, ad esempio il gruppo Administrators, dispongano delle autorizzazioni di scrittura per il registro eventi del computer in cui è installato SQL Server. A questo punto, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietàe nella pagina Sistema avvisi selezionare Sostituisci token per tutte le risposte del processo ad avvisi per abilitare questi token.

SQL Server Agent sostituirà i token con valori stringa letterali esatti, con un'operazione semplice ed efficiente. Tutti i token effettuano una distinzione tra maiuscole e minuscole. È necessario prendere in considerazione tale comportamento nei passaggi di processo e indicare correttamente i token da utilizzare oppure convertire la stringa di sostituzione nel tipo di dati corretto.

Ad esempio, è possibile utilizzare l'istruzione seguente per inserire il nome del database in un passaggio di processo:

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

In questo esempio la macro ESCAPE_SQUOTE viene inserita con il token A-DBN . In fase di esecuzione il token A-DBN viene sostituito con il nome del database appropriato. Tramite la macro di escape è possibile utilizzare caratteri di escape per eventuali virgolette singole inavvertitamente passate nella stringa di sostituzione del token. SQL Server Agent sostituisce una virgoletta singola con due virgolette singole nella stringa finale.

Se ad esempio la stringa passata per sostituire il token è AdventureWorks2022'SELECT @@VERSION --, il comando eseguito dal passaggio di processo di SQL Server Agent sarà il seguente:

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

In questo caso, l'istruzione inserita, SELECT @@VERSION, non viene eseguita. Al contrario, la virgoletta singola aggiuntiva indurrà il server ad analizzare l'istruzione inserita come stringa. Se la stringa di sostituzione del token non contiene una virgoletta singola, per nessun carattere verranno utilizzati caratteri di escape e il passaggio di processo contenente il token verrà eseguito come previsto.

Per eseguire il debug dell'utilizzo dei token nei passaggi di processo, utilizzare istruzioni PRINT come PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' e salvare l'output del passaggio di processo in un file o in una tabella. Usare la pagina Avanzate della finestra di dialogo Proprietà passaggio processo per specificare un file o una tabella per l'output del passaggio di processo.

Token e macro di SQL Server Agent

Nelle tabelle seguenti vengono elencati e illustrati i token e le macro supportati da SQL Server Agent.

Token di SQL Server Agent

Token	Descrizione
(A-DBN)	nome del database. Se il processo viene eseguito da un avviso, il valore del nome del database sostituisce automaticamente il token nel passaggio di processo.
(A-SVR)	Nome server. Se il processo viene eseguito da un avviso, il valore del nome del server sostituisce automaticamente il token nel passaggio di processo.
(A-ERR)	Numero di errore. Se il processo viene eseguito da un avviso, il valore del numero di errore sostituisce automaticamente il token nel passaggio di processo.
(A-SEV)	Gravità dell'errore. Se il processo viene eseguito da un avviso, il valore della gravità dell'errore sostituisce automaticamente il token nel passaggio di processo.
(A-MSG)	Testo del messaggio. Se il processo viene eseguito da un avviso, il valore del testo del messaggio sostituisce automaticamente il token nel passaggio di processo.
(JOBNAME)	Il nome del processo. Questo token è disponibile solo in SQL Server 2016 e versioni successive.
(STEPNAME)	Nome del passaggio. Questo token è disponibile solo in SQL Server 2016 e versioni successive.
(DATE)	Data corrente nel formato AAAAMMGG.
(INST)	Nome dell'istanza. Per un'istanza predefinita, questo token ha il nome dell'istanza predefinita: MSSQLSERVER.
(JOBID)	ID del processo.
(MACH)	Nome computer.
(MSSA)	Nome del servizio SQLServerAgent master.
(OSCMD)	Prefisso per il programma usato per l'esecuzione dei passaggi di processo CmdExec .
(SQLDIR)	Directory in cui è installato SQL Server. Per impostazione predefinita corrisponde a C:\Programmi\Microsoft SQL Server\MSSQL.
(SQLLOGDIR)	Token di sostituzione per il percorso della cartella del log degli errori di SQL Server, ad esempio $(ESCAPE_SQUOTE(SQLLOGDIR)). Questo token è disponibile solo in SQL Server 2014 e versioni successive.
(STEPCT)	Numero di esecuzioni del passaggio, escluse le esecuzioni non completate. Può essere utilizzato dal comando del passaggio per imporre l'interruzione di un ciclo a più passaggi.
(STEPID)	ID del passaggio.
(SRVR)	Nome del computer che esegue SQL Server. Se l'istanza di SQL Server è un'istanza denominata, questo token include il nome dell'istanza.
(TIME)	Ora corrente nel formato HHMMSS.
(STRTTM)	Ora nel formato HHMMSS in cui è stata avviata l'esecuzione del processo.
(STRTDT)	Data nel formato AAAAMMGG in cui è stata avviata l'esecuzione del processo.
(WMI(property))	Per i processi eseguiti in risposta ad avvisi WMI, indica il valore della proprietà specificata da property. Ad esempio, `$(WMI(DatabaseName))` specifica il valore della proprietà DatabaseName per l'evento WMI che ha provocato l'esecuzione dell'avviso.

Macro di escape di SQL Server Agent

Macro di escape	Descrizione
$(ESCAPE_SQUOTE(nome_token))	Utilizza caratteri di escape per virgolette singole (') nella stringa di sostituzione del token. Sostituisce una virgoletta singola con due virgolette singole.
$(ESCAPE_DQUOTE(nome_token))	Utilizza caratteri di escape per virgolette doppie (") nella stringa di sostituzione del token. Sostituisce una virgoletta doppia con due virgolette doppie.
$(ESCAPE_RBRACKET(nome_token))	Utilizza caratteri di escape per parentesi chiuse (]) nella stringa di sostituzione del token. Sostituisce una parentesi chiusa con due parentesi chiuse.
$(ESCAPE_NONE(nome_token))	Sostituisce il token senza utilizzare caratteri di escape per i caratteri della stringa. Questa macro viene utilizzata per assicurare la compatibilità con le versioni precedenti in ambienti in cui si presuppone che le stringhe di sostituzione dei token provengano esclusivamente da utenti trusted. Per ulteriori informazioni, vedere "Aggiornamento dei passaggi di processo per l'utilizzo di macro" più avanti in questo argomento.

Aggiornare i passaggi del processo per usare le macro

La tabella seguente descrive in che modo SQL Server Agent gestisce la sostituzione dei token. Per attivare o disattivare la sostituzione dei token relativi agli avvisi, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietàe selezionare o deselezionare la casella di controllo Sostituisci token per tutte le risposte del processo ad avvisi nella pagina Sistema avvisi .

Sintassi dei token	Sostituzione dei token relativi agli avvisi attivata	Sostituzione dei token relativi agli avvisi disattivata
La macro ESCAPE è stata utilizzata	Tutti i token presenti nei processi sono stati sostituiti correttamente.	I token attivati da avvisi non vengono sostituiti. I token interessati sono A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property). Altri token statici sono stati sostituiti correttamente.
La macro ESCAPE non è stata utilizzata	Tutti i processi contenenti token hanno esito negativo.	Tutti i processi contenenti token hanno esito negativo.

Esempi di aggiornamento della sintassi dei token

Di seguito sono riportati esempi di sintassi dei token per illustrare come usare questi comandi.

R. Utilizzo di token in stringhe non nidificate

Nell'esempio seguente viene illustrato come aggiornare uno script semplice non nidificato con la macro di escape appropriata. Prima di eseguire lo script di aggiornamento, lo script del passaggio di processo seguente utilizza un token per inserire il nome del database appropriato:

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

Dopo aver eseguito lo script di aggiornamento, una macro ESCAPE_NONE viene inserita prima del token A-DBN . Poiché le virgolette singole vengono utilizzate per delimitare la stringa di stampa, è necessario aggiornare il passaggio di processo inserendo la macro ESCAPE_SQUOTE nel modo seguente:

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

B. Utilizzo di token in stringhe nidificate

Negli script dei passaggi di processo in cui i token vengono utilizzati in istruzioni o stringhe nidificate, è necessario riscrivere le istruzioni nidificate come più istruzioni prima di inserire le macro di escape appropriate.

Si consideri, ad esempio, il passaggio di processo seguente che non è stato aggiornato con una macro di escape e nel quale viene utilizzato il token A-MSG:

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

Dopo aver eseguito lo script di aggiornamento, una macro ESCAPE_NONE viene inserita con il token. In questo caso, tuttavia, è necessario riscrivere lo script senza utilizzare la nidificazione nel modo seguente e inserire la macro ESCAPE_SQUOTE per utilizzare correttamente caratteri di escape per i delimitatori che potrebbero essere passati nella stringa di sostituzione del token:

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

Nota

In questo esempio la funzione QUOTENAME imposta il carattere utilizzato per le virgolette.

C. Utilizzo di token con la macro ESCAPE_NONE

L'esempio seguente fa parte di uno script in cui job_id viene recuperato dalla tabella sysjobs e in cui il token JOBID viene utilizzato per popolare la variabile @JobID dichiarata in precedenza nello script come tipo di dati binario.