Use a API de Arquivos

Use a API de arquivos para ler, gravar, listar e excluir arquivos e diretórios por caminho. Funciona com arquivos em volumes do Unity Catalog, aos quais você se refere pelo caminho de volume absoluto, como /Volumes/<catalog>/<schema>/<volume>/<path>. As solicitações da API de arquivos 3.0 usam o prefixo de endpoint /api/3.0/fs e vão para o hostname regional do seu workspace. Para cada operação, parâmetro e cabeçalho, consulte a referência da API de arquivos 3.0.

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar a API de arquivos V3 com suporte a upload de arquivos grandes na página Prévias . Consulte Gerenciar prévias do Databricks.

O uso da API de arquivos pode incorrer em encargos de transferência de dados do Databricks.

Enviar solicitações para o hostname regional

Envie solicitações da API de arquivos 3.0 para o hostname regional do workspace ao qual o usuário solicitante pertence. O hostname regional tem o seguinte formato:

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

Por exemplo, 1234567890123456.storage.us-west-2.cloud.databricks.com.

Para encontrar seu ID de workspace e região, use o console da account. Consulte Nomes de instâncias, URLs e IDs de workspace. Você também pode encontrar o ID de workspace na URL de implantação: em https://<databricks-instance>/?o=1234567890123456, o número após o= é o ID do workspace. A UI do workspace mostra a região abaixo do nome do workspace.

Configurar conectividade de rede

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

Da sua rede ao Databricks

Se você permitir acesso público à internet para seu workspace, mas restringi-lo com um firewall, adicione à lista de permissões os intervalos de IP do plano de controle para sua região.

Inclua os IPs em Armazenamento default, OpenSharing SecureConnect, Ingestão Zerobus e Autoscaling Lakebase. Consulte IPs de entrada.

Se você não permitir o acesso à Internet ao Databricks e se conectar através de um link privado de front-end, crie um segundo link privado de front-end para serviços de alto desempenho. Consulte Configurar PrivateLink de entrada para serviços de alto desempenho.

Do Databricks para o seu armazenamento

Se você permitir o acesso público ao seu armazenamento, mas aplicar restrições de rede, para armazenamento na região, adicione à lista de permissões o OrgPath serverless do Databricks. Caso contrário, adicione à lista de permissões os IPs de saída do Databricks.

Se você não permitir o acesso público ao seu armazenamento, crie um link privado para o Amazon S3. Consulte Configurar conectividade privada para recursos gerenciados pela AWS.

nota

Custos de rede Serverless serão aplicados. Consulte Entender os custos de rede do Databricks.

Upload de arquivos grandes

Uma única solicitação de upload aceita arquivos de até 5000 MiB. Para fazer upload de um arquivo maior, ou de um arquivo cujo tamanho é desconhecido quando o upload começa, use um upload multipart da API de Arquivos 3.0: comece uma sessão com a ação initiate-upload, faça upload de cada parte com PUT e, em seguida, monte as partes com a ação complete-upload. Para limites de partes e detalhes da solicitação, consulte Fazer upload de um arquivo e Executar uma ação em um arquivo.

Retomar um download interrompido

Para retomar um download interrompido, solicite os bytes restantes com um cabeçalho Range que começa no primeiro byte que você ainda não recebeu. Para garantir que o arquivo não mudou entre as solicitações, envie também If-Match com o ETag da sua primeira resposta:

HTTP

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

206 Partial Content
Content-Range: bytes 1048576-10485759/10485760
<binary data>

Se o arquivo foi alterado, o servidor retornará 412 Precondition Failed e você deve começar o download novamente. Combinar bytes de diferentes versões de um arquivo corrompe o resultado. Para a sintaxe de cabeçalho de Range, consulte Download um arquivo.

Solicitações condicionais

Use cabeçalhos condicionais para execução uma solicitação apenas quando o valor ETag ou Last-Modified atual do arquivo atender a uma condição definida por você. Para os cabeçalhos que cada operação suporta, consulte a referência da API de arquivos 3.0. Ao usá-los, observe o seguinte:

• Armazene o ETag exatamente como o servidor o retorna, incluindo as aspas envolventes, e envie-o de volta inalterado. Não analise nem construa um ETag.
• Last-Modified tem uma precisão de um segundo, então If-Modified-Since e If-Unmodified-Since não conseguem detectar várias alterações no mesmo segundo. Para impedir que escritores concorrentes sobrescrevam as alterações uns dos outros, use If-Match ou If-None-Match em vez disso.
• Uma solicitação de leitura pode incluir no máximo dois cabeçalhos condicionais. Ao enviar dois, sua precedência segue a RFC 9110.

Versões da API de arquivos

A Files API 2.0 envia solicitações para o hostname do seu workspace com o prefixo de endpoint /api/2.0/fs. Ele não suporta upload de multipart e seu único cabeçalho condicional é If-Unmodified-Since em downloads. Consulte a referência da Files API 2.0.

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

• Envie solicitações para o hostname regional com o prefixo de endpoint /api/3.0/fs e configure a conectividade de rede.
• Envie o cabeçalho Content-Length em cada upload. Se você não souber o tamanho do arquivo com antecedência, use o upload multipart.
• Espere 200 OK em vez de 204 No Content de um upload bem-sucedido.
• Espere 204 No Content quando você excluir um arquivo que não existe. Para obter 404 Not Found em vez disso, como na API de Arquivos 2.0, envie If-Match: *.