Gerenciar lakehouse no Microsoft Fabric com a API REST

Artigo
09/05/2024

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:

Ação	Descrição
Criar	Cria uma casa de lago dentro de um espaço de trabalho. Um ponto de extremidade de análise SQL também é provisionado junto com o lakehouse.
Atualizar	Atualiza o nome de um lakehouse e o ponto de extremidade de análise SQL.
Delete	Exclui o lakehouse e o ponto de extremidade de análise SQL associado.
Obter propriedades	Obtém as propriedades de um lakehouse e o ponto de extremidade de análise SQL.
Listar tabelas	Listar tabelas na casa do lago.
Carga da tabela	Cria tabelas delta a partir de arquivos e pastas CSV e parquet.
Manutenção de tabelas	Aplique bin-compaction, V-Order e remoção de arquivos antigos e não referenciados.

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.

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/dc39f96a-47d7-4c2d-9358-740f50c0aa31 
{ 
    "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:

Carregue arquivos e pastas para a seção Arquivos do Lakehouse usando as APIs do OneLake.
Enviar carga para a solicitação de API de tabelas.
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/32ad6d2a-82bb-420d-bb57-4620c8860373. O guid 32ad6d2a-82bb-420d-bb57-4620c8860373 é 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 bin-compaction, V-Order e limpeza de arquivos antigos não referenciados.

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

Enviar solicitação de API de manutenção de tabela.
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}",
        "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/f2d65699-dd22-4889-980c-15226deb0e1b. O guid f2d65699-dd22-4889-980c-15226deb0e1b é 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

Partilhar via

Gerenciar lakehouse no Microsoft Fabric com a API REST

Pré-requisitos

Lakehouse CRUD

Criar uma casa no lago

Atualizar uma casa no lago

Obter propriedades lakehouse

Excluir uma casa do lago

Listar tabelas em uma Lakehouse

Carregar em tabelas

Carregar para tabelas Solicitação de API

Monitoramento de operações de carga para tabelas

Manutenção de tabelas

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

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

Comentários

Recursos adicionais

Partilhar via

Gerenciar lakehouse no Microsoft Fabric com a API REST

Pré-requisitos

Lakehouse CRUD

Criar uma casa no lago

Atualizar uma casa no lago

Obter propriedades lakehouse

Excluir uma casa do lago

Listar tabelas em uma Lakehouse

Exemplo de paginação

Carregar em tabelas

Carregar para tabelas Solicitação de API

Monitoramento de operações de carga para tabelas

Manutenção de tabelas

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

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

Conteúdos relacionados

Comentários

Recursos adicionais