작업 단계에서 토큰 사용
적용 대상: 
SQL Server Azure SQL Managed Instance
Important
현재 Azure SQL Managed Instance에서는 SQL Server 에이전트 기능이 대부분 지원됩니다. 자세한 내용은 SQL Server와 Azure SQL Managed Instance 간의 T-SQL 차이점을 참조하세요.
SQL Server 에이전트를 사용하면 Transact-SQL 작업 단계 스크립트에 토큰을 사용할 수 있습니다. 작업 단계를 작성할 때 토큰을 사용하면 소프트웨어 프로그램을 작성할 때 변수가 제공하는 것과 동일한 유연성을 얻을 수 있습니다. 작업 단계 스크립트에 토큰을 삽입하면 SQL Server 하위 시스템에서 해당 작업 단계를 실행하기 전에 Transact-SQL 에이전트가 런타임 시 토큰을 바꿉니다.
토큰 사용 이해
Important
Windows 이벤트 로그에 대한 쓰기 권한이 있는 모든 Windows 사용자는 SQL Server 에이전트 경고 또는 WMI 경고에 의해 활성화되는 작업 단계에 액세스할 수 있습니다. 이 보안 위험을 방지하기 위해, 경고에 의해 활성화된 작업에 사용할 수 있는 SQL Server 에이전트 토큰은 기본적으로 사용하지 않도록 설정됩니다. 이러한 토큰은 A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, WMI(property)입니다. 이 릴리스에서는 토큰 사용이 모든 경고로 확장됩니다.
이러한 토큰을 사용해야 하는 경우 먼저 Administrators 그룹과 같은 트러스트된 Windows 보안 그룹의 멤버만 SQL Server가 설치된 컴퓨터의 이벤트 로그에 대한 쓰기 권한이 있는지 확인합니다. 그런 다음 개체 탐색기에서 SQL Server 에이전트를 마우스 오른쪽 단추로 클릭하고 속성을 선택한 다음 경고 시스템 페이지에서 경고에 대한 모든 작업 응답에 대한 토큰 바꾸기를 선택하여 이러한 토큰을 사용하도록 설정합니다.
SQL Server 에이전트에서는 토큰이 간단하고 효율적으로 바뀝니다. SQL Server 에이전트에서 토큰을 해당하는 리터럴 문자열 값으로 바꿉니다. 모든 토큰은 대/소문자를 구분합니다. 작업 단계에서는 이를 고려하여 사용하는 토큰을 올바르게 인용하거나 대체 문자열을 올바른 데이터 형식으로 변환해야 합니다.
예를 들어 다음 문을 사용하여 작업 단계에서 데이터베이스의 이름을 인쇄할 수 있습니다.
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
이 예에서 ESCAPE_SQUOTE 매크로는 A-DBN 토큰과 함께 삽입됩니다. 런타임 시 A-DBN 토큰은 적절한 데이터베이스 이름으로 바뀝니다. 이스케이프 매크로는 토큰 대체 문자열에 실수로 전달될 수 있는 작은따옴표를 이스케이프합니다. SQL Server 에이전트는 마지막 문자열에서 작은따옴표 하나를 작은따옴표 두 개로 바꿉니다.
예를 들어 토큰을 바꾸기 위해 전달된 문자열이 AdventureWorks2022'SELECT @@VERSION --인 경우 SQL Server 에이전트 작업 단계에서 실행되는 명령은 다음과 같습니다.
PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;
이 경우 삽입된 문(SELECT @@VERSION)은 실행되지 않습니다. 대신 추가 작은따옴표로 인해 서버는 삽입된 문을 문자열로 구문 분석합니다. 토큰 대체 문자열에 작은따옴표가 포함되어 있지 않으면 문자가 이스케이프되지 않고 토큰을 포함하는 작업 단계가 의도한 대로 실행됩니다.
작업 단계에서 토큰 사용량을 디버그하려면 PRINT N'$(ESCAPE_SQUOTE(SQLDIR))'와(과) 같은 인쇄 문을 사용하고 작업 단계 출력을 파일 또는 테이블에 저장합니다. 작업 단계 속성 대화 상자의 고급 페이지에서 작업 단계 출력 파일이나 테이블을 지정할 수 있습니다.
SQL Server 에이전트 토큰 및 매크로
다음 표에서는 SQL Server 에이전트 지원하는 토큰 및 매크로를 나열하고 설명합니다.
SQL Server 에이전트 토큰
| 토큰 | 설명 |
|---|---|
| (A-DBN) | 데이터베이스 이름입니다. 작업이 경고에 의해 실행되는 경우 데이터베이스 이름 값이 작업 단계에서 이 토큰을 자동으로 대체합니다. |
| (A-SVR) | 서버 이름입니다. 작업이 경고에 의해 실행되는 경우 서버 이름 값이 작업 단계에서 이 토큰을 자동으로 대체합니다. |
| (A-ERR) | 오류 번호입니다. 작업이 경고에 의해 실행되는 경우 오류 번호 값이 작업 단계에서 이 토큰을 자동으로 대체합니다. |
| (A-SEV) | 오류 심각도입니다. 작업이 경고에 의해 실행되는 경우 오류 심각도 값이 작업 단계에서 이 토큰을 자동으로 대체합니다. |
| (A-MSG) | 메시지 텍스트입니다. 작업이 경고에 의해 실행되는 경우 메시지 텍스트 값이 작업 단계에서 이 토큰을 자동으로 대체합니다. |
| (JOBNAME) | 작업의 이름입니다. 이 토큰은 SQL Server 2016 이상에서만 사용할 수 있습니다. |
| (STEPNAME) | 단계의 이름입니다. 이 토큰은 SQL Server 2016 이상에서만 사용할 수 있습니다. |
| (DATE) | 현재 날짜(YYYYMMDD 형식)입니다. |
| (INST) | 인스턴스 이름입니다. 기본 인스턴스의 경우 이 토큰의 기본 인스턴스 이름은 MSSQLSERVER입니다. |
| (JOBID) | 작업 ID입니다. |
| (MACH) | 컴퓨터 이름입니다. |
| (MSSA) | 마스터 SQLServerAgent 서비스 이름입니다. |
| (OSCMD) | CmdExec 작업 단계를 실행하는 데 사용되는 프로그램의 접두사입니다. |
| (SQLDIR) | SQL Server가 설치된 디렉터리입니다. 기본적으로 C:\Program Files\Microsoft SQL Server\MSSQL에 설치됩니다. |
| (SQLLOGDIR) | SQL Server 오류 로그 폴더 경로에 대한 대체 토큰입니다(예: $(ESCAPE_SQUOTE(SQLLOGDIR)). 이 토큰은 SQL Server 2014 이상에서만 사용할 수 있습니다. |
| (STEPCT) | 이 단계가 실행된 횟수입니다(재시도 제외). 단계 명령에서 다중 단계 루프를 강제로 종료하는 데 사용할 수 있습니다. |
| (STEPID) | 단계 ID입니다. |
| (SRVR) | SQL Server를 실행 중인 서버 컴퓨터의 이름입니다. SQL Server 인스턴스가 명명된 인스턴스인 경우 여기에는 인스턴스 이름이 포함됩니다. |
| (TIME) | 현재 시간(HHMMSS 형식)입니다. |
| (STRTTM) | 작업이 실행되기 시작한 시간(HHMMSS 형식)입니다. |
| (STRTDT) | 작업이 실행되기 시작한 날짜(YYYYMMDD 형식)입니다. |
| (WMI(property)) | WMI 경고에 대한 응답으로 실행되는 작업의 경우 속성으로 지정된 속성의 값입니다. 예를 들어 $(WMI(DatabaseName))은(는) 경고를 발생시킨 WMI 이벤트에 대한 DatabaseName 속성 값을 제공합니다. |
SQL Server 에이전트 이스케이프 매크로
| 이스케이프 매크로 | 설명 |
|---|---|
| $(ESCAPE_SQUOTE(token_name)) | 토큰 대체 문자열에서 작은따옴표(')를 이스케이프합니다. 작은따옴표 하나를 작은따옴표 두 개로 바꿉니다. |
| $(ESCAPE_DQUOTE(token_name)) | 토큰 대체 문자열에서 큰따옴표(")를 이스케이프합니다. 작은따옴표 하나를 큰따옴표 두 개로 바꿉니다. |
| $(ESCAPE_RBRACKET(token_name)) | 토큰 대체 문자열에서 오른쪽 대괄호(])를 이스케이프합니다. 오른쪽 대괄호 하나를 오른쪽 대괄호 두 개로 바꿉니다. |
| $(ESCAPE_NONE(token_name)) | 문자열의 문자를 이스케이프하지 않고 토큰을 대체합니다. 이 매크로는 신뢰할 수 있는 사용자에게만 토큰 대체 문자열이 필요한 환경에서 이전 버전과의 호환성을 지원하기 위해 제공됩니다. 자세한 내용은 이 항목의 뒷부분에 있는 "매크로를 사용하도록 작업 단계 업데이트"를 참조하세요. |
매크로를 사용하도록 작업 단계 업데이트
다음 표에서는 SQL Server 에이전트에서 토큰 바꾸기를 처리하는 방법에 대해 설명합니다. 경고 토큰 교체를 켜거나 끄려면 개체 탐색기에서 SQL Server 에이전트를 마우스 오른쪽 단추로 클릭하고 속성을 선택한 다음 경고 시스템 페이지에서 경고에 대한 모든 작업 응답에 대한 토큰 바꾸기를 선택하거나 선택 취소합니다.
| 토큰 구문 | 경고 토큰 교체 켜짐 | 경고 토큰 교체 꺼짐 |
|---|---|---|
| ESCAPE 매크로 사용됨 | 작업의 모든 토큰이 성공적으로 대체되었습니다. | 경고로 활성화된 토큰은 대체되지 않습니다. 이러한 토큰은 A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, WMI(property)입니다. 다른 정적 토큰은 성공적으로 바뀝니다. |
| ESCAPE 매크로 사용되지 않음 | 토큰을 포함하는 모든 작업이 실패합니다. | 토큰을 포함하는 모든 작업이 실패합니다. |
토큰 구문 업데이트 예제
다음은 이러한 명령을 사용하는 방법을 설명하는 데 도움이 되는 토큰 구문 예제입니다.
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;
참고 항목
이 예제에서 QUOTENAME 함수는 따옴표 문자를 설정합니다.
C. ESCAPE_NONE 매크로와 함께 토큰 사용
다음 예는 sysjobs 테이블에서 job_id를 검색하고 JOBID 토큰을 사용하여 스크립트의 앞부분에서 binary 데이터 형식으로 선언된 @JobID 변수를 채우는 스크립트의 일부입니다.
참고 항목
이진 데이터 형식에는 구분 기호가 필요하지 않으므로 ESCAPE_NONE 매크로는 JOBID 토큰과 함께 사용됩니다. 업데이트 스크립트를 실행한 후에는 이 작업 단계를 업데이트할 필요가 없습니다.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
이는 JOBID 토큰의 값을 @JobID에 직접 할당하여 불필요한 데이터베이스 쿼리 및 암시적 변환을 제거하고 섹션 C에서 제기된 문제를 해결합니다.