Gerenciar o lakehouse no Microsoft Fabric com a API REST

Artigo
09/05/2024

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:

Ação	Descrição
Criar	Cria um lakehouse dentro de um workspace. 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 do ponto de extremidade de análise SQL.
Listar tabelas	Lista tabelas no lakehouse.
Carga da tabela	Cria tabelas delta de arquivos e pastas CSV e parquet.
Manutenção de tabela	Aplica a compactação de bin, ordem V e remoção de arquivos não referenciados e antigos.

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.

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

Resposta Vazia

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:

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

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

Enviar a solicitação da API de manutenção de tabela.
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}",
        "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 como o seguinte: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. O GUID f2d65699-dd22-4889-980c-15226deb0e1b é 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

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.

Compartilhar via

Gerenciar o lakehouse no Microsoft Fabric com a API REST

Pré-requisitos

CRUD do Lakehouse

Criar um lakehouse

Atualizar um lakehouse

Obter as propriedades do lakehouse

Excluir um lakehouse

Listar tabelas em um Lakehouse

Carregar nas tabelas

Carregar na solicitação da API de tabelas

Monitorar as operações Carregar para Tabelas

Manutenção de tabela

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

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

Comentários

Recursos adicionais

Compartilhar via

Gerenciar o lakehouse no Microsoft Fabric com a API REST

Pré-requisitos

CRUD do Lakehouse

Criar um lakehouse

Atualizar um lakehouse

Obter as propriedades do lakehouse

Excluir um lakehouse

Listar tabelas em um Lakehouse

Exemplo de paginação

Carregar nas tabelas

Carregar na solicitação da API de tabelas

Monitorar as operações Carregar para Tabelas

Manutenção de tabela

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

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

Conteúdo relacionado

Comentários

Recursos adicionais