Microsoft OneLake에 연결
Microsoft OneLake는 기존 ADLS(Azure Data Lake Storage) Gen2 API 및 SDK를 통해 모든 Fabric 항목에 대한 공개 액세스를 제공합니다. OneLake URI를 대신 사용하여 ADLS Gen2와 호환되는 API, SDK 또는 도구를 통해 OneLake의 데이터에 액세스할 수 있습니다. Azure Storage Explorer를 통해 레이크하우스에 데이터를 업로드하거나 Azure Databricks의 바로 가기를 통해 델타 테이블을 읽을 수 있습니다.
OneLake는 SaaS(Software as a Service)이므로 권한 관리 또는 항목 업데이트와 같은 일부 작업은 ADLS Gen2 API 대신 Fabric 환경을 통해 수행해야 합니다. 이러한 API에 대한 변경 내용의 전체 목록은 OneLake API 패리티를 참조하세요.
URI 구문
OneLake는 전체 Microsoft Fabric 테넌트에 존재하기 때문에 해당 작업 영역, 항목 및 경로로 테넌트 내의 모든 항목을 참조할 수 있습니다.
https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>
참고 항목
여러 항목 종류에서 항목 이름을 다시 사용할 수 있으므로 확장에서 항목 종류를 지정해야 합니다. 예를 들어 레이크하우스의 경우 .lakehouse, 웨어하우스의 경우 .datawarehouse입니다.
또한 OneLake는 GUID(Globally Unique Identifier)를 사용하여 작업 영역 및 항목 참조를 지원합니다. OneLake는 GUID를 할당하며 작업 영역 또는 항목 이름이 변경되더라도 GUID는 변경되지 않습니다. Fabric 포털의 URL에서 작업 영역 또는 항목에 대한 연결된 GUID를 찾을 수 있습니다. 작업 영역과 항목 모두에 GUID를 사용해야 하며 항목 종류가 필요하지 않습니다.
https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName>
ADLS Gen2 대신 OneLake를 통해 사용할 도구를 채택하는 경우 다음 매핑을 사용합니다.
- 계정 이름은 항상
onelake입니다. - 컨테이너 이름은 작업 영역 이름입니다.
- 데이터 경로는 항목에서 시작됩니다. 예:
/mylakehouse.lakehouse/Files/
또한 OneLake는 ADLS Gen2 및 Azure Blob Storage와의 호환성을 위해 ABFS(Azure Blob Filesystem 드라이버)를 지원합니다. ABFS 드라이버는 자체 스키마 식별자 abfs 및 다른 URI 형식을 사용하여 ADLS Gen2 계정의 파일 및 디렉터리를 처리합니다. OneLake에서 이 URI 형식을 사용하려면 파일 시스템에 대한 작업 영역을 교환하고 항목 및 항목 종류를 포함합니다.
abfs[s]://<workspace>@onelake.dfs.fabric.microsoft.com/<item>.<itemtype>/<path>/<fileName>
abfs 드라이버 URI는 작업 영역 이름에 공백과 같은 특수 문자를 허용하지 않습니다. 이러한 경우 이 섹션의 앞부분에서 설명한 대로 GUID(Globally Unique Identifiers)를 사용하여 작업 영역 및 항목을 참조할 수 있습니다.
인증
인증 헤더를 전달하여 Microsoft Entra ID를 사용하여 OneLake API를 인증할 수 있습니다. 도구에서 토큰 통과를 사용하도록 설정하기 위해 Azure 계정에 로그인을 지원하는 경우 구독을 선택할 수 있습니다. OneLake는 사용자 토큰만 필요하며 Azure 구독에 대해 신경 쓰지 않습니다.
DFS API를 통해 OneLake를 직접 호출하는 경우 Microsoft Entra 계정에 대한 전달자 토큰으로 인증할 수 있습니다. 조직에 대한 전달자 토큰을 요청하고 관리하는 방법에 대한 자세한 내용은 Microsoft 인증 라이브러리를 확인하세요.
직접 API 호출을 사용하여 OneLake를 신속하게 임시 테스트하려면 PowerShell을 사용하여 Azure 계정에 로그인하고 스토리지 범위 토큰을 검색하고 다른 곳에서 쉽게 사용할 수 있도록 클립보드에 복사하는 간단한 예제가 있습니다. PowerShell을 사용하여 액세스 토큰을 검색하는 방법에 대한 자세한 내용은 Get-AzAccessToken을 참조하세요.
참고 항목
OneLake는 Storage 대상 그룹의 토큰만 지원합니다. 다음 예제에서는 ResourceTypeName 매개 변수를 통해 대상 그룹을 설정합니다.
Connect-AzAccount
$testToken = Get-AzAccessToken -ResourceTypeName Storage
# Retrieved token is of string type which you can validate with the "$testToken.Token.GetTypeCode()" command.
$testToken.Token | Set-Clipboard
데이터 보존
글로벌 끝점('https://onelake.dfs.fabric.microsoft.com`)을 사용하여 작업 영역의 지역과 다른 지역의 데이터를 쿼리하는 경우 끝점 확인 프로세스 중에 데이터가 해당 지역을 떠날 수 있습니다. 데이터 보존이 우려되는 경우 작업 영역에 올바른 지역 끝점을 사용하면 데이터가 현재 지역 내에 유지되고 지역 경계를 넘지 않습니다. 작업 영역이 연결된 용량의 지역을 확인하여 올바른 지역 끝점을 검색할 수 있습니다.
OneLake 지역 끝점은 모두 동일한 형식을 따릅니다. https://<region>-onelake.dfs.fabric.microsoft.com 예를 들어 미국 서부 지역의 용량에 연결된 작업 영역은 지역 엔드포인트 https://westus-onelake.dfs.fabric.microsoft.com을 통해 액세스할 수 있습니다.
일반적인 문제
ADLS Gen2와 호환되는 도구 또는 패키지가 OneLake에서 작동하지 않는 경우 가장 일반적인 문제는 URL 유효성 검사입니다. OneLake는 ADLS Gen2(dfs.core.windows.net)와 다른 끝점(dfs.fabric.microsoft.com)을 사용하므로 일부 도구는 OneLake 끝점을 인식하고 차단하지 않습니다. 일부 도구를 사용하면 사용자 지정 엔드포인트(예: PowerShell)를 사용할 수 있습니다. 그렇지 않으면 OneLake의 끝점을 지원되는 끝점으로 추가하는 간단한 수정 사항인 경우가 많습니다. URL 유효성 검사 문제가 발견되거나 OneLake에 연결하는 데 다른 문제가 있는 경우 알려주세요.
샘플
파일 만들기
| 요청 | PUT https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file |
|---|---|
| 헤더 | Authorization: Bearer <userAADToken> |
| Response | ResponseCode: 201 Created헤더: x-ms-version : 2021-06-08x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67bx-ms-content-crc64 : OAJ6r0dQWP0=x-ms-request-server-encrypted : trueETag : 0x8DA58EE365본문: |