Pular para o conteúdo principal
Última atualização em

Usar a API Files com volumes do Unity Catalog

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

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

Envie solicitações para o hostname regional​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar a API de Arquivos V3 com Suporte para Upload de Arquivos Grandes na página Prévias . Consulte Gerenciar prévias do Databricks.

Envie solicitações da API de arquivos 3.0 para o hostname regional do workspace ao qual o usuário que faz a solicitação 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 localizar o ID do seu workspace e região, use o console de account. Consulte Nomes de instâncias, URLs e IDs de workspace. Você também pode localizar o ID do 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​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar a API de Arquivos V3 com Suporte para Upload de Arquivos Grandes na página Prévias . Consulte Gerenciar prévias do Databricks.

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 para o Databricks​

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

Inclua os IPs sob Storage default, OpenSharing SecureConnect, Zerobus Ingestion e Lakebase Autoscaling. Consulte IPs de entrada.

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

Do Databricks para o seu armazenamento​

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

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

nota

A cobrança da rede serverless se aplica. Consulte Entender os custos de rede do Databricks.

Fazer upload de arquivos grandes com upload multipart​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar a API de Arquivos V3 com Suporte para Upload de Arquivos Grandes na página Prévias . Consulte Gerenciar prévias do Databricks.

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 o upload de várias partes: você faz upload do arquivo em partes, e o Databricks monta em um único arquivo.

Os números das partes variam de 1 a 10000. Cada parte, exceto a última, deve ter pelo menos 5 MiB, e cada parte pode ter no máximo 4000 MiB. O Databricks monta as partes na ordem crescente do número da parte. Para cada parâmetro, consulte Fazer upload de um arquivo e Executar uma ação em um arquivo.

Exemplo de upload multipart​

O exemplo a seguir faz upload de um arquivo em duas partes.

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

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

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

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

HTTP
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 fazer upload da segunda parte, repita a solicitação com o próximo part_number:

HTTP
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 finalizar, conclua o upload com um corpo que liste todas as partes e seu ETag armazenado:

HTTP
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 ao arquivo inteiro montado, não a uma parte. Você pode usá-lo em solicitações condicionais posteriores, por exemplo, para substituir o arquivo apenas se ele não tiver sido alterado desde que você fez o upload.

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

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

200 OK

download arquivos grandes com solicitações de intervalo​

Use solicitações de intervalo para fazer download de um arquivo grande em várias solicitações menores ou para retomar um download interrompido.

Solicitar um intervalo​

Envie o cabeçalho Range com as posições baseadas em zero dos primeiros e últimos bytes que você deseja. O intervalo inclui ambas as posições. Por exemplo, bytes=0-1048575 solicita o primeiro 1 MiB de um arquivo de 10 MiB:

HTTP
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 resposta 206 Partial Content contém apenas os bytes solicitados, e Content-Range mostra quais bytes ele contém e o tamanho total do arquivo. Para ler até o final do arquivo, omita a última posição, como em bytes=1048576-. Se a última posição estiver depois do final do arquivo, a resposta contém os bytes até o final. Para outra sintaxe de Range, consulte download um arquivo.

Uma solicitação HEAD com um cabeçalho Range retorna o mesmo status e cabeçalhos que a solicitação GET correspondente, sem o corpo.

Retomar um download interrompido​

Para retomar um download, solicite os bytes restantes com um intervalo que começa no primeiro byte que você 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 arquivo:

HTTP
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 arquivo for alterado, o servidor retornará 412 Precondition Failed, e você deverá começar o download novamente.

Usar solicitações condicionais​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar a API de Arquivos V3 com Suporte para Upload de Arquivos Grandes na página Prévias . Consulte Gerenciar prévias do Databricks.

Uma solicitação condicional entra em vigor apenas se o arquivo estiver no estado que você espera. Use solicitações condicionais para evitar downloads repetidos, para impedir que escritores concorrentes sobrescrevam as alterações uns dos outros e para criar ou excluir arquivos com segurança. A Files API 3.0 suporta os quatro cabeçalhos condicionais HTTP padrão do RFC 9110:

cabeçalho

Compara com

Honrado em

If-Match

O do arquivo ETag

Lê, grava e exclui

If-None-Match

O do arquivo ETag

Leituras e gravações

If-Modified-Since

A hora de Last-Modified do arquivo

Lê apenas

If-Unmodified-Since

A hora de Last-Modified do arquivo

Lê apenas

cabeçalho

Compara com

Honrado em

If-Match

O do arquivo ETag

Lê, grava e exclui

If-None-Match

O do arquivo ETag

Leituras e gravações

If-Modified-Since

A hora de Last-Modified do arquivo

Lê apenas

If-Unmodified-Since

A hora de Last-Modified do arquivo

Lê apenas

Quando a condição não é atendida, o servidor não executa a operação e retorna um dos seguintes status:

  • 304 Not Modified, quando uma solicitação GET ou HEAD com If-None-Match ou If-Modified-Since falha. Sua cópia em cache ainda é válida.
  • 412 Precondition Failed, quando qualquer outra condição falha.

Validadores: ETag e Last-Modified​

Os cabeçalhos condicionais comparam um valor fornecido por você com um dos validadores do arquivo. A API de Arquivos retorna ambos os validadores como cabeçalhos de resposta em GET e HEAD:

  • ETag: um identificador opaco para o conteúdo do arquivo, também retornado em PUT e na resposta multipart complete-upload. Armazene-o exatamente como retornado, incluindo as aspas circundantes, e não analise ou construa-o.
  • Last-Modified: o horário da última modificação do arquivo, como uma data HTTP. Sua precisão é de um segundo, portanto If-Modified-Since e If-Unmodified-Since não conseguem detectar várias alterações no mesmo segundo. Para controlar a concorrência, use ETag com If-Match ou If-None-Match.

Leituras condicionais​

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

HTTP
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 de maneira oposta: o servidor retorna o arquivo somente se ele não tiver sido alterado; caso contrário, retorna 412. Uma leitura pode incluir no máximo dois cabeçalhos condicionais, e a precedência deles segue a RFC 9110.

Gravações condicionais​

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

  • If-None-Match: * faz upload do arquivo apenas se nenhum arquivo existir no caminho. Caso contrário, a solicitação retornará 412 Precondition Failed.
  • If-Match: <etag> faz o upload do arquivo apenas se o seu ETag atual corresponder ao que você fornece. Caso contrário, a solicitação retornará 412 Precondition Failed ou 404 se nenhum arquivo existir no caminho.

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

HTTP
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 substituir um arquivo apenas se ele ainda for a versão que você buscou pela última vez, envie seu ETag com If-Match:

HTTP
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 de múltiplas partes, envie o cabeçalho condicional na chamada initiate-upload. A API de Arquivos o avalia quando o upload é concluído, portanto, a condição se aplica ao arquivo montado. Para os formulários de cabeçalho que cada chamada suporta, consulte Fazer upload de um arquivo e Executar uma ação em um arquivo.

Exclusões condicionais​

Um DELETE simples é bem-sucedido mesmo se o arquivo não existir, então ele não pode lhe dizer se você removeu a versão pretendida. Para tornar uma exclusão condicional, envie If-Match:

  • If-Match: <etag> exclui o arquivo somente se o ETag atual corresponder ao valor fornecido. Se alguém alterar o arquivo depois que você o buscar, a solicitação retornará 412 Precondition Failed. Se o arquivo não existir mais, retorna 404.
  • If-Match: * exclui o arquivo apenas se ele existir e retorna 404 se ele não existir.
HTTP
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Versões da API Files​

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

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

Nesta página