OneLake REST의 카탈로그 통합 구성하기¶

OneLake REST API 엔드포인트에 대한 카탈로그 통합을 생성하려면 이 항목의 단계를 따릅니다. 이 엔드포인트는 Microsoft Fabric의 테이블과 상호 작용하는 데 사용할 수 있는 OneLake 테이블 APIs의 엔드포인트입니다. 이 엔드포인트에 대한 자세한 내용은 Microsoft Fabric 설명서의 `Iceberg용 OneLake 테이블 APIs 시작하기<https://learn.microsoft.com/en-us/fabric/onelake/table-apis/iceberg-table-apis-get-started>`_를 참조하세요.

이 카탈로그 통합을 통해 Snowflake를 사용하여 Iceberg 메타데이터가 있는 OneLake 테이블을 읽을 수 있습니다.

전제 조건¶

시작하기 전에 Fabric의 작업 공간에 대한 작업 공간 ID 및 Fabric의 레이크하우스에 대한 데이터 항목 ID를 찾아야 합니다. OneLake REST에 대한 카탈로그 통합을 생성하는 경우 나중에 작업 공간 ID 및 데이터 항목 ID를 지정합니다.
- 작업 공간 ID(<workspaceID>)를 찾으려면 작업 공간의 항목에 대한 Fabric 사이트의 URL을 참조하십시오. 자세한 내용은 Microsoft Fabric 설명서의 `작업 공간 ID 식별하기<https://learn.microsoft.com/en-us/fabric/admin/portal-workspace#identify-your-workspace-id>`_을 참조하세요. 작업 공간 ID를 텍스트 편집기에 복사합니다.
- 데이터 항목 ID(``<dataItemID>)를 찾으려면 레이크하우스를 연 후 URL에서 레이크하우스 뒤의 값을 참조합니다. 자세한 내용은 Microsoft Fabric 설명서의 `레이크하우스 Source 구성<https://learn.microsoft.com/en-us/fabric/data-factory/connector-lakehouse-copy-activity#source>`_ 및 ‘연결’ 글머리 기호를 참조하세요. 데이터 항목 ID를 텍스트 편집기에 복사합니다.
Fabric 작업 공간에서 모든 데이터 항목(예: 레이크하우스)에 Iceberg 테이블이 있는지 확인합니다.

1단계: OneLake에 대한 액세스 권한 구성하기¶

OneLake에 대한 액세스 권한을 구성하려면 Microsoft Azure에서 애플리케이션 등록을 만들고, 애플리케이션 등록에 user_impersonation 권한을 추가하고, 애플리케이션 등록을 위한 새 클라이언트 시크릿을 만듭니다.

Azure에서 애플리케이션 등록을 만듭니다.

자세한 내용은 Microsoft Entra 설명서의 `Microsoft Entra ID에 애플리케이션 등록하기<https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app>`_를 참조하세요.
애플리케이션 등록에서 user_impersonation 권한을 추가합니다.

시작하려면 Microsoft 그래프 설명서의 `Microsoft Entra 관리 센터를 사용하여 조직에서 사용하는 APIs 찾기<https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-configure-permissions?tabs=http&pivots=entra-portal-api-permissions#use-the-microsoft-entra-admin-center-to-find-the-apis-your-organization-uses>`_에 나와 있는 4단계를 따릅니다.

중요

해당 단계에 설명된 대로 APIs my organization uses 탭으로 전환하지 마세요. 대신 Microsoft APIs 탭으로 전환하고 Azure Storage`를 선택한 후 :extui:`user_impersonation 권한을 추가합니다.
애플리케이션 등록을 위한 새 클라이언트 시크릿을 만든 다음 시크릿을 텍스트 편집기에 복사합니다.

지침은 Microsoft Entra 설명서의 `새 클라이언트 시크릿 만들기<https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret>`_를 참조하세요. 카탈로그 통합을 생성할 때 이 시크릿을 지정합니다.

중요

시크릿은 나중에 검색할 수 없으므로 반드시 텍스트 편집기에 복사해야 합니다.
애플리케이션 등록의 Overview 페이지에서 Display name, Application (client) ID, :extui:`Directory (tenant) ID`를 텍스트 편집기에 복사합니다.

카탈로그 통합 및 외부 볼륨을 생성할 때 해당 값을 지정합니다.

2단계: 애플리케이션 등록에 Fabric 작업 공간에 대한 액세스 권한 부여하기¶

이 단계에서는 애플리케이션 등록에 Fabric의 작업 공간에 대한 액세스 권한을 부여합니다.

`Microsoft Fabric<https://app.fabric.microsoft.com/>`_으로 이동한 후 로그인합니다.
Microsoft Fabric 작업 공간을 엽니다.
Manage access 을 선택합니다.
+ Add people or groups 을 선택합니다.
Enter name or email 필드에서 애플리케이션 등록 이름을 붙여넣습니다.

이 이름은 :ref:`OneLake에 대해 액세스 권한이 구성<label-configure_access_permissions_onelake>`될 때 복사한 :extui:`Display name`입니다.
앱이 필요한 Fabric 항목을 생성하도록 허용하려면 드롭다운 메뉴에서 Contributor 이상의 액세스 권한을 선택합니다.
Add 을 선택합니다.

3단계: Snowflake에서 카탈로그 통합 만들기¶

CREATE CATALOG INTEGRATION(Apache Iceberg™ REST) 명령을 사용하여 REST API 엔드포인트에 대한 카탈로그 통합을 생성합니다.

예:

CREATE OR REPLACE CATALOG INTEGRATION my_onelake_catalog_int
   CATALOG_SOURCE = ICEBERG_REST
   TABLE_FORMAT = ICEBERG
   REST_CONFIG = (
      CATALOG_URI = 'https://onelake.table.fabric.microsoft.com/iceberg'
      CATALOG_NAME = '<fabric_data_item_scope>'
   )
   REST_AUTHENTICATION = (
      TYPE = OAUTH
      OAUTH_TOKEN_URI = '<azure_active_directory_token_endpoint>'
      OAUTH_CLIENT_ID = '<entra_application_client_id>'
      OAUTH_CLIENT_SECRET = '<entra_application_client_secret>'
      OAUTH_ALLOWED_SCOPES = ('https://storage.azure.com/.default')
   )
   ENABLED = TRUE;

Copy

여기서

``https://onelake.table.fabric.microsoft.com/iceberg``는 OneLake 테이블 엔드포인트의 기본 URL입니다.
<fabric_data_item_scope>는 `` is the Fabric data item scope, in the form ``<workspaceID>/<dataItemID>, such as 12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91과 같은 형식의 Fabric 데이터 항목 범위입니다. ``. To find your ``<workspaceID> 및 and ``<dataItemID>``를 찾으려면 전제 조건 섹션을 참조하세요.
<azure_active_directory_token_endpoint_>는 is your Azure Active Directory OAuth 2.0 token endpoint URL, in the form of https://login.microsoftonline.com/<entra_tenant_id>/oauth2/v2.0/token과 같은 형식의 Azure Active Directory OAuth 2.0 토큰 엔드포인트 URL입니다.. For <entra_tenant_id> :ref:`ID에 대해 액세스 권한이 구성<label-configure_access_permissions_onelake>`될 때 복사한 Entra 테넌트 OneLake를 지정합니다.
<entra_application_client_id>``는 :ref:`OneLake에 대해 액세스 권한이 구성<label-configure_access_permissions_onelake>`될 때 복사한 Entra 애플리케이션 클라이언트 ID입니다(예: ``11111111-aabb-1a11-abc1-ab11111a11a1).
``<entra_application_client_secret>``은 :ref:`OneLake에 대해 액세스 권한이 구성<label-configure_access_permissions_onelake>`될 때 복사한 애플리케이션 클라이언트 시크릿입니다.
``https://storage.azure.com/.default``는 저장소 토큰 대상 그룹입니다.

4단계: 외부 볼륨 구성¶

이 단계에서는 Azure OneLake URL 및 Entra 테넌트 ID를 사용하여 Azure용 외부 볼륨을 구성합니다.

CREATE EXTERNAL VOLUME 명령을 사용하여 외부 볼륨을 생성합니다.

예:
```
CREATE OR REPLACE EXTERNAL VOLUME my_onelake_extvol
   STORAGE_LOCATIONS =
   (
      (
            NAME = 'my_onelake_extvol'
            STORAGE_PROVIDER = 'AZURE'
            STORAGE_BASE_URL = '<azure_onelake_url>'
            AZURE_TENANT_ID='<entra_tenant_id>'
      )
   )
   ALLOW_WRITES = FALSE;
```
Copy
여기서
- <azure_onelake_url>은 `` is your Azure OneLake URL, in the form of ``azure://onelake.dfs.fabric.microsoft.com/<workspaceID>/<dataItemID>와 같은 형식의 Azure Active Directory OAuth 2.0 토큰 엔드포인트 URL입니다(예: ``, such as ``azure://onelake.dfs.fabric.microsoft.com/12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91).. To find your <workspaceID> 및 and ``<dataItemID>``를 찾으려면 전제 조건 섹션을 참조하세요.
- ``<entra_tenant_id>는 `` is your Entra tenant ID, such as, ``11111111-aabb-1a11-abc1-ab11111a11a1``과 같은 형식의 Entra tenant ID입니다. :ref:`OneLake에 대해 액세스 권한이 구성<label-configure_access_permissions_onelake>`될 때 Entra tenant ID를 복사했습니다.

Microsoft 권한 요청 페이지의 URL을 검색하려면 DESCRIBE EXTERNAL VOLUME 명령을 사용하십시오. 이전에 생성한 외부 볼륨의 이름을 지정합니다.

DESC EXTERNAL VOLUME my_onelake_extvol;

Copy

다음 속성의 값을 기록합니다.

속성	설명
`AZURE_CONSENT_URL`	Microsoft 권한 요청 페이지에 대한 URL입니다.
`AZURE_MULTI_TENANT_APP_NAME`	계정에 대해 생성된 Snowflake 클라이언트 애플리케이션의 이름입니다. 이 섹션의 이후 단계에서는 허용되는 저장소 위치에 대한 액세스 토큰을 획득하기 위한 권한을 이 애플리케이션에 부여해야 합니다.

다음 단계에서 이러한 값을 사용합니다.

웹 브라우저에서 Microsoft 권한 요청 페이지(AZURE_CONSENT_URL)로 이동합니다.
Accept 를 선택합니다. 이 작업을 통해 Snowflake 계정에 대해 생성된 Azure 서비스 주체에게 tenant 내부의 모든 리소스에 대한 액세스 토큰이 부여됩니다. 액세스 토큰은 서비스 주체에 저장소 계정 수준에 적절한 권한을 부여한 경우에만 획득이 가능합니다(다음 단계 참조).
다중 테넌트 애플리케이션에 Fabric의 허용된 저장소 위치에 대한 액세스 토큰을 얻을 수 있는 권한을 부여합니다.
1. `Microsoft Fabric<https://app.fabric.microsoft.com/>`_으로 이동한 후 로그인합니다.
2. Microsoft Fabric 작업 공간을 엽니다.
3. Manage access 을 선택합니다.
4. + Add people or groups 을 선택합니다.
5. Enter name or email 필드에서 AZURE_MULTI_TENANT_APP_NAME에 대해 기록한 값을 붙여넣습니다..
6. 앱이 필요한 Fabric 항목을 생성하도록 허용하려면 드롭다운 메뉴에서 Contributor 이상의 액세스 권한을 선택합니다.
7. Add 을 선택합니다.

자세한 내용은 Microsoft Fabric의 `REST 엔드포인트에 대한 Snowflake 카탈로그 통합 및 외부 볼륨 코드 예제<https://learn.microsoft.com/en-us/fabric/onelake/table-apis/iceberg-table-apis-get-started#snowflake>`_를 참조하세요.

다음 단계¶

OneLake REST 및 외부 볼륨에 대한 카탈로그 통합을 구성한 후 CREATE DATABASE(카탈로그 연결) 명령을 사용하여 카탈로그 연결 데이터베이스를 생성한 다음 Snowflake의 OneLake에서 테이블을 읽습니다.

카탈로그 연결 데이터베이스를 생성하는 경우 생성한 카탈로그 통합 및 외부 볼륨을 지정합니다.

예:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'my_onelake_catalog_int'
   )
   EXTERNAL_VOLUME = 'my_onelake_extvol';

SELECT SYSTEM$CATALOG_LINK_STATUS('IRC_CATALOG_LINKED');

SELECT * FROM my_linked_db."dbo"."sentiment";

Copy

참고

Snowflake는 OneLake의 테이블에 대한 읽기 작업만 지원합니다.