Use a API de Arquivos com volumes do Unity Catalog

Use a API Files para ler, escrever, listar e excluir arquivos e diretórios por caminho. Ele 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 vão para o hostname regional do seu workspace. Para cada operação, parâmetro e cabeçalho, veja a referência Files API 3.0.

O uso da API Files pode gerar cobranças de transferência de dados do Azure Databricks.

Enviar solicitações para o nome regional do host

Importante

Esse recurso está em Beta. Para usá-lo, um administrador de espaço de trabalho deve ativar Files API V3 with Large File Upload Support a partir da página Previews. Consulte Gerenciar visualizações do Azure Databricks.

Enviar solicitações da API de Arquivos 3.0 para o nome de host regional do workspace ao qual o usuário solicitante pertence. O nome de host regional apresenta o seguinte formato:

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

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

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

Configurar a conectividade de rede

Importante

Esse recurso está em Beta. Para usá-lo, um administrador de espaço de trabalho deve ativar Files API V3 with Large File Upload Support a partir da página Previews. Consulte Gerenciar visualizações do Azure Databricks.

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

Da sua rede para o Azure Databricks

Se você permitir acesso público à internet ao seu espaço de trabalho, 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 IPs do Plano de Controle, incluindo armazenamento padrão e webapp. Veja Tráfego de entrada para o plano de controle do Azure Databricks.

Se você não permitir acesso à internet ao Azure Databricks e se conectar por um link privado front-end, crie um segundo link privado front-end para serviços que exigem muito desempenho. Consulte Configurar o Link Privado de Entrada para serviços com uso intensivo de desempenho.

Do Azure Databricks para o seu armazenamento

Se você permitir acesso público ao seu armazenamento, mas aplicar restrições de rede, para armazenamento dentro da região, adicione suas contas de armazenamento a um Azure network security perimeter (NSP) e depois adicione a AzureDatabricksServerless tag de serviço à lista de permissões. O perímetro de segurança da rede deve permanecer em modo Transition. Caso contrário, adicione à lista de permissões os IPs de saída do Azure Databricks.

Se você não permitir acesso público ao seu armazenamento, configure um link privado para seu armazenamento do Azure. Consulte Configuração de conectividade privada para recursos do Azure.

Note

A cobrança de rede serverless se aplica. Consulte Noções básicas sobre os custos de rede do Databricks.

Envie arquivos grandes com upload multiparte

Importante

Esse recurso está em Beta. Para usá-lo, um administrador de espaço de trabalho deve ativar Files API V3 with Large File Upload Support a partir da página Previews. Consulte Gerenciar visualizações do Azure Databricks.

Uma única solicitação de upload aceita arquivos de até 5000 MiB. Para enviar um arquivo maior, ou um arquivo cujo tamanho é desconhecido quando o upload começa, use upload multiparte: você faz upload em partes, e o Azure Databricks o monta em um único arquivo.

Os números das peças variam de 1 a 10000. Toda parte, exceto a última, deve 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, veja Fazer upload de um arquivo e Execute uma ação em um arquivo.

Exemplo de upload multiparte

O exemplo a seguir faz upload de um arquivo 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 fazer upload da primeira parte, envie seu conteúdo com upload_id e part_number. A resposta inclui a ETagparte seguinte:

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 enviar a segunda parte, repita o pedido com a próxima 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 finalizar, complete o upload com um corpo que liste todas as partes e o que está armazenado em cada uma 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 ao arquivo completo, não a uma parte. Você pode usá-lo em requisições condicionais posteriores, por exemplo, para sobrescrever o arquivo somente se ele não tiver mudado desde que você o enviou.

Para cancelar o upload em vez de completá-lo, 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

Baixe arquivos grandes com requisições de intervalo

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

Solicite um intervalo

Envie o Range cabeçalho com as posições baseadas em zero do primeiro e último byte que você quer. O intervalo inclui ambas as posições. Por exemplo, bytes=0-1048575 solicita o primeiro 1 MiB de um arquivo 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 arquivo. Para ler até o final do arquivo, omita a última posição, como em bytes=1048576-. Se a última posição estiver além do final do arquivo, a resposta contém os bytes até o fim. Para outra sintaxe Range, veja Baixar um arquivo.

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

Retomar um download interrompido

Para retomar um download, solicite os bytes restantes com um intervalo que comece 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:

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 mudou, o servidor retorna 412 Precondition Failed, e você deve iniciar o download novamente.

Use solicitações condicionais

Importante

Esse recurso está em Beta. Para usá-lo, um administrador de espaço de trabalho deve ativar Files API V3 with Large File Upload Support a partir da página Previews. Consulte Gerenciar visualizações do Azure Databricks.

Uma solicitação condicional só entra em vigor se o arquivo estiver no estado que você espera. Use solicitações condicionais para evitar downloads repetidos, impedir que gravações simultâneas sobrescrevam as alterações umas das outras e criar ou excluir arquivos com segurança. A API de Arquivos 3.0 suporta os quatro cabeçalhos condicionais HTTP padrão do RFC 9110:

Cabeçalho Compara com Homenageado em
If-Match O ETag do arquivo Lê, escreve e exclui
If-None-Match O ETag do arquivo Lê e escreve
If-Modified-Since O tempo do Last-Modified arquivo Somente leitura
If-Unmodified-Since O tempo do Last-Modified arquivo Somente leitura

Quando a condição não é cumprida, o servidor não realiza 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

Cabeçalhos condicionais comparam um valor que você fornece com um dos validadores do arquivo. A API Files 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 multiparte complete-upload. Armazene-o exatamente como foi retornado, incluindo as aspas que o envolvem, e não o analise nem o construa.
  • Last-Modified: o tempo da última modificação do arquivo, como data HTTP. Sua precisão é de um segundo, então If-Modified-Since e If-Unmodified-Since não conseguem detectar várias mudanças no mesmo segundo. Para controle 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 em que você a buscou. Se o arquivo estiver inalterado, o servidor retorna 304 Not Modified sem corpo. Caso contrário, ele retorna 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 retorna o arquivo apenas se ele não tiver mudado, e caso contrário retorna 412. Uma leitura pode incluir, no máximo, dois cabeçalhos condicionais, e sua precedência segue o RFC 9110.

Gravações condicionais

Em PUT, use If-None-Match e If-Match para evitar sobrescrever mudanças que você não viu, também conhecido como problema da atualização perdida:

  • If-None-Match: * Carrega o arquivo somente se não houver nenhum arquivo no caminho. Caso contrário, a solicitação retorna 412 Precondition Failed.
  • If-Match: <etag> carrega o arquivo apenas se o ETag atual corresponder ao que você forneceu. Caso contrário, a solicitação retorna 412 Precondition Failed, ou 404 se não houver arquivo no caminho.

Para criar um arquivo somente 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 arquivo somente se ainda for a versão que você buscou pela última vez, envie 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 API de Files o avalia quando o upload é concluído, então a condição se aplica ao arquivo montado. Para os formulários de cabeçalho que cada chamada suporta, veja Enviar um arquivo e Executar uma ação sobre um arquivo.

Excluções condicionais

Um DELETE simples é bem-sucedido mesmo que o arquivo não exista, então não informa se você removeu a versão que pretendia. Para tornar a exclusão condicional, envie If-Match:

  • If-Match: <etag> exclui o arquivo apenas se seu ETag atual coincidir com o que você forneceu. Se alguém alterou o arquivo depois que você o buscou, a solicitação retorna 412 Precondition Failed. Se o arquivo não existir mais, ele retorna 404.
  • If-Match: * exclui o arquivo apenas se ele existir e retorna 404 caso ele não exista.
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Versões da API de arquivos

A API de Arquivos 2.0 envia requisições para o nome de host do seu workspace com o prefixo de endpoint /api/2.0/fs. Ele não suporta upload multiparte, e seu único cabeçalho condicional é If-Unmodified-Since para downloads. Veja a referência da API de Arquivos 2.0.

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