Gerenciar lakehouse no Microsoft Fabric com a API REST

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

Pré-requisitos

• Para usar a API REST de malha, primeiro você precisa obter um token Microsoft Entra para o serviço Fabric. Em seguida, 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 operações. O ponto final é 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.

Lakehouse CRUD

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

Criar uma casa no lago

Pedido:

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 uma casa no lago

Atualize a descrição e renomeie a Lakehouse.

Pedido:

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 propriedades lakehouse

Pedido:

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 uma casa do lago

Quando você exclui uma 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.

Pedido:

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

Resposta:Vazio

Listar tabelas em uma Lakehouse

Pedido:

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 tabelas de lista suporta 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

Pedido:

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 em tabelas

Esta API apresenta os recursos do recurso Load to Tables lakehouse. Com esta API, é possível carregar arquivos CSV e parquet para tabelas de lago delta novas ou existentes na casa do lago.

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

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

As secções seguintes pressupõem que os ficheiros já foram carregados.

Carregar para tabelas Solicitação de API

O mode parâmetro suporta overwrite e append opera. pathType parâmetro especificado se estiver carregando arquivos individuais ou todos os arquivos da pasta especificada. Ambos CSV e parquet são suportados como o parâmetro de arquivo format .

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

Pedido:

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 forma: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/bbbbcccc-1111-dddd-2222-eeee3333ffff. O guid bbbbcccc-1111-dddd-2222-eeee3333ffff é o ID da operação para consultar o status das operações de carga em execução para tabelas, conforme descrito na próxima seção.

Monitoramento de operações de carga para tabelas

Depois de capturar o operationId da resposta da solicitação de API load to tables, execute a seguinte solicitação:

Pedido:

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

Resposta:

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

Possível status da operação para carregar em tabelas:

• 1 - Operação não iniciada
• 2 - Corrida
• 3 - Sucesso
• 4 - Falhou

Manutenção de tabelas

Esta API apresenta os recursos do recurso de manutenção de mesa Lakehouse. Com esta API, é possível aplicar compactação binária, V-Order e limpeza de ficheiros antigos não referenciados (vacuum).

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

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

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

Este exemplo executa um trabalho de manutenção de tabela que aplica V-Order a uma tabela, enquanto também aplica Z-Order tipAmount à coluna e executa a VACUUM operação com uma retenção de sete dias e uma hora.

Pedido:

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 forma: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/ccccdddd-2222-eeee-3333-ffff4444aaaa. O guid ccccdddd-2222-eeee-3333-ffff4444aaaa é o ID da operação para consultar o status das operações de manutenção de tabela em execução, conforme descrito na próxima seção.

Monitorização das operações de manutenção de quadros

Depois de capturar operationId da resposta da solicitação de API load to tables, execute a seguinte solicitação:

Pedido:

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

Possível estado de funcionamento para manutenção da mesa:

• NotStarted - Trabalho não iniciado
• InProgress - Trabalhos em curso
• Concluído - Trabalho concluído
• Falhou - Falha no trabalho
• Cancelado - Trabalho cancelado
• Deduped - Uma instância do mesmo tipo de trabalho já está em execução e essa instância de trabalho foi ignorada

Conteúdos relacionados

• Carregar para tabelas Lakehouse recurso.
• Use o recurso de manutenção de tabela para gerenciar tabelas delta no Fabric.
• Otimização da tabela Delta Lake e V-Order.