ジョブ ステップでのトークンの使用

適用対象:SQL ServerAzure SQL Managed Instance

SQL Server エージェントを使用すると、Transact-SQL ジョブ ステップ スクリプトでトークンを使用できます。 ジョブ ステップを記述するときにトークンを使用すると、ソフトウェア プログラムを記述するときの変数と同じような柔軟性が得られます。 ジョブ ステップ スクリプトにトークンを挿入した後、Transact-SQL サブシステムでジョブ ステップが実行される前に、SQL Server エージェントにより実行時にトークンが置き換えられます。

トークンの使用について

SQL Server エージェントのトークンの置換は簡単で効率的です。 SQL Server エージェントにより、トークンのリテラル文字列値にそのまま置き換えられます。 すべてのトークンには大文字と小文字の区別があります。 ジョブ ステップでは、この点を考慮し、使用するトークンを正しく引用したり、置換後の文字列を正しいデータ型に変換したりする必要があります。

たとえば、ジョブ ステップでデータベースの名前を表示するときに、次のステートメントを使用する場合があります。

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

この例では、 ESCAPE_SQUOTE マクロは A-DBN トークンと共に挿入されます。 実行時に、 A-DBN トークンは適切なデータベース名に置き換えられます。 エスケープ マクロにより、トークンの置換後の文字列に誤って渡される可能性がある単一引用符がエスケープされます。 SQL Server エージェントにより、最後の文字列にある 1 つの単一引用符が 2 つの連続する単一引用符に置き換えられます。

たとえば、トークンを置き換えるために渡される文字列が AdventureWorks2022'SELECT @@VERSION --の場合、 SQL Server エージェントのジョブ ステップで実行されるコマンドは次のようになります。

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

この場合、挿入されたステートメント SELECT @@VERSIONは実行されません。 代わりに、追加の単一引用符によって、サーバーは挿入されたステートメントを文字列として解析します。 トークンの置換後の文字列に単一引用符が含まれていない場合は、エスケープされる文字はなく、トークンを含むジョブ ステップが意図したとおりに実行されます。

ジョブ ステップでのトークンの使用をデバッグするには、 PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' のような PRINT ステートメントを使用して、ジョブ ステップの出力をファイルまたはテーブルに保存します。 [ジョブ ステップのプロパティ] ダイアログ ボックスの [詳細設定] ページを使用して、ジョブ ステップの出力ファイルまたはテーブルを指定します。

SQL Server エージェントのトークンとマクロ

次の表では、 SQL Server エージェントでサポートされているトークンとマクロについて説明します。

SQL Server エージェントのトークン

SQL Server エージェントのエスケープ マクロ

マクロを使用するようにジョブ ステップを更新する

次の表では、 SQL Server エージェントでトークンの置換がどのように処理されるのかを説明します。 警告トークンの置換の有効と無効を切り替えるには、オブジェクト エクスプローラーで [SQL Server エージェント] を右クリックし、 [プロパティ]を選択します。次に、 [警告システム] ページの [警告に応答するすべてのジョブのトークンを置き換える] チェック ボックスをオンまたはオフにします。

トークンの構文の更新例

これらのコマンドの使用方法を示すトークン構文の例を次に示します。

A. 入れ子になっていない文字列でトークンを使用する

次の例では、適切なエスケープ マクロを使用して入れ子になっていない単純なスクリプトを更新する方法を示します。 更新スクリプトを実行する前に、次のジョブ ステップ スクリプトで、ジョブ ステップ トークンを使用して適切なデータベース名を表示します。

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

更新スクリプトを実行すると、 ESCAPE_NONE マクロが A-DBN トークンの前に挿入されます。 表示する文字列を区切るために単一引用符が使用されているため、次のように、 ESCAPE_SQUOTE マクロを挿入してジョブ ステップを更新する必要があります。

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

B. 入れ子になっている文字列でトークンを使用する

トークンが入れ子になっている文字列やステートメントで使用されているジョブ ステップ スクリプトでは、入れ子になっているステートメントを複数のステートメントに書き直してから、適切なエスケープ マクロを挿入する必要があります。

たとえば、次のジョブ ステップを考えてみましょう。A-MSG トークンを使用するこのジョブ ステップは、エスケープ マクロで更新されていません。

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

更新スクリプトを実行すると、 ESCAPE_NONE マクロがトークンと共に挿入されます。 ただし、この場合、次のように入れ子を使用しないスクリプトに書き直して ESCAPE_SQUOTE マクロを挿入し、トークンの置換後の文字列に渡される可能性がある区切り文字を正しくエスケープすることが必要な場合があります。

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

C: ESCAPE_NONE マクロと共にトークンを使用する

次の例は、あるスクリプトの一部です。ここでは、sysjobs テーブルから job_id を取得し、スクリプト内で既にバイナリ データ型として宣言された @JobID 変数を設定するために JOBID トークンを使用しています。

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

これにより、@JobID に JOBID トークンの値が直接割り当てられ、不要なデータベース クエリや暗黙的な変換が排除され、セクション C で発生する問題に対処できます。

関連項目

• ジョブの実装
• ジョブ ステップの管理