Gerenciar o lakehouse no Microsoft Fabric com a API REST
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": "hkpobavgthae5kji5cuqxtivcu-dda6npvkyiaeteyrkfkgim53xa-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
Conteúdo relacionado
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de