REST API를 사용하여 Microsoft Fabric에서 Lakehouse 관리

아티클
10/15/2024

Microsoft Fabric Rest API는 Fabric 항목의 CRUD 작업에 대한 서비스 엔드포인트를 제공합니다. Lakehouse에서 사용할 수 있는 작업은 다음과 같습니다.

작업	설명
만들기	작업 영역 내에 Lakehouse를 만듭니다. 또한 SQL 분석 엔드포인트는 Lakehouse와 함께 프로비전됩니다.
엽데이트	Lakehouse 및 SQL 분석 엔드포인트의 이름을 업데이트합니다.
삭제	Lakehouse 및 연결된 SQL 분석 엔드포인트를 삭제합니다.
속성 가져오기	Lakehouse 및 SQL 분석 엔드포인트의 속성을 가져옵니다.
테이블 나열	Lakehouse의 테이블을 나열합니다.
테이블 로드	CSV 및 parquet 파일 및 폴더에서 델타 테이블을 만듭니다.
테이블 유지 관리	bin 압축, V 순서 및 참조되지 않은 파일과 이전 파일의 제거를 적용합니다.

필수 조건

Fabric REST API를 사용하려면 먼저 Fabric 서비스에 대한 Microsoft Entra 토큰을 가져오기가 필요합니다. 그런 다음 API 호출의 인증 헤더에 해당 토큰을 사용합니다.
Microsoft Fabric Rest API는 작업에 대한 통합 엔드포인트를 정의합니다. 엔드포인트가 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items인 경우 이 문서에서 예시한 명령을 실행할 때 자리 표시자 {workspaceId}와 {lakehouseId}를 적절한 값으로 바꿔야 합니다.

Lakehouse CRUD

다음 API를 사용하여 작업 영역 내에서 Lakehouse를 만들고 수정하고 제거합니다.

Lakehouse 만들기

요청:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items 
{ 
    "displayName": "demo", 
    "type": "Lakehouse" 
}

응답:

{
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

Lakehouse 업데이트하기

설명을 업데이트하고 Lakehouse의 이름을 바꿉니다.

요청:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/dc39f96a-47d7-4c2d-9358-740f50c0aa31 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

응답:

{ 
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "newname", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

Lakehouse 속성 가져오기

요청:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}

응답:

{ 
    "id": "daaa77c7-9ef4-41fc-ad3c-f192604424f5", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "bee6c118-c2aa-4900-9311-51546433bbb8", 
    "properties": { 
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Tables", 
        "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Files", 
        "sqlEndpointProperties": { 
            "connectionString": "A1bC2dE3fH4iJ5kL6mN7oP8qR9-C2dE3fH4iJ5kL6mN7oP8qR9sT0uV-datawarehouse.pbidedicated.windows.net", 
            "id": "0dfbd45a-2c4b-4f91-920a-0bb367826479", 
            "provisioningStatus": "Success" 
        } 
    } 
}

Lakehouse 삭제하기

Lakehouse를 삭제하면 개체 메타데이터 및 데이터가 삭제됩니다. 바로 가기 참조는 삭제되지만 데이터는 대상에 유지됩니다.

요청:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}

응답: 비어있음

Lakehouse의 테이블 나열

요청:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables

응답:

{ 
    "continuationToken": null, 
    "continuationUri": null, 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "demo1", 
            "location": "abfss://c522396d-7ac8-435d-8d77-442c3ff21295@onelake.dfs.fabric.microsoft.com/{workspaceId}/Tables/demo1", 
            "format": "delta" 
        } 
    ] 
}

테이블 API 나열은 페이지 매김을 지원합니다. 페이지당 maxResults를 요청에 대한 매개 변수로 제공하고 API는 결과의 다음 페이지를 가져오는 데 사용할 수 있는 연속 URI로 응답합니다.

페이지 매김 예제

요청:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?maxResults=1

응답:

{ 
    "continuationToken": "+RID:~HTsuAOseYicH-GcAAAAAAA==#RT:1#TRC:1#ISV:2#IEO:65567#QCF:8#FPC:AgKfAZ8BnwEEAAe8eoA=", 
    "continuationUri": "https://api.fabric.microsoft.com:443/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?continuationToken=%2BRID%3A~HTsuAOseYicH-GcAAAAAAA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65567%23QCF%3A8%23FPC%3AAgKfAZ8BnwEEAAe8eoA%3D", 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "nyctaxismall", 
            "location": "abfss://bee6c118-c2aa-4900-9311-51546433bbb8@onelake.dfs.fabric.microsoft.com/daaa77c7-9ef4-41fc-ad3c-f192604424f5/Tables/nyctaxismall", 
            "format": "delta" 
        } 
    ] 
}

테이블에 로드

이 API는 테이블로 로드 Lakehouse 기능의 기능을 표시합니다. 이 API를 사용하면 CSV 및 parquet 파일을 Lakehouse의 새 또는 기존 Delta Lake 테이블에 로드할 수 있습니다.

이 API는 비동기이므로 다음 세 단계가 필요합니다.

OneLake API를 사용하여 Lakehouse의 Files 섹션에 파일 및 폴더를 업로드합니다.
테이블 API 요청에 로드를 제출합니다.
완료될 때까지 작업 상태를 추적합니다.

다음 섹션에서는 파일이 이미 업로드되었다고 가정합니다.

테이블 API 요청에 로드

mode 매개 변수는 overwrite 및 append 작업을 지원합니다. pathType는 지정된 폴더에서 개별 파일 또는 모든 파일을 로드하는 경우 지정된 매개 변수입니다. CSV과 parquet 둘 다 파일 format 매개 변수로 지원됩니다.

다음은 이름이 demo.csv인 CSV 파일을 기존 테이블 demo에 업로드하는 예제입니다.

요청:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables/demo/load 
{ 
    "relativePath": "Files/demo.csv", 
    "pathType": "File", 
    "mode": "overwrite", 
    "formatOptions": 
    { 
        "header": true, 
        "delimiter": ",", 
        "format": "CSV" 
    } 
}

응답 헤더에는 비동기 작업의 상태를 폴링하는 URI가 포함되어 있습니다. URI는 응답 헤더의 Location 변수에 있습니다.

Location 변수에는 다음과 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373같은 URI가 포함됩니다. GUID 32ad6d2a-82bb-420d-bb57-4620c8860373는 다음 섹션에 설명된 대로 테이블 작업에 대한 로드 실행 상태를 쿼리하는 작업 ID입니다.

테이블로 로드 작업 모니터링

테이블 API 요청에 대한 로드 응답에서 operationId를 캡처한 후 다음 요청을 실행합니다.

요청:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/{operationId}

응답:

{ 
    "Status": 3, 
    "CreatedTimeUtc": "", 
    "LastUpdatedTimeUtc": "", 
    "PercentComplete": 100, 
    "Error": null 
}

테이블에 로드할 수 있는 작업 상태.

1 - 작동이 시작되지 않음
2 - 실행 중
3 - 성공
4 - 실패

테이블 유지 관리

이 API는 Lakehouse 테이블 유지 관리 기능의 기능을 보여줍니다. 이 API를 사용하면 bin 압축, V 순서 및 참조되지 않은 이전 파일 정리를 적용할 수 있습니다.

이 API는 비동기이므로 다음 두 단계가 필요합니다.

테이블 유지 관리 API 요청을 제출합니다.
완료될 때까지 작업 상태를 추적합니다.

테이블 유지 관리 API 요청

다음은 테이블에 V-Order를 적용하는 테이블 유지 관리 작업을 실행하는 동시에 tipAmount 열에 Z-Order 를 적용하고 7일 및 1시간의 보존 기간으로 작업을 실행하는 예제 VACUUM입니다.

요청:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=TableMaintenance
{
    "executionData": {
        "tableName": "{table_name}",
        "optimizeSettings": {
            "vOrder": true,
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7.01:00:00"
        }
    }
}

응답 헤더에는 비동기 작업의 상태를 폴링하는 URI가 포함되어 있습니다. URI는 응답 헤더의 Location 변수에 있습니다.

Location 변수에는 다음과 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b같은 URI가 포함됩니다. GUID f2d65699-dd22-4889-980c-15226deb0e1b는 다음 섹션에 설명된 대로 테이블 유지 관리 작업 실행 상태를 쿼리하는 작업 ID입니다.

테이블 유지 관리 작업 모니터링

로드 응답에서 테이블 API 요청으로 operationId를 캡처한 후 다음 요청을 실행합니다.

요청:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{operationId}

응답:

{
    "parameters": {
        "workspaceId": "{workspaceId}",
        "itemId": "{lakehouseId}",
        "jobInstanceId": "{operationId}"
    },
    "responses": {
        "200": {
            "body": {
                "id": "{operationId}",
                "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
                "jobType": "DefaultJob",
                "invokeType": "Manual",
                "status": "Completed",
                "rootActivityId": "8c2ee553-53a4-7edb-1042-0d8189a9e0ca",
                "startTimeUtc": "2023-04-22T06:35:00.7812154",
                "endTimeUtc": "2023-04-22T06:35:00.8033333",
                "failureReason": null
            }
        }
    }
}

테이블 유지 관리에 대한 가능한 작업 상태:

NotStarted - 작업이 시작되지 않음
InProgress - 진행 중인 작업
Completed - 작업이 완료되었습니다.
Failed - 작업이 실패했습니다.
Canceled - 작업 취소됨
Deduped - 동일한 작업 유형의 인스턴스가 이미 실행 중이며 이 작업 인스턴스를 건너뜁

다음을 통해 공유

REST API를 사용하여 Microsoft Fabric에서 Lakehouse 관리

필수 조건

Lakehouse CRUD

Lakehouse 만들기

Lakehouse 업데이트하기

Lakehouse 속성 가져오기

Lakehouse 삭제하기

Lakehouse의 테이블 나열

테이블에 로드

테이블 API 요청에 로드

테이블로 로드 작업 모니터링

테이블 유지 관리

테이블 유지 관리 API 요청

테이블 유지 관리 작업 모니터링

피드백

추가 리소스

다음을 통해 공유

REST API를 사용하여 Microsoft Fabric에서 Lakehouse 관리

필수 조건

Lakehouse CRUD

Lakehouse 만들기

Lakehouse 업데이트하기

Lakehouse 속성 가져오기

Lakehouse 삭제하기

Lakehouse의 테이블 나열

페이지 매김 예제

테이블에 로드

테이블 API 요청에 로드

테이블로 로드 작업 모니터링

테이블 유지 관리

테이블 유지 관리 API 요청

테이블 유지 관리 작업 모니터링

관련 콘텐츠

피드백

추가 리소스