Utilize a API Files com volumes do Unity Catalog

Use a API de Ficheiros para ler, escrever, listar e eliminar ficheiros e diretórios por caminho. Funciona com ficheiros em volumes do Unity Catalog, aos quais se refere pelo seu caminho de volume absoluto, como /Volumes/<catalog>/<schema>/<volume>/<path>. Os pedidos da API 3.0 de ficheiros usam o prefixo de endpoint /api/3.0/fs e vão para o nome de anfitrião regional do seu espaço de trabalho. Para cada operação, parâmetro e cabeçalho, consulte a referência Files API 3.0.

A utilização da Files API pode incorrer em encargos de transferência de dados do Azure Databricks.

Enviar solicitações para o nome de anfitrião regional

Enviar pedidos para a Send Files API 3.0 para o nome de anfitrião regional do espaço de trabalho ao qual o utilizador requerente pertence. O hostname regional apresenta o seguinte formato:

<workspace-id>.storage.<workspace-region>.<databricks-domain>

Por exemplo, 1234567890123456.storage.westus.azuredatabricks.net.

Para encontrar o ID e a região do seu espaço de trabalho, use a consola da conta. Consulte Nomes, URLs e IDs das instâncias do espaço de trabalho. Também pode encontrar o ID do espaço de trabalho na URL de implementação: em https://<databricks-instance>/?o=1234567890123456, o número a seguir a o= é o ID do espaço de trabalho. A interface do espaço de trabalho mostra a região abaixo do nome do espaço de trabalho.

Configurar a conectividade de rede

A API de ficheiros 3.0 requer conectividade de rede da sua rede para o Azure Databricks e do Azure Databricks para o seu armazenamento.

Da tua rede para Azure Databricks

Se permitires o acesso público à internet ao teu espaço de trabalho mas o restringires com um firewall, adiciona à lista de permissões os intervalos de IP do plano de controlo para a tua região.

Inclua os IPs em IPs do Control Plane, incluindo armazenamento predefinido e webapp. Veja Tráfego de entrada para o plano de controlo do Azure Databricks.

Se não permitir acesso à internet ao Azure Databricks e se ligar através de um link privado front-end, crie um segundo link privado front-end para serviços que exigem muito desempenho. Consulte Configurar Ligação Privada de entrada para serviços que exigem muito desempenho.

Do Azure Databricks para o seu armazenamento

Se permitir o acesso público ao seu armazenamento mas aplicar restrições de rede, para armazenamento dentro da região, adicione as suas contas de armazenamento a um perímetro de segurança de rede Azure (NSP) e depois adicione a AzureDatabricksServerless etiqueta de serviço à lista de permissões. O perímetro de segurança da rede deve manter-se em modo de transição. Caso contrário, adicione à lista de permissões as IPs de saída do Azure Databricks.

Se não permitires acesso público ao teu armazenamento, configura uma ligação privada para o teu armazenamento do Azure. Consulte Configurar conectividade privada para recursos do Azure.

Carregar ficheiros grandes com carregamento em várias partes

Um único pedido de upload aceita ficheiros até 5000 MiB. Para carregar um ficheiro maior, ou um ficheiro cujo tamanho é desconhecido quando o upload começa, use o upload multiparte: carrega o ficheiro em partes, e o Azure Databricks monta-as num único ficheiro.

Os números de peça variam de 1 a 10000. Todas as partes, exceto a última, devem ter pelo menos 5 MiB, e cada parte pode ter no máximo 4000 MiB. Azure Databricks monta as partes em ordem crescente de número de peça. Para cada parâmetro, consulte Carregar um ficheiro e Executar uma ação num ficheiro.

Exemplo de carregamento em múltiplas partes

O exemplo seguinte carrega um ficheiro em duas partes.

Para iniciar a sessão de upload, inicie o upload. A resposta contém o upload_id que identifica a sessão:

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=initiate-upload

200 OK
Content-Type: application/json
{
  "upload_id": "dvOR6FE39mNb"
}

Para carregar a primeira parte, envie o seu conteúdo com upload_id e part_number. A resposta inclui a parte:ETag

PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=1
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>

200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Para carregar a segunda parte, repita o pedido com o próximo part_number:

PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=2
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>

200 OK
ETag: "954fb694be262821177cfbc47f9d4a0aa06c349b"

Para terminar, complete o carregamento com um corpo que liste todas as peças e os respetivos valores armazenados ETag:

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=complete-upload&upload_id=dvOR6FE39mNb
Content-Type: application/json
{
  "parts": [
    { "part_number": 1, "etag": "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"" },
    { "part_number": 2, "etag": "\"954fb694be262821177cfbc47f9d4a0aa06c349b\"" }
  ]
}

200 OK
ETag: "b3f1c2a94d6e7085f2a1c0b9e8d7654321fedcba"

O ETag nesta resposta pertence à totalidade do ficheiro montado, não a uma parte. Podes usá-lo em pedidos condicionais posteriores, por exemplo, para sobrescrever o ficheiro apenas se não tiver mudado desde que o carregaste.

Para cancelar o upload em vez de o completar, envie a abort-upload ação com o upload_id:

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=abort-upload&upload_id=dvOR6FE39mNb

200 OK

Descarregue ficheiros grandes com pedidos de intervalo

Utilize pedidos com intervalo para descarregar um ficheiro grande em vários pedidos mais pequenos, ou para retomar uma transferência interrompida.

Solicite um intervalo

Envia o Range cabeçalho com as posições baseadas em zero do primeiro e último bytes que queres. O intervalo inclui ambas as posições. Por exemplo, bytes=0-1048575 solicita os primeiros 1 MiB de um ficheiro de 10 MiB:

GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=0-1048575

206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-1048575/10485760
Content-Length: 1048576
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
<binary data>

A 206 Partial Content resposta contém apenas os bytes solicitados e Content-Range mostra quais bytes contém e o tamanho total do ficheiro. Para ler até ao fim do ficheiro, omita a última posição, como em bytes=1048576-. Se a última posição estiver para além do final do ficheiro, a resposta contém os bytes até ao fim. Para outra Range sintaxe, veja Descarregar um ficheiro.

Um pedido HEAD com um cabeçalho Range devolve o mesmo estado e cabeçalhos que o pedido GET correspondente, sem o corpo.

Retomar um download interrompido

Para retomar um download, peça os bytes restantes com um intervalo que comece no primeiro byte que ainda não recebeu. Também envie If-Match com o ETag da sua primeira resposta, para não combinar bytes de duas versões do ficheiro:

GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=1048576-
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 1048576-10485759/10485760
Content-Length: 9437184
<binary data>

Se o ficheiro mudou, o servidor devolve 412 Precondition Failed, e tem de iniciar o download novamente.

Usar solicitações condicionais

Um pedido condicional só entra em vigor se o ficheiro estiver no estado em que espera que ele esteja. Utilize pedidos condicionais para evitar downloads repetidos, para evitar que escritores simultâneos sobreescrevam alterações uns dos outros e para criar ou eliminar ficheiros em segurança. A API de Ficheiros 3.0 suporta os quatro cabeçalhos condicionais HTTP padrão do RFC 9110:

Quando a condição não é cumprida, o servidor não executa a operação e devolve um dos seguintes estados:

• 304 Not Modified, quando um pedido GET ou HEAD com If-None-Match ou If-Modified-Since falha. A sua cópia em cache continua válida.
• 412 Precondition Failed, quando qualquer outra condição falha.

Validadores: ETag e Last-Modified

Os cabeçalhos condicionais comparam um valor que fornece com um dos validadores do ficheiro. A Files API retorna ambos os validadores como cabeçalhos de resposta em GET e HEAD:

• ETag: um identificador opaco para o conteúdo do ficheiro, também devolvido em PUT e na resposta multiparte complete-upload. Guarde-a exatamente como foi devolvida, incluindo as aspas à volta, e não a processe nem a construa.
• Last-Modified: o tempo da última modificação do ficheiro, como data HTTP. A sua precisão é de um segundo, por isso If-Modified-Since e If-Unmodified-Since não conseguem detetar várias alterações no mesmo segundo. Para controlo de concorrência, use ETag com If-Match ou If-None-Match.

Leituras condicionais

A leitura condicional mais comum é a revalidação de cache. Envie If-None-Match com o ETag da sua cópia em cache, ou If-Modified-Since com a hora da última vez que a obteve. Se o ficheiro não tiver sido alterado, o servidor retorna 304 Not Modified sem corpo. Caso contrário, regressa 200 OK com o novo conteúdo:

GET /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

304 Not Modified

If-Match e If-Unmodified-Since funcionam ao contrário: o servidor devolve o ficheiro apenas se este não tiver mudado, e caso contrário devolve 412. Uma leitura pode incluir, no máximo, dois cabeçalhos condicionais, e a sua precedência segue o RFC 9110.

Gravações condicionais

Em PUT, use If-None-Match e If-Match para evitar sobrescrever alterações que não viu, também chamado de problema da atualização perdida:

• If-None-Match: * faz upload do ficheiro apenas se não existir nenhum ficheiro no caminho. Caso contrário, a solicitação retorna 412 Precondition Failed.
• If-Match: <etag> carrega o ficheiro apenas se o ETag atual corresponder ao que fornece. Caso contrário, o pedido devolve 412 Precondition Failed, ou 404 se não existir ficheiro no caminho.

Para criar um ficheiro apenas se ele ainda não existir, envie If-None-Match: *:

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: *
Content-Type: application/octet-stream
<binary data>

200 OK

Para sobrescrever um ficheiro apenas se ainda for a versão que obtiveste pela última vez, envia o seu ETag com If-Match:

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/octet-stream
<binary data>

200 OK

Para um upload multiparte, envie o cabeçalho condicional na initiate-upload chamada. A Files API avalia-o quando o upload termina, por isso a condição aplica-se ao ficheiro montado. Para os formulários de cabeçalho que cada chamada suporta, consulte Carregar um ficheiro e Executar uma ação sobre um ficheiro.

Eliminações condicionadas

Um checkout simples DELETE tem sucesso mesmo que o ficheiro não exista, por isso não te pode dizer se removeste a versão que pretendias. Para tornar uma eliminação condicional, envie If-Match:

• If-Match: <etag> Apaga o ficheiro apenas se o seu atual ETag coincidir com o que forneceste. Se alguém alterou o ficheiro depois de o ter obtido, o pedido devolve 412 Precondition Failed. Se o ficheiro já não existir, devolve 404.
• If-Match: * apaga o ficheiro apenas se existir, e devolve 404 se não existir.

DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Versões da API de ficheiros

A API de Ficheiros 2.0 envia pedidos para o hostname do seu espaço de trabalho com o prefixo de endpoint /api/2.0/fs. Não suporta upload multiparte, e o seu único cabeçalho condicional é If-Unmodified-Since para downloads. Consulte a referência Files API 2.0.

Para mover código da API de Ficheiros 2.0 para a 3.0, faça as seguintes alterações:

• Envie pedidos para o hostname regional com o /api/3.0/fs prefixo do endpoint e configure a conectividade de rede.
• Envia o Content-Length cabeçalho em cada upload. Se não souberes o tamanho do ficheiro de antemão, usa upload multiparte.
• Espere 200 OK em vez de 204 No Content de um carregamento bem-sucedido.
• Espere 204 No Content, não 404 Not Found, quando apagas um ficheiro que não existe. Ver Eliminações condicionais.