Azure Data Factory 또는 Synapse Analytics에서 스크립트 작업을 사용하여 데이터 변환
적용 대상:
Azure Data Factory Azure Synapse Analytics
팁
기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!
Data Factory 또는 Synapse 파이프라인의 데이터 변환 작업을 통해 원시 데이터를 변환 및 처리하여 예측 가능한, 통찰력 있는 정보로 만듭니다. 스크립트 작업은 파이프라인이 지원하는 변환 작업 중 하나입니다. 이 문서는 데이터 변환 및 지원되는 변환 작업의 일반적인 개요를 제공하는 데이터 변환 문서를 기반으로 합니다.
스크립트 작업을 사용하여 DML(데이터 조작 언어) 및 DDL(데이터 정의 언어)을 사용하여 일반적인 작업을 실행할 수 있습니다. INSERT, UPDATE, DELETE, SELECT와 같은 DML 문을 사용하면 사용자가 데이터베이스에서 데이터를 삽입, 수정, 삭제, 검색할 수 있습니다. CREATE, ALTER 및 DROP과 같은 DDL 문을 사용하면 데이터베이스 관리자가 테이블, 인덱스 및 사용자와 같은 데이터베이스 개체를 만들고 수정하고 제거할 수 있습니다.
스크립트 작업을 사용하여 엔터프라이즈 또는 Azure VM(가상 머신)의 다음 데이터 저장소 중 하나에서 SQL 스크립트를 호출할 수 있습니다.
- Azure SQL Database
- Azure Synapse Analytics
- SQL Server 데이터베이스. SQL Server를 사용 중인 경우 데이터베이스를 호스트하는 동일한 컴퓨터 또는 데이터베이스에 대한 액세스 권한이 있는 별도 컴퓨터에서 자체 호스팅 통합 런타임을 설치합니다. 자체 호스팅 통합 런타임은 온-프레미스/Azure VM에서 데이터 원본을 클라우드 서비스에 안전하고 관리되는 방식으로 연결하는 구성 요소입니다. 자세한 내용은 자체 호스팅 통합 런타임 문서를 참조하세요.
- Oracle
- Snowflake
스크립트는 단일 SQL 문 또는 순차적으로 실행되는 여러 SQL 문을 포함할 수 있습니다. 스크립트 태스크는 다음 용도로 사용할 수 있습니다.
- 데이터를 삽입을 준비하기 위해 테이블을 자릅니다.
- 테이블 및 뷰와 같은 데이터베이스 개체를 만들고 변경 및 삭제합니다.
- 팩트 및 차원 테이블에 데이터를 로드하기 전에 해당 테이블을 다시 만듭니다.
- 저장 프로시저를 실행합니다. SQL 문이 임시 테이블의 결과를 반환하는 저장 프로시저를 호출하는 경우 WITH RESULT SETS 옵션을 사용하여 결과 집합의 메타데이터를 정의합니다.
- 쿼리에서 반환된 행 집합을 다운스트림 사용을 위한 활동 출력으로 저장합니다.
구문 세부 정보
다음은 스크립트 작업을 정의하는 JSON 형식입니다.
{
"name": "<activity name>",
"type": "Script",
"linkedServiceName": {
"referenceName": "<name>",
"type": "LinkedServiceReference"
},
"typeProperties": {
"scripts" : [
{
"text": "<Script Block>",
"type": "<Query> or <NonQuery>",
"parameters":[
{
"name": "<name>",
"value": "<value>",
"type": "<type>",
"direction": "<Input> or <Output> or <InputOutput>",
"size": 256
},
...
]
},
...
],
...
]
},
"scriptBlockExecutionTimeout": "<time>",
"logSettings": {
"logDestination": "<ActivityOutput> or <ExternalStore>",
"logLocationSettings":{
"linkedServiceName":{
"referenceName": "<name>",
"type": "<LinkedServiceReference>"
},
"path": "<folder path>"
}
}
}
}
다음 표에서는 이러한 JSON 속성에 대해 설명합니다.
| Property name | 설명 | 필수 |
|---|---|---|
| name | 활동의 이름입니다. | 예 |
| type | 작업의 형식이며 “Script”로 설정합니다. | 예 |
| typeProperties | 스크립트 작업을 구성할 속성을 지정합니다. | 예 |
| linkedServiceName | 스크립트가 실행되는 대상 데이터베이스입니다. 연결된 서비스에 대한 참조여야 합니다. | 예 |
| scripts | 스크립트를 나타내는 개체의 배열입니다. | 아니요 |
| scripts.text | 쿼리 블록의 일반 텍스트입니다. | 아니요 |
| scripts.type | 쿼리 블록의 형식입니다. Query 또는 NonQuery일 수 있습니다. 기본값: Query. | 아니요 |
| scripts.parameter | 스크립트의 매개 변수 배열입니다. | 아니요 |
| scripts.parameter.name | 매개 변수의 이름입니다. | 아니요 |
| scripts.parameter.value | 매개 변수의 값입니다. | 아니요 |
| scripts.parameter.type | 매개 변수의 데이터 형식입니다. 형식은 논리적 형식이며 각 커넥터의 형식 매핑을 따릅니다. | 아니요 |
| scripts.parameter.direction | 매개 변수의 방향입니다. Input, Output, InputOutput일 수 있습니다. 방향이 Output이면 값이 무시됩니다. ReturnValue 형식은 지원되지 않습니다. SP의 반환 값을 출력 매개 변수로 설정하여 검색합니다. | 아니요 |
| scripts.parameter.size | 매개 변수의 최대 크기입니다. string/byte[] 형식의 Output/InputOutput 방향 매개 변수에만 적용됩니다. | 아니요 |
| scriptBlockExecutionTimeout | 제한 시간이 초과되기 전에 스크립트 블록 실행 작업이 완료되기 위한 대기 시간입니다. | 아니요 |
| logSettings | 출력 로그를 저장할 설정입니다. 지정하지 않으면 스크립트 로그를 사용할 수 없습니다. | 아니요 |
| logSettings.logDestination | 로그 출력의 대상입니다. ActivityOutput 또는 ExternalStore일 수 있습니다. 기본값: ActivityOutput. | 아니요 |
| logSettings.logLocationSettings | logDestination이 ExternalStore인 경우 대상 위치의 설정입니다. | 아니요 |
| logSettiongs.logLocationSettings.linkedServiceName | 대상 위치의 연결된 서비스입니다. Blob Storage만 지원됩니다. | 아니요 |
| logSettings.logLocationSettings.path | 로그가 저장될 폴더 경로입니다. | 아니요 |
활동 출력
샘플 출력:
{
"resultSetCount": 2,
"resultSets": [
{
"rowCount": 10,
"rows":[
{
"<columnName1>": "<value1>",
"<columnName2>": "<value2>",
...
}
]
},
...
],
"recordsAffected": 123,
"outputParameters":{
"<parameterName1>": "<value1>",
"<parameterName2>": "<value2>"
},
"outputLogs": "<logs>",
"outputLogsLocation": "<folder path>",
"outputTruncated": true,
...
}
| Property name | 설명 | 조건 |
|---|---|---|
| resultSetCount | 스크립트에서 반환된 결과 집합의 수입니다. | Always |
| resultSets | 모든 결과 집합을 포함하는 배열입니다. | Always |
| resultSets.rowCount | 결과 집합의 총 행 수입니다. | Always |
| resultSets.rows | 결과 집합의 행 배열입니다. | Always |
| recordsAffected | 스크립트에서 영향을 받는 행의 행 수입니다. | scriptType이 NonQuery인 경우 |
| outputParameters | 스크립트의 출력 매개 변수입니다. | 매개 변수 형식이 Output 또는 InputOutput인 경우 |
| outputLogs | 스크립트에서 작성한 로그(예: print 문)입니다. | 커넥터가 log 문을 지원하고 enableScriptLogs가 true이고 logLocationSettings가 제공되지 않는 경우 |
| outputLogsPath | 로그 파일의 전체 경로입니다. | enableScriptLogs가 true이고 logLocationSettings가 제공된 경우 |
| outputTruncated | 출력이 한도를 초과하여 잘리는지 여부를 나타냅니다. | 출력이 한도를 초과하는 경우 |
참고 항목
- 스크립트 블록이 실행될 때마다 출력이 수집됩니다. 최종 출력은 모든 스크립트 블록 출력의 병합된 결과입니다. 다른 스크립트 블록에서 이름이 같은 출력 매개 변수는 덮어쓰여집니다.
- 출력에는 크기/행 제한이 있으므로 출력은 로그 -> 매개변수 -> 행 순서로 잘립니다. 이것은 단일 스크립트 블록에 적용됩니다. 즉, 다음 스크립트 블록의 출력 행이 이전 로그를 제거하지 않습니다.
- 로그로 인한 오류는 작업에 실패하지 않습니다.
- 다운 스트림 작업의 활동 출력 resultSets를 사용하려면 조회 작업 결과 설명서를 참조하세요.
- 로깅 용도로 'PRINT' 문을 사용하는 경우 outputLogs를 사용합니다. 쿼리가 resultSets를 반환하는 경우 활동 출력에서 사용할 수 있으며 5,000개 행/4MB 크기 제한으로 제한됩니다.
UI를 사용하여 스크립트 작업 구성
Inline script(인라인 스크립트)
인라인 스크립트는 파이프라인 CI/CD와 잘 통합됩니다. 스크립트가 파이프라인 메타데이터의 일부로 저장되기 때문입니다.
로깅
로깅 옵션:
- 사용 안 함 - 실행 출력이 기록되지 않습니다.
- 활동 출력 – 스크립트 실행 출력이 활동 출력에 추가됩니다. 다운스트림 활동에서 사용할 수 있습니다. 출력 크기는 4MB로 제한됩니다.
- 외부 스토리지 – 스토리지에 출력을 유지합니다. 출력 크기가 2MB보다 크거나 스토리지 계정에 출력을 명시적으로 유지하려는 경우 이 옵션을 사용합니다.
참고 항목
청구 - 스크립트 작업은 파이프라인 활동으로 청구됩니다.
관련 콘텐츠
다른 방법으로 데이터를 변환하는 방법을 설명하는 다음 문서를 참조하세요.