Compartir a través de

Administrar almacén de lago en Microsoft Fabric con la API de REST

  • Artículo

La API de REST de Microsoft Fabric proporciona un punto de conexión de servicio para el funcionamiento de CRUD de un elemento de Fabric. Las siguientes acciones están disponibles para el almacén de lago:

Acción Descripción
Crear Crea un almacén de lago dentro de un área de trabajo. También se aprovisiona un punto de conexión de análisis SQL junto con el almacén de lago.
Actualizar Actualiza el nombre de un almacén de lago y el punto de conexión de análisis SQL.
Eliminar Elimina un almacén de lago y el punto de conexión de análisis SQL asociado.
Obtención de propiedades Obtiene las propiedades de un almacén de lago y el punto de conexión de análisis SQL.
Enumeración de tablas Enumera las tablas en el almacén de lago.
Carga de tablas Crea tablas delta a partir de CSV y de archivos y carpetas parquet.
Mantenimiento de tablas Aplica la compactación bin, el orden V y la eliminación de archivos sin referencia y antiguos.

Requisitos previos

  • Para usar la API de REST de Fabric, primero debe obtener un token de Microsoft Entra para el servicio de Fabric. A continuación, use ese token en el encabezado de autorización de la llamada API.

  • La API de REST de Microsoft Fabric define un punto de conexión unificado para las operaciones. El extremo es https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Los marcadores de posición {workspaceId} y {lakehouseId} deben reemplazarse por los valores adecuados al emitir los comandos que se ejemplifican en este artículo.

CRUD en el almacén de lago

Use la siguiente API para realizar la creación, las modificaciones y la eliminación del almacén de lago dentro de un área de trabajo.

Creación de un almacén de lago

Solicitud:

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

Respuesta:

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

Crear un almacén de lago

Actualice la descripción y cambie el nombre del almacén de lago.

Solicitud:

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

Respuesta:

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

Obtención de propiedades de almacén de lago

Solicitud:

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

Respuesta:

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

Eliminación de un almacén de lago

Al eliminar un almacén de lago, se eliminan los metadatos y los datos del objeto. Las referencias de acceso directo se eliminan, pero los datos se conservan en el destino.

Solicitud:

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

Respuesta: vacía

Enumerar tablas en un almacén de lago

Solicitud:

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

Respuesta:

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

La API de tablas de lista admite la paginación. Proporcione maxResults por página como parámetro para la solicitud y la API responde con el URI de continuación que se puede usar para obtener la siguiente página de resultados.

Ejemplo de paginación

Solicitud:

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

Respuesta:

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

Cargar en tablas

Esta API muestra las funcionalidades de la característica del almacén de lago Cargar en tablas. Con esta API, es posible cargar archivos CSV y parquet en tablas de lago delta nuevas o existentes en el almacén de lago.

Esta API es asincrónica, por lo que se requieren tres pasos:

  1. Cargue archivos y carpetas en la sección Archivos del almacén de lago mediante las API de OneLake.
  2. Envíe la carga a la solicitud de API de tablas.
  3. Realice un seguimiento del estado de la operación hasta la finalización.

En las secciones siguientes se supone que los archivos ya se cargaron.

Carga en la solicitud de API de tablas

El parámetro mode admite operaciones overwrite y append. El parámetro pathType especificado si se cargan archivos individuales o todos los archivos de la carpeta especificada. Tanto CSV como parquet se admiten como parámetro del archivo format.

En este ejemplo se carga un archivo CSV denominado demo.csv en una tabla existente denominada demo.

Solicitud:

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

El encabezado de respuesta contiene el URI para sondear el estado de las operaciones asincrónicas. El URI está en la variable Location del encabezado de respuesta.

La variable Location contiene un URI como se indica a continuación: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373. El guid 32ad6d2a-82bb-420d-bb57-4620c8860373 es el identificador de operación para consultar el estado de ejecución de la carga en las operaciones de tablas, tal como se describe en la sección siguiente.

Supervisión de la carga en las operaciones de tablas

Después de capturar el operationId de la respuesta de la carga a la solicitud de API de tablas, ejecute la siguiente solicitud:

Solicitud:

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

Respuesta:

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

Estado de operación posible para la carga en tablas:

  • 1 - Operación no iniciada
  • 2 - En ejecución
  • 3 - Correcta
  • 4 - Error

Mantenimiento de tablas

Esta API expone las funcionalidades de la característica de mantenimiento de tablas de almacén de lago. Con esta API, es posible aplicar la compactación bin, el orden V y la limpieza de archivos antiguos sin referencia.

Esta API es asincrónica, por lo que se requieren dos pasos:

  1. Envíe una solicitud de API de mantenimiento de tabla.
  2. Realice un seguimiento del estado de la operación hasta la finalización.

Solicitud de API de mantenimiento de tablas

En este ejemplo se ejecuta un trabajo de mantenimiento de tabla que aplica orden V a una tabla, mientras que también se aplica orden Z a la columna tipAmount y se ejecuta la operación VACUUM con una retención de siete días y una hora.

Solicitud:

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

El encabezado de respuesta contiene el URI para sondear el estado de las operaciones asincrónicas. El URI está en la variable Location del encabezado de respuesta.

La variable Location contiene un URI como se indica a continuación: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. El guid f2d65699-dd22-4889-980c-15226deb0e1b es el identificador de la operación para consultar el estado de las operaciones de mantenimiento de tablas en ejecución, tal como se describe en la sección siguiente.

Supervisión de operaciones de mantenimiento de tablas

Después de capturar operationId de la respuesta de la carga a la solicitud de API de tablas, ejecute la solicitud siguiente:

Solicitud:

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

Respuesta:

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

Estado de operación posible para el mantenimiento de tablas:

  • NotStarted: trabajo no iniciado
  • InProgress: trabajo en curso
  • Completed: trabajo completado
  • Error: error en el trabajo
  • Canceled: trabajo cancelado
  • Deduped: ya se está ejecutando una instancia del mismo tipo de trabajo y se omite esta instancia de trabajo

Contenido relacionado