Gerir uma casa de lago com a API REST

Este artigo percorre cenários comuns para gerir programáticamente uma casa de lago com a API REST do Microsoft Fabric. Cada secção mostra o pedido HTTP e a resposta para uma tarefa específica para que possas adaptar o padrão aos teus scripts ou aplicações de automação.

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

Pré-requisitos

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

Criar, atualizar e eliminar uma casa de lago

Os exemplos seguintes mostram como provisionar uma nova casa de lago, renomeá-la, recuperar as suas propriedades (incluindo o endpoint de análise SQL auto-provisionado) e eliminá-la. Para a lista completa de parâmetros e exemplos adicionais (como criar uma casa de lago com esquema ou criar com uma definição), consulte a referência da API Lakehouse Items.

Criar uma casa no lago

Para criar uma casa de lago num espaço de trabalho, envie um pedido POST com o nome de visualização. O Fabric provisiona automaticamente um endpoint de análise SQL junto ao lakehouse.

Pedido

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

Para renomear uma casa de lago ou atualizar a sua descrição, envie um pedido PATCH com os novos valores.

Pedido

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

Recuperar os metadados do lakehouse, incluindo os caminhos OneLake e a cadeia de conexão do ponto final de análise SQL.

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

Eliminar uma casa de lago remove os seus metadados e dados. Os atalhos são removidos, mas os dados no alvo do atalho são preservados.

Pedido

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

Resposta

O corpo da resposta está vazio.

Liste as mesas numa casa de lago

Para recuperar todas as tabelas Delta num lakehouse — por exemplo, para construir um catálogo de dados ou validar uma implementação — use o endpoint List Tables. Para a lista completa de parâmetros, consulte a referência da API Tables.

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 Listas suporta paginação. Passe maxResults como parâmetro de consulta para controlar o tamanho da página. A resposta inclui um continuationUri que pode chamar para recuperar a página seguinte.

Paginar por uma grande lista de tabelas

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 um ficheiro numa tabela Delta

Para converter ficheiros CSV ou Parquet em tabelas Delta sem escrever código Spark, use a API Load Table. Este é o equivalente programático da funcionalidade Load to Tables na página inicial do Lakehouse. Para a lista completa de parâmetros, consulte a referência da API Load Table.

A operação é assíncrona. Siga estes passos:

1. Carregue ficheiros para a secção Ficheiros do Lakehouse usando as APIs do OneLake.
2. Submete o pedido de carregamento.
3. Consulta o estado da operação até que termine.

Os exemplos seguintes assumem que os ficheiros já foram carregados.

Submeter o pedido de carregamento

Este exemplo carrega um ficheiro CSV nomeado demo.csv numa tabela chamada demo, sobrescrevendo quaisquer dados existentes. Defina mode como Append para, em vez disso, adicionar linhas. Defina pathType como Folder para carregar todos os ficheiros numa pasta.

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

A resposta não inclui um corpo. Em vez disso, o Location cabeçalho contém um URI que usas para consultar o estado da operação. O URI segue este padrão:

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

Inquirir o estado da operação de carga

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

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

Executar a manutenção da tabela numa tabela Delta

Para otimizar tabelas Delta — aplicando compactação em lotes, V-Order, Z-Order ou VACUUM — sem usar o Lakehouse Explorer, utilize a API de Manutenção de Tabelas. Isto é o equivalente programático da funcionalidade de manutenção de tabelas. Para a lista completa de parâmetros, consulte a referência da API de Manutenção de Tabelas.

A operação é assíncrona. Siga estes passos:

1. Submeta o pedido de manutenção da mesa.
2. Consulta o estado da operação até que termine.

Submeta o pedido de manutenção da tabela

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

Pedido

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 utiliza para consultar o estado da operação:

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

O endpoint 'run' tem escopo associado ao lakehouse, mas a interrogação das instâncias de tarefas utiliza o endpoint genérico de item de trabalho (/items/{itemId}/jobs/instances/{jobInstanceId}) por design.

Verificar o estado de manutenção da tabela

Use o operationId do cabeçalho Location para verificar o estado do trabalho.

Pedido

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

Esta rota de sondagem intencionalmente utiliza items 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
}

Estado de operação possível para manutenção da tabela.

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

Conteúdos relacionados

• Referência da API REST de Lakehouse
• Carregar nas Tabelas
• Use a funcionalidade de manutenção de tabelas para gerir tabelas delta no Fabric
• Otimização da tabela Delta Lake e V-Order
• Início rápido da API REST do Fabric