Synapse SQL을 사용하여 안전하게 데이터 로드

아티클
02/29/2024

이 문서에서는 COPY 문의 보안 인증 메커니즘을 설명하고 예시를 보여줍니다. COPY 문은 Synapse SQL에서 데이터를 대량 로드하기 위한 가장 유연하고 안전한 방법입니다.

지원되는 인증 메커니즘

다음 표에서는 각 파일 유형 및 스토리지 계정에 대해 지원되는 인증 방법을 설명합니다. 원본 스토리지 위치 및 오류 파일 위치에 적용됩니다.

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/SERVICE PRINCIPAL/KEY/AAD	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE PRINCIPAL/KEY/AAD	SAS(blob¹)/MSI(dfs²)/SERVICE PRINCIPAL/KEY/AAD	SAS(blob¹)/MSI(dfs²)/SERVICE PRINCIPAL/KEY/AAD

1: 이 인증 방법에는 외부 위치 경로의 .blob 엔드포인트(.blob.core.windows.net)가 필요합니다.

2: 이 인증 방법에는 외부 위치 경로의 .dfs 엔드포인트(.dfs.core.windows.net)가 필요합니다.

A. 행 종결자로 LF가 사용되는 스토리지 계정 키(Unix 스타일의 줄 바꿈)

--Note when specifying the column list, input field numbers start from 1
COPY INTO target_table (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://adlsgen2account.dfs.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV'
    ,CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_Account_Key>')
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<secret>'),
    ,ROWTERMINATOR='0x0A' --0x0A specifies to use the Line Feed character (Unix based systems)
)

Important

16진수 값(0x0A)을 사용하여 줄 바꿈 문자를 지정합니다. COPY 문은 \n 문자열을 \r\n(캐리지 리턴 줄 바꿈)으로 해석합니다.

B. 행 종결자로 CRLF를 사용하는 SAS(공유 액세스 서명)(Windows 스타일 줄 바꿈)

COPY INTO target_table
FROM 'https://adlsgen2account.dfs.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV'
    ,CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSFSYsz4AkN'),
    ,ROWTERMINATOR='\n'-- COPY command automatically prefixes the \r character when \n (newline) is specified. This results in carriage return newline (\r\n) for Windows based systems.
)

Important

ROWTERMINATOR를 '\r\r\n'으로 해석되고 구문 분석 문제를 일으킬 수 있는 '\r\n'으로 지정하지 마십시오. COPY 명령은 \n(줄 바꿈)이 지정되는 경우 자동으로 \r 문자를 접두사 지정합니다. 이로 인해 Windows 기반 시스템에 대한 캐리지 리턴 줄 바꿈(\r\n)이 생성됩니다.

C. 관리 ID

스토리지 계정이 VNet에 연결되었을 때는 관리 ID 인증이 필요합니다.

필수 조건

Azure PowerShell을 설치합니다. PowerShell 설치를 참조하세요.
범용 v1 또는 Blob 스토리지 계정이 있는 경우 먼저 범용 v2로 업그레이드해야 합니다. 범용 v2 스토리지 계정으로 업그레이드를 참조하세요.
Azure Storage 계정 방화벽 및 가상 네트워크 설정 메뉴에서 신뢰할 수 있는 Microsoft 서비스가 이 스토리지 계정에 액세스하도록 허용합니다.를 설정해야 합니다. Azure Storage 방화벽 및 가상 네트워크 구성을 참조하세요.

단계

독립 실행형 전용 SQL 풀이 있는 경우 PowerShell을 사용하여 Microsoft Entra ID에 SQL 서버를 등록합니다.
```
Connect-AzAccount
Select-AzSubscription -SubscriptionId <subscriptionId>
Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity
```
Synapse 작업 영역 내의 전용 SQL 풀에는 이 단계가 필요하지 않습니다. 작업 영역의 SA-MI(시스템 할당 관리 ID)는 Synapse 관리자 역할의 구성원이기 때문에 작업 영역의 전용 SQL 풀에서 상승된 권한을 갖습니다.
범용 v2 Storage 계정을 만듭니다. 자세한 내용은 스토리지 계정 만들기 를 참조하세요.
참고 항목
- 범용 v1 또는 Blob 스토리지 계정이 있는 경우 먼저 v2로 업그레이드해야 합니다. 자세한 내용은 범용 v2 스토리지 계정으로 업그레이드를 참조하세요.
- Azure Data Lake Storage Gen2에 대한 알려진 문제는 Azure Data Lake Storage Gen2의 알려진 문제를 참조하세요.
스토리지 계정에서 액세스 제어(IAM)를 선택합니다.
역할 할당 추가>를 선택하여 역할 할당 추가 페이지를 엽니다.

다음 역할을 할당합니다. 세부 단계에 대해서는 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

설정	값
역할	Storage Blob 데이터 Contributor
다음에 대한 액세스 할당	SERVICEPRINCIPAL
멤버	Microsoft Entra ID에 등록한 전용 SQL 풀을 호스트하는 서버 또는 작업 영역

Azure Portal에서 역할 할당 페이지 추가

참고 항목

소유자 권한이 있는 멤버만 이 단계를 수행할 수 있습니다. 다양한 Azure 기본 제공 역할에 관해서는 Azure 기본 제공 역할을 참조하세요.

Important

Storage Blob 데이터 소유자, 기여자 또는 읽기 권한자 Azure 역할을 지정합니다. 이러한 역할은 소유자, 기여자 및 읽기 권한자로 구성되는 Azure 기본 제공 역할과 다릅니다.

로드할 수 있는 Azure RBAC 권한 부여

이제 "관리 ID"를 사용하여 COPY 문을 실행할 수 있습니다.

COPY INTO dbo.target_table
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.txt'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL = (IDENTITY = 'Managed Identity'),
)

D. Microsoft Entra 인증

단계

스토리지 계정에서 액세스 제어(IAM)를 선택합니다.
역할 할당 추가>를 선택하여 역할 할당 추가 페이지를 엽니다.
다음 역할을 할당합니다. 세부 단계에 대해서는 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

설정 값

역할 Storage Blob 데이터 소유자, 기여자 또는 리더

다음에 대한 액세스 할당 USER

멤버 Microsoft Entra 사용자

Important

Storage Blob 데이터 소유자, 기여자 또는 읽기 권한자 Azure 역할을 지정합니다. 이러한 역할은 소유자, 기여자 및 읽기 권한자로 구성되는 Azure 기본 제공 역할과 다릅니다.
Microsoft Entra 인증을 구성합니다. Azure SQL에서 Microsoft Entra 인증 구성 및 관리를 참조하세요.
Active Directory를 사용하여 SQL 풀에 연결합니다. 이제 자격 증명을 지정하지 않고 COPY 문을 실행할 수 있습니다.
```
COPY INTO dbo.target_table
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.txt'
WITH (
    FILE_TYPE = 'CSV'
)
```

설정	값
역할	Storage Blob 데이터 소유자, 기여자 또는 리더
다음에 대한 액세스 할당	USER
멤버	Microsoft Entra 사용자

E. 서비스 주체 인증

단계

Microsoft Entra 애플리케이션을 만듭니다.
애플리케이션 ID 가져오기
인증 키 가져오기
V1 OAuth 2.0 토큰 엔드포인트 가져오기
스토리지 계정에서 Microsoft Entra 애플리케이션에 읽기, 쓰기 및 실행 권한을 할당합니다.

이제 COPY 문을 실행할 수 있습니다.

COPY INTO dbo.target_table
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt'
WITH (
    FILE_TYPE = 'CSV'
    ,CREDENTIAL=(IDENTITY= '<application_ID>@<OAuth_2.0_Token_EndPoint>' , SECRET= '<authentication_key>')
    --CREDENTIAL should look something like this:
    --,CREDENTIAL=(IDENTITY= '92761aac-12a9-4ec3-89b8-7149aef4c35b@https://login.microsoftonline.com/72f714bf-86f1-41af-91ab-2d7cd011db47/oauth2/token', SECRET='juXi12sZ6gse]woKQNgqwSywYv]7A.M')
)

Important

OAuth 2.0 토큰 엔드포인트의 V1 버전 사용

다음 단계

자세한 구문은 COPY 문 문서를 확인하세요.
모범 사례를 로드하려면 데이터 로드 개요 문서를 확인하세요.

다음을 통해 공유

Synapse SQL을 사용하여 안전하게 데이터 로드

지원되는 인증 메커니즘

A. 행 종결자로 LF가 사용되는 스토리지 계정 키(Unix 스타일의 줄 바꿈)

B. 행 종결자로 CRLF를 사용하는 SAS(공유 액세스 서명)(Windows 스타일 줄 바꿈)

C. 관리 ID

필수 조건

단계

D. Microsoft Entra 인증

단계

E. 서비스 주체 인증

단계

다음 단계

피드백

추가 리소스