Gerenciar um lakehouse com a API REST

Este artigo aborda cenários comuns para gerenciar um lakehouse programaticamente com a API REST Microsoft Fabric. Cada seção mostra a solicitação HTTP e a resposta de uma tarefa específica para que você possa adaptar o padrão aos seus scripts ou aplicativos de automação.

Para obter a especificação completa, incluindo todos os parâmetros, permissões necessárias, esquemas de solicitação e códigos de erro, consulte a referência da API REST do Lakehouse.

Pré-requisitos

Obtenha um token do Microsoft Entra para o serviço Fabric e inclua-o no Authorization cabeçalho de cada solicitação.
Substitua {workspaceId} e {lakehouseId} nos exemplos abaixo por seus próprios valores.

Criar, atualizar e excluir um lakehouse

Os exemplos a seguir mostram como provisionar um novo lakehouse, renomeá-lo, recuperar suas propriedades (incluindo o ponto de extremidade de análise de SQL provisionado automaticamente) e excluí-lo. Para obter a lista de parâmetros completa e exemplos adicionais (como criar um lakehouse habilitado para esquema ou criar com uma definição), consulte a referência à API de Itens do Lakehouse.

Criar um lakehouse

Para criar um lakehouse em um workspace, envie uma solicitação POST com o nome de exibição. O Fabric provisiona automaticamente um ponto de extremidade de análise SQL junto ao lakehouse.

Solicitação

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses
{ 
    "displayName": "demo"
}

Resposta

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

Atualizar um lakehouse

Para renomear um lakehouse ou atualizar sua descrição, envie uma requisição PATCH contendo os novos valores.

Solicitação

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

Resposta

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

Obter as propriedades do lakehouse

Recupere os metadados do lakehouse, incluindo os caminhos do OneLake e a string de conexão do ponto de extremidade de análise do SQL.

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

Excluir um lakehouse remove seus metadados e dados. Os atalhos são removidos, mas os dados no destino de atalho são preservados.

Solicitação

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

Resposta

O corpo da resposta está vazio.

Listar as tabelas em uma casa de lago

Para recuperar todas as tabelas Delta em um lakehouse — por exemplo, para criar um catálogo de dados ou validar uma implantação — use o ponto de extremidade Listar Tabelas. Para obter a lista completa de parâmetros, consulte a referência da API de Tabelas.

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 tabelas de lista dá suporte à paginação. Passe maxResults como um parâmetro de consulta para controlar o tamanho da página. A resposta inclui uma continuationUri que você pode usar para recuperar a próxima página.

Paginar em uma lista de tabela grande

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 um arquivo em uma tabela Delta

Para converter arquivos CSV ou Parquet em tabelas Delta sem escrever código Spark, use a API de Tabela de Carga. Esse é o equivalente programático do recurso Carregar para Tabelas na home page do Lakehouse. Para obter a lista de parâmetros completa, consulte a referência da API de Tabela de Carga.

A operação é assíncrona. Siga estas etapas:

Carregue arquivos na seção Lakehouse Files usando APIs do OneLake.
Envie a solicitação de carga.
Monitorar o status da operação até que ela seja concluída.

Os exemplos a seguir pressupõem que os arquivos já estão carregados.

Enviar a solicitação de carga

Este exemplo carrega um arquivo CSV nomeado demo.csv em uma tabela nomeada demo, substituindo todos os dados existentes. Defina mode para Append para adicionar linhas. Defina pathType para Folder carregar todos os arquivos em uma pasta.

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

A resposta não inclui um corpo. Em vez disso, o Location cabeçalho contém um URI que você usa para sondar o status da operação. O URI segue este padrão:

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

Consultar o status da operação de carga

Use o operationId do cabeçalho Location para verificar o progresso:

Solicitação

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

Resposta

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

Possíveis status de operações para carregamento em tabelas:

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

Executar a manutenção da tabela em uma tabela Delta

Para otimizar tabelas Delta — aplicando bin-compaction, V-Order, Z-Order ou VACUUM — sem usar o Lakehouse Explorer, use a API de Manutenção de Tabela. Esse é o equivalente programático do recurso de manutenção da tabela. Para obter a lista completa de parâmetros, consulte a referência da API de Manutenção de Tabela.

A operação é assíncrona. Siga estas etapas:

Envie a solicitação de manutenção da tabela.
Monitorar o status da operação até que ela seja concluída.

Enviar a solicitação de manutenção da tabela

Este exemplo aplica a otimização de V-Order e o Z-Order na tipAmount coluna e executa o VACUUM com um período de retenção de sete dias e uma hora.

Solicitação

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

A resposta não inclui um corpo. O Location cabeçalho contém um URI que você usa para sondar o status da operação:

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

O ponto de extremidade de execução tem escopo de lakehouse, mas a sondagem de instância de trabalho usa o ponto de extremidade genérico de trabalho de item (/items/{itemId}/jobs/instances/{jobInstanceId}) por design.

Importante

A configuração de um período de retenção menor que sete dias afeta a "viagem no tempo Delta" e pode causar falhas de leitor ou corrupção de tabelas se os instantâneos ou os arquivos não confirmados ainda estiverem em uso. Por esse motivo, a manutenção da tabela nas APIs REST e da interface do usuário do Fabric rejeita períodos de retenção abaixo de sete dias por padrão. Para permitir um intervalo mais curto, defina spark.databricks.delta.retentionDurationCheck.enabled para false nas configurações do espaço de trabalho, pois os trabalhos de manutenção da tabela usarão essa configuração durante false execução.

Consultar o status de manutenção da tabela

Use o operationId cabeçalho para verificar o status do trabalho:

Solicitação

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

Essa rota de sondagem usa items intencionalmente em vez de lakehouses.

Resposta

{
    "id": "{operationId}",
    "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
    "jobType": "TableMaintenance",
    "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
Cancelado – Trabalho cancelado
Deduped – Uma instância do mesmo tipo de trabalho já está em execução e esta instância é ignorada

Comentários

Esta página foi útil?

Last updated on 2026-03-11

Compartilhar via

Gerenciar um lakehouse com a API REST

Pré-requisitos

Criar, atualizar e excluir um lakehouse

Criar um lakehouse

Atualizar um lakehouse

Obter as propriedades do lakehouse

Excluir um lakehouse

Listar as tabelas em uma casa de lago

Paginar em uma lista de tabela grande

Carregar um arquivo em uma tabela Delta

Enviar a solicitação de carga

Consultar o status da operação de carga

Executar a manutenção da tabela em uma tabela Delta

Enviar a solicitação de manutenção da tabela

Consultar o status de manutenção da tabela

Conteúdo relacionado

Comentários

Recursos adicionais