Verwalten von Lakehouse in Microsoft Fabric mit REST-API

Die Microsoft Fabric-Rest-API stellt einen Dienstendpunkt für den CRUD-Vorgang eines Fabric-Elements bereit. Die folgenden Aktionen sind für das Lakehouse verfügbar:

Voraussetzungen

• Um die Fabric-REST-API zu verwenden, musst du zuerst ein Microsoft Entra-Token für den Fabric-Dienst abrufen. Verwende dieses Token dann im Autorisierungsheader des API-Aufrufs.

• Die Microsoft Fabric-REST-API definiert einen einheitlichen Endpunkt für Vorgänge. Der Endpunkt ist https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Die Platzhalter {workspaceId} und {lakehouseId} sollten bei der Ausgabe der in diesem Artikel beschriebenen Befehle durch die entsprechenden Werte ersetzt werden.

Lakehouse CRUD

Verwenden Sie die folgende API zum Erstellen, Ändern und Entfernen des Lakehouses innerhalb eines Arbeitsbereichs.

Erstellen eines Lakehouse

Anforderung:

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

Antwort:

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

Aktualisieren eines Lakehouse

Aktualisieren Sie die Beschreibung, und benennen Sie das Lakehouse um.

Anforderung:

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

Antwort:

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

Abrufen von Lakehouse-Eigenschaften

Anforderung:

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

Antwort:

{ 
    "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" 
        } 
    } 
}

Löschen eines Lakehouse

Wenn Sie ein Lakehouse löschen, werden die Objektmetadaten und -daten gelöscht. Verknüpfungsverweise werden gelöscht, die Daten werden jedoch am Ziel beibehalten.

Anforderung:

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

Antwort: Leer

Auflisten von Tabellen in einem Lakehouse

Anforderung:

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

Antwort:

{ 
    "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" 
        } 
    ] 
} 

Diese API zum Auflisten von Tabellen unterstützt die Paginierung. Stellen Sie maxResults pro Seite als Parameter für die Anforderung bereit, und die API antwortet mit dem Fortsetzungs-URI, mit dem die nächste Ergebnisseite abgerufen werden kann.

Paginierungsbeispiel

Anforderung:

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

Antwort:

{ 
    "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" 
        } 
    ] 
}

In Tabellen laden

Diese API zeigt die Funktionen des Lakehouse-Features Laden in Tabelle an. Mit dieser API ist es möglich, CSV- und Parquet-Dateien in neue oder vorhandene Delta Lake-Tabellen im Lakehouse zu laden.

Diese API ist asynchron, sodass drei Schritte erforderlich sind:

1. Hochladen von Dateien und Ordnern in den Abschnitt Dateien mithilfe von OneLake-APIs.
2. Senden der API-Anforderung zum Laden in Tabellen.
3. Verfolgen des Status des Vorgangs bis zum Abschluss.

In den folgenden Abschnitten wird davon ausgegangen, dass die Dateien bereits hochgeladen wurden.

API-Anforderung zum Laden in Tabellen

Der Parameter mode unterstützt overwrite- und append-Vorgänge. Der Parameter pathType ist angegeben, wenn einzelne Dateien oder alle Dateien aus dem angegebenen Ordner geladen werden. Sowohl CSV als auch parquet werden als Datei-format-Parameter unterstützt.

In diesem Beispiel wird eine CSV-Datei namens demo.csv in eine vorhandene Tabelle mit dem Namen demo hochgeladen.

Anforderung:

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" 
    } 
}

Der Antwortheader enthält den URI, um den Status der asynchronen Vorgänge abzufragen. Der URI befindet sich in der Variable Location des Antwortheaders.

Die Location-Variable enthält einen URI wie folgt: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373. Die GUID-32ad6d2a-82bb-420d-bb57-4620c8860373 ist die Vorgangs-ID, um den Status der Ausführung von Ladevorgängen für Tabellenvorgänge abzufragen, wie im nächsten Abschnitt beschrieben.

Überwachen der Vorgänge zum Laden in Tabellen

Nachdem Sie die operationId aus der Antwort der API-Anforderung zum Laden in Tabellen erfasst haben, führen Sie die folgende Anforderung aus:

Anforderung:

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

Antwort:

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

Möglicher Vorgangsstatus für das Laden in Tabellen:

• 1: Vorgang nicht gestartet
• 2: Wird ausgeführt
• 3: Erfolg
• 4: Fehler

Tabellenwartung

Diese API zeigt die Möglichkeiten des Tabellenwartungsfeatures in Lakehouse. Mit diesen API können Bin-Verdichtung, V-Reihenfolge und Bereinigung nicht referenzierter alter Dateien angewendet werden.

Diese API ist asynchron, sodass zwei Schritte erforderlich sind:

1. Übermitteln der API-Anforderung zur Tabellenwartung.
2. Verfolgen des Status des Vorgangs bis zum Abschluss.

API-Anforderung zur Tabellenwartung

In diesem Beispiel wird ein Tabellenwartungsauftrag ausgeführt, der die V-Reihenfolge auf eine Tabelle anwendet und gleichzeitig die Z-Reihenfolge auf die Spalte tipAmount anwendet und den VACUUM-Vorgang mit einer Aufbewahrung von sieben Tagen und einer Stunde ausführt.

Anforderung:

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"
        }
    }
}
 

Der Antwortheader enthält den URI, um den Status der asynchronen Vorgänge abzufragen. Der URI befindet sich in der Variable Location des Antwortheaders.

Die Location-Variable enthält einen URI wie folgt: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. Die GUID-f2d65699-dd22-4889-980c-15226deb0e1b ist die Vorgangs-ID, um den Status der Ausführung der Tabellenwartungsvorgänge abzufragen, wie im nächsten Abschnitt beschrieben.

Überwachen von Tabellenwartungsvorgängen

Nachdem Sie operationId aus der Antwort der API-Anforderung zum Laden in Tabellen erfasst haben, führen Sie die folgende Anforderung aus:

Anforderung:

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

Antwort:

{
    "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
            }
        }
    }
}

Möglicher Vorgangsstatus für Tabellenwartung:

• NotStarted: Auftrag nicht gestartet
• InProgress: Auftrag ist in Bearbeitung
• Completed: Auftrag abgeschlossen
• Failed: Fehler beim Auftrag
• Canceled: Auftrag abgebrochen
• Deduped: Eine Instanz desselben Auftragstyps wird bereits ausgeführt, und diese Auftragsinstanz wird übersprungen.

Zugehöriger Inhalt

• Lakehouse-Feature Laden in Tabellen.
• Verwenden des Tabellenwartungsfeatures zum Verwalten von Delta-Tabellen in Fabric.
• Delta Lake-Tabellenoptimierung und V-Reihenfolge.