Azure Synapse Analytics의 파일 탑재/분리 API 소개

아티클
05/24/2024

Azure Synapse Studio 팀은 Microsoft Spark Utilities(mssparkutils) 패키지에 두 개의 새로운 탑재/분리 API를 빌드했습니다. 이러한 API를 사용하여 원격 스토리지(Azure Blob Storage 또는 Azure Data Lake Storage Gen2)를 모든 작업 노드(드라이버 노드 및 작업자 노드)에 연결할 수 있습니다. 스토리지가 배치되면 로컬 파일 API를 사용하여 마치 로컬 파일 시스템에 저장된 것처럼 데이터에 액세스할 수 있습니다. 자세한 내용은 Microsoft Spark 유틸리티 소개를 참조하세요.

이 문서에서는 작업 영역에서 API 탑재/분리를 사용하는 방법을 보여 줍니다. 다음 내용을 배웁니다.

Data Lake Storage Gen2 또는 Blob Storage를 탑재하는 방법
로컬 파일 시스템 API를 통해 탑재 지점에서 파일에 액세스하는 방법
mssparktuils fs API를 사용하여 탑재 지점에서 파일에 액세스하는 방법
Spark 읽기 API를 사용하여 탑재 지점에서 파일에 액세스하는 방법
탑재 지점을 분리하는 방법

Warning

Azure 파일 공유 탑재를 일시적으로 사용할 수 없습니다. 다음 섹션에 설명된 대로 Data Lake Storage Gen2 또는 Azure Blob Storage 탑재를 대신 사용할 수 있습니다.

Azure Data Lake Storage Gen1은 지원되지 않습니다. 탑재 API를 사용하기 전에 Azure Data Lake Storage Gen1에서 Gen2로의 마이그레이션 지침에 따라 Data Lake Storage Gen2로 마이그레이션할 수 있습니다.

스토리지 탑재

이 섹션에서는 예제로 Data Lake Storage Gen2를 단계별로 탑재하는 방법을 보여 줍니다. Blob Storage 탑재 방법도 비슷합니다.

이 예제에서는 storegen2라는 Data Lake Storage Gen2 계정이 하나 있다고 가정합니다. 계정에는 Spark 풀의 /test에 탑재할 mycontainer라는 컨테이너가 하나 있습니다.

Data Lake Storage Gen2 스토리지 계정의 스크린샷

mycontainer라는 컨테이너를 탑재하려면 먼저 mssparkutils가 컨테이너에 액세스할 수 있는 권한이 있는지 확인해야 합니다. 현재 Azure Synapse Analytics는 트리거 탑재 작업에 대해 linkedService, accountKey 및 sastoken의 세 가지 인증 방법을 지원합니다.

연결된 서비스를 사용하여 탑재(권장)

연결된 서비스를 통해 트리거 탑재를 하는 것이 좋습니다. 이 방법은 mssparkutils가 비밀 또는 인증 값 자체를 저장하지 않기 때문에 보안 누출을 방지합니다. 대신 mssparkutils는 항상 연결된 서비스에서 인증 값을 가져와 원격 스토리지에서 Blob 데이터를 요청합니다.

연결된 서비스의 스크린샷

Data Lake Storage Gen2 또는 Blob Storage에 대한 연결된 서비스를 만들 수 있습니다. 현재 Azure Synapse Analytics는 연결된 서비스를 만들 때 다음과 같은 두 가지 인증 방법을 지원합니다.

계정 키를 사용하여 연결된 서비스 만들기
시스템 할당 관리 ID를 사용하여 연결된 서비스 만들기

Important

위에서 만든 Azure Data Lake Storage Gen2에 대한 연결된 서비스가 관리형 프라이빗 엔드포인트(dfs URI 포함)를 사용하는 경우 Azure Blob Storage 옵션(Blob URI 포함)을 사용하여 다른 보조 관리형 프라이빗 엔드포인트를 만들어 내부 fsspec/adlfs 코드가 BlobServiceClient 인터페이스를 사용하여 연결할 수 있도록 해야 합니다.
보조 관리형 프라이빗 엔드포인트가 올바르게 구성되지 않은 경우 ServiceRequestError: 호스트 [storageaccountname].blob.core.windows.net:443 ssl:True [이름 또는 서비스를 알 수 없음]에 연결할 수 없음과 같은 오류 메시지가 표시됩니다.

Blob 엔드포인트를 사용하여 ADLS Gen2 스토리지에 관리형 프라이빗 엔드포인트를 만드는 스크린샷.

참고 항목

관리 ID를 인증 방법으로 사용하여 연결된 서비스를 만드는 경우 작업 영역 MSI 파일에 탑재된 컨테이너의 Storage Blob 데이터 기여자 역할이 있어야 합니다.

연결된 서비스가 만들어지면 다음과 같은 Python 코드를 사용하여 컨테이너를 Spark 풀에 쉽게 탑재할 수 있습니다.

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"linkedService": "mygen2account"} 
)

참고 항목

사용할 수 없는 경우 mssparkutils를 가져와야 할 수 있습니다.

from notebookutils import mssparkutils

어떤 인증 방법을 사용하든 루트 폴더를 탑재하지 않는 것이 좋습니다.

탑재 매개 변수:

fileCacheTimeout: Blob은 기본적으로 120초 동안 로컬 임시 폴더에 캐시됩니다. 이 시간 동안 blobfuse는 파일이 최신 상태인지 여부를 확인하지 않습니다. 매개 변수를 설정하여 기본 시간 제한 시간을 변경할 수 있습니다. 로컬 파일과 원격 파일 간의 불일치를 방지하기 위해 여러 클라이언트가 동시에 파일을 수정하는 경우 캐시 시간을 단축하거나 0으로 변경하고 항상 서버에서 최신 파일을 가져오는 것이 좋습니다.
제한 시간: 탑재 작업 시간 제한은 기본적으로 120초입니다. 매개 변수를 설정하여 기본 시간 제한 시간을 변경할 수 있습니다. 실행기가 너무 많거나 탑재 시간이 초과되는 경우 값을 늘리는 것이 좋습니다.
범위: 범위 매개 변수는 탑재의 범위를 지정하는 데 사용됩니다. 기본값은 "job"입니다. 범위가 "작업"으로 설정된 경우 탑재는 현재 클러스터에만 표시됩니다. 범위가 "작업 영역"으로 설정된 경우 탑재는 현재 작업 영역의 모든 Notebook에 표시되고 탑재 지점이 없으면 자동으로 생성됩니다. 탑재 해제 API에 동일한 매개 변수를 추가하여 탑재 지점을 분리합니다. 작업 영역 수준 탑재는 연결된 서비스 인증에 대해서만 지원됩니다.

다음과 같은 매개 변수를 사용할 수 있습니다.

mssparkutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

공유 액세스 서명 토큰 또는 계정 키를 통해 탑재

연결된 서비스를 통해 탑재하는 것 외에도 mssparkutils는 대상을 탑재하기 위한 매개 변수로 계정 키 또는 SAS(공유 액세스 서명) 토큰을 명시적으로 전달하도록 지원합니다.

보안상의 이유로 계정 키 또는 SAS 토큰을 Azure Key Vault에 저장하는 것이 좋습니다(다음 예제 스크린샷에 표시됨). 그런 다음 mssparkutil.credentials.getSecret API를 사용하여 검색할 수 있습니다. 자세한 내용은 Key Vault 및 Azure CLI(레거시)를 사용하여 스토리지 계정 키 관리를 참조하세요.

자격 증명 모음에 저장된 비밀을 보여 주는 스크린샷

다음은 샘플 코드입니다.

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

참고 항목

보안상의 이유로 코드에 자격 증명을 저장하지 마세요.

mssparkutils fs API를 사용하여 탑재 지점 아래의 파일에 액세스

탑재 작업의 주요 목적은 고객이 로컬 파일 시스템 API를 사용하여 원격 스토리지 계정에 저장된 데이터에 액세스할 수 있도록 하는 것입니다. 탑재된 경로가 있는 mssparkutils fs API를 매개 변수로 사용하여 데이터에 액세스할 수도 있습니다. 여기에 사용되는 경로 형식은 약간 다릅니다.

탑재 API를 사용하여 /test에 Data Lake Storage Gen2 컨테이너 mycontainer를 탑재했다고 가정합니다. 로컬 파일 시스템 API를 통해 데이터에 액세스하는 경우:

Spark 버전이 3.3보다 작거나 같은 경우 경로 형식은 다음과 같습니다 /synfs/{jobId}/test/{filename}.
3.4보다 크거나 같은 Spark 버전의 경우 경로 형식은 다음과 같습니다 /synfs/notebook/{jobId}/test/{filename}.

정확한 경로를 가져오는 데는 다음 mssparkutils.fs.getMountPath() 을 사용하는 것이 좋습니다.

path = mssparkutils.fs.getMountPath("/test")

참고 항목

범위를 사용하여 스토리지 workspace 를 탑재하면 탑재 지점이 폴더 아래에 /synfs/workspace 만들어집니다. 그리고 정확한 경로를 가져오는 데 사용해야 mssparkutils.fs.getMountPath("/test", "workspace") 합니다.

API를 사용하여 mssparkutils fs 데이터에 액세스하려는 경우 경로 형식은 다음과 synfs:/notebook/{jobId}/test/{filename}같습니다. 이 경우 탑재된 경로의 일부 대신 synfs가 스키마로 사용되는 것을 알 수 있습니다. 물론 로컬 파일 시스템 스키마를 사용하여 데이터에 액세스할 수도 있습니다. 예들 들어 file:/synfs/notebook/{jobId}/test/{filename}입니다.

다음 세 가지 예제에서는 mssparkutils fs를 사용하여 탑재 지점 경로가 있는 파일에 액세스하는 방법을 보여 줍니다.

디렉터리 나열:

mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}')

파일 콘텐츠 읽기:

mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv')

디렉터리 만들기:

mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir')

Spark 읽기 API를 사용하여 탑재 지점에서 파일에 액세스

Spark 읽기 API를 통해 데이터에 액세스하는 매개 변수를 제공할 수 있습니다. 여기서 경로 형식은 API를 사용하는 mssparkutils fs 경우 동일합니다.

탑재된 Data Lake Storage Gen2 스토리지 계정에서 파일 읽기

다음 예제에서는 Data Lake Storage Gen2 스토리지 계정이 이미 탑재되어 있다고 가정하고 탑재 경로를 사용하여 파일을 읽습니다.

%%pyspark 

df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv') 
df.show()

참고 항목

연결된 서비스를 사용하여 스토리지를 탑재하는 경우 synfs 스키마를 사용하여 데이터에 액세스하기 전에 항상 명시적으로 Spark 연결된 서비스 구성을 설정해야 합니다. 자세한 내용은 연결된 서비스가 있는 ADLS Gen2 스토리지를 참조하세요 .

탑재된 Blob 스토리지 계정에서 파일 읽기

Blob Storage 계정을 탑재하고 mssparkutils 또는 Spark API를 사용하여 액세스하려는 경우, 탑재 API를 사용하여 컨테이너 탑재를 시도하기 전에 Spark 구성을 통해 SAS 토큰을 명시적으로 구성해야 합니다.

트리거 탑재 후 mssparkutils 또는 Spark API를 사용하여 Blob Storage 계정에 액세스하려면 다음 코드 예시와 같이 Spark 구성을 업데이트하세요. 탑재 후 로컬 파일 API를 사용해야만 Spark 구성에 액세스하려는 경우에는 이 단계를 건너뛰면 됩니다.
```
blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 

spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
```

연결된 서비스 myblobstorageaccount를 만들고 연결된 서비스를 사용하여 Blob Storage 계정을 탑재합니다.

%%spark 
mssparkutils.fs.mount( 
    "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
    "/test", 
    Map("linkedService" -> "myblobstorageaccount") 
)

Blob Storage 컨테이너를 탑재한 다음, 로컬 파일 API를 통해 탑재 경로를 사용하여 파일을 읽습니다.

    # mount the Blob Storage container, and then read the file by using a mount path
    with open(mssparkutils.fs.getMountPath("/test") + "/myFile.txt") as f:
    print(f.read())

Spark 읽기 API를 통해 탑재된 Blob Storage 컨테이너에서 데이터를 읽습니다.

%%spark
// mount blob storage container and then read file using mount path
val df = spark.read.text(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.txt')
df.show()

탑재 지점 분리

다음 코드를 사용하여 탑재 지점을 분리합니다(이 예제에서는 /test).

mssparkutils.fs.unmount("/test")

알려진 제한 사항

분리 메커니즘은 자동이 아닙니다. 애플리케이션 실행이 완료되면 탑재 지점을 분리하여 디스크 공간을 해제하려면 코드에서 분리 API를 명시적으로 호출해야 합니다. 그렇지 않으면 애플리케이션 실행이 완료된 후에도 탑재 지점이 노드에 계속 존재합니다.
Data Lake Storage Gen1 스토리지 계정 탑재는 현재 지원되지 않습니다.

다음을 통해 공유

Azure Synapse Analytics의 파일 탑재/분리 API 소개

스토리지 탑재

연결된 서비스를 사용하여 탑재(권장)

공유 액세스 서명 토큰 또는 계정 키를 통해 탑재

mssparkutils fs API를 사용하여 탑재 지점 아래의 파일에 액세스

Spark 읽기 API를 사용하여 탑재 지점에서 파일에 액세스

탑재된 Data Lake Storage Gen2 스토리지 계정에서 파일 읽기

탑재된 Blob 스토리지 계정에서 파일 읽기

탑재 지점 분리

알려진 제한 사항

다음 단계

피드백

추가 리소스