Usare i token nei passaggi delle operazioni

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

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

Informazioni sull'uso dei token

Qualsiasi utente di Windows con autorizzazioni di scrittura nel registro eventi di Windows può accedere ai passaggi del processo attivati dagli avvisi di SQL Server Agent o dagli avvisi WMI. Per evitare questo rischio di sicurezza, i token di SQL Server Agent che possono essere usati nei processi attivati dagli avvisi sono disabilitati per impostazione predefinita. Questi token sono: A-DBN, A-SVR, A-ERRA-SEV, , A-MSGe WMI(<property>). In questa versione, l'uso dei token viene esteso a tutti gli avvisi.

La sostituzione dei token di SQL Server Agent è semplice ed efficiente: SQL Server Agent sostituisce un valore letterale esatto per il token. Tutti i token fanno distinzione tra maiuscole e minuscole. I passaggi del processo devono tenere conto di questa operazione e indicare correttamente i token usati o convertire la stringa di sostituzione nel tipo di dati corretto.

Ad esempio, è possibile usare l'istruzione seguente per stampare il nome del database in un passaggio del processo:

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

In questo esempio la ESCAPE_SQUOTE macro viene inserita con il A-DBN token. In fase di esecuzione, il A-DBN token viene sostituito con il nome del database appropriato. La macro di escape effettua l'escape delle virgolette singole che potrebbero essere passate inavvertitamente nella stringa sostitutiva del token. SQL Server Agent sostituisce una virgoletta singola con due virgolette singole nella stringa finale.

Ad esempio, se la stringa passata per sostituire il token è AdventureWorks2022'SELECT @@VERSION --, il comando eseguito dal passaggio del processo di SQL Server Agent è:

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

In questo caso, l'istruzione inserted, SELECT @@VERSION, non viene eseguita. La virgoletta singola aggiuntiva fa invece in modo che il server analizzi l'istruzione inserita come stringa. Se la stringa di sostituzione del token non contiene una virgoletta singola, non viene applicato alcun carattere di escape e la fase del processo contenente il token viene eseguita come previsto.

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

Token e macro di SQL Server Agent

Le tabelle seguenti elencano e descrivono i token e le macro supportati da SQL Server Agent.

Token di SQL Server Agent

Macro di escape per SQL Server Agent

Aggiornare i passaggi del lavoro per usare le macro

Nella tabella seguente viene descritto il modo in cui la sostituzione dei token viene gestita da SQL Server Agent. Per attivare o disattivare la sostituzione dei token di avviso, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, selezionare Proprietà e nella pagina Sistema avvisi selezionare o deselezionare la casella di controllo Sostituisci token per tutte le risposte di processo agli avvisi .

Esempi di aggiornamento della sintassi dei token

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

Un. Usare i token in stringhe non annidate

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

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

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

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

B. Usare i token nelle stringhe annidate

Negli script dei passaggi di lavoro in cui i token vengono usati in stringhe o istruzioni annidate, le istruzioni nidificate devono essere riscritte in più istruzioni distinte prima di inserire le macro di escape appropriate.

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

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

Dopo aver eseguito lo script di aggiornamento, viene inserita una ESCAPE_NONE macro con il token. In questo caso, tuttavia, è necessario riscrivere lo script senza usare l'annidamento come indicato di seguito e inserire la macro ESCAPE_SQUOTE per gestire correttamente i delimitatori che potrebbero essere passati nella stringa di sostituzione del token.

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

In questo esempio la QUOTENAME funzione imposta il carattere di virgolette.

C. Usare i token con la macro ESCAPE_NONE

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

DECLARE @JobID UNIQUEIDENTIFIER;
SET @JobID = $(ESCAPE_NONE(JOBID));

Questo assegna direttamente il valore dal JOBID token a @JobID, eliminando le query di database non necessarie e le conversioni implicite, risolvendo i problemi generati nella sezione C.

Contenuti correlati

• Implementare lavori
• Gestire le fasi del lavoro