Gerenciar o lakehouse no Microsoft Fabric com a API REST

A API Rest do Microsoft Fabric fornece um ponto de extremidade de serviço para a operação CRUD de um item do Fabric. As ações a seguir estão disponíveis para o Lakehouse:

Pré-requisitos

• Para usar a API REST do Fabric, primeiro você precisa obter um token do Microsoft Entra para o serviço Fabric. Depois use esse token no cabeçalho de autorização da chamada de API.

• A API Rest do Microsoft Fabric define um ponto de extremidade unificado para as operações. O ponto de extremidade é https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Os espaços reservados {workspaceId} e {lakehouseId} devem ser substituídos pelos valores apropriados ao emitir os comandos exemplificados neste artigo.

CRUD do Lakehouse

Use a API a seguir para executar a criação, as modificações e a remoção do lakehouse dentro de um workspace. Para obter parâmetros de API detalhados e exemplos de solicitação, consulte a documentação da API REST Create Lakehouse.

Criar um lakehouse

Solicitação:

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

Resposta:

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

Atualizar um lakehouse

Atualize a descrição e renomeie o Lakehouse.

Solicitação:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/aaaabbbb-0000-cccc-1111-dddd2222eeee 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
} 

Resposta:

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

Obter as propriedades do lakehouse

Solicitação:

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

Resposta:

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

Excluir um lakehouse

Quando você exclui um lakehouse, os metadados e os dados do objeto são excluídos. As referências de atalho são excluídas, mas os dados são preservados no destino.

Solicitação:

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

RespostaVazia

Listar tabelas em um Lakehouse

Solicitação:

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

Resposta:

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

A API de listagem de tabelas oferece suporte à paginação. Forneça maxResults por página como um parâmetro para a solicitação e a API responde com o URI de continuação que pode ser usado para obter a próxima página de resultados.

Exemplo de paginação

Solicitação:

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

Resposta:

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

Carregar nas tabelas

Essa API apresenta as funcionalidades do recurso Carregar para Tabelas do lakehouse. Com essa API, é possível carregar arquivos CSV e parquet para tabelas novas ou existentes do delta lake no lakehouse.

Essa API é assíncrona, portanto, são necessárias três etapas:

1. Carregue arquivos e pastas na seção Arquivos do Lakehouse usando APIs do OneLake.
2. Enviar carga para a solicitação da API de tabelas.
3. Acompanhar o status da operação até a conclusão.

As seções a seguir pressupõem que os arquivos já foram carregados.

Carregar na solicitação da API de tabelas

O parâmetro mode dá suporte a operações de overwrite e append. Parâmetro pathType especificado se estiver carregando arquivos individuais ou todos os arquivos da pasta especificada. Há suporte para CSV e parquet como o parâmetro format do arquivo.

Este exemplo carrega um arquivo CSV chamado demo.csv em uma tabela existente chamada demo.

Solicitação:

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

O cabeçalho de resposta contém o URI para sondar o status das operações assíncronas. O URI está na variável Location do cabeçalho de resposta.

A variável Location contém um URI da seguinte maneira: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/bbbbcccc-1111-dddd-2222-eeee3333ffff. O GUID bbbbcccc-1111-dddd-2222-eeee3333ffff é a ID da operação para consultar o status da execução da carga em operações de tabelas, conforme descrito na próxima seção.

Monitorar as operações Carregar para Tabelas

Depois de capturar a operationId da resposta à solicitação da API Carregar para Tabelas, execute a seguinte solicitação:

Solicitação:

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

Resposta:

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

Status de operação possíveis para carregar para tabelas:

• 1– Operação ainda não iniciada
• 2 – Em execução
• 3 – Êxito
• 4 – Com falha

Manutenção de tabela

Essa API apresenta as funcionalidades do recurso de manutenção de tabela do Lakehouse. Com essa API, é possível aplicar bin-compaction, V-Order e limpeza de arquivos antigos não referenciados (vácuo).

Essa API é assíncrona, portanto, são necessárias duas etapas:

1. Enviar a solicitação da API de manutenção de tabela.
2. Acompanhar o status da operação até a conclusão.

Solicitação da API de manutenção de tabela

Este exemplo executa um trabalho de manutenção de tabela que aplica a ordem V a uma tabela, ao mesmo tempo em que aplica a ordem Z à coluna tipAmount e executa a operação VACUUM com uma retenção de sete dias e uma hora.

Solicitação:

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

O cabeçalho de resposta contém o URI para sondar o status das operações assíncronas. O URI está na variável Location do cabeçalho de resposta.

A variável Location contém um URI da seguinte maneira: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/ccccdddd-2222-eeee-3333-ffff4444aaaa. O GUID ccccdddd-2222-eeee-3333-ffff4444aaaa é a ID da operação para consultar o status da execução das operações de manutenção de tabela, conforme descrito na próxima seção.

Monitoramento das operações de manutenção de tabelas

Depois de capturar a operationId da resposta à solicitação da API Carregar para Tabelas, execute a seguinte solicitação:

Solicitação:

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

Resposta:

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

Status de operação possível para a manutenção da tabela:

• NotStarted – Trabalho não iniciado
• InProgress – Trabalho em andamento
• Completed – Trabalho concluído
• Failed – O trabalho falhou
• Canceled – Trabalho cancelado
• Deduped – Uma instância do mesmo tipo de trabalho já está em execução e essa instância de trabalho é ignorada

Conteúdo relacionado

• Recurso Carregar para Tabelas do Lakehouse.
• Usar o recurso de manutenção de tabelas para gerenciar tabelas Delta no Fabric.
• Otimização de tabela do Delta Lake e V-Order.