Usar solicitações condicionais

info

Beta

Esse recurso está na versão 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.

As solicitações condicionais permitem que você faça uma operação depender do estado atual do arquivo de destino, para que a solicitação só entre em vigor se o arquivo estiver no estado esperado. Isso permite que você evite transferências desperdiçadas, impeça atualizações perdidas de escritores concorrentes e crie ou exclua arquivos com segurança.

A API de Arquivos 3.0 é compatível com os quatro cabeçalhos condicionais HTTP padrão do RFC 9110.

cabeçalho	Compara com	Homenageado em
If-Match	Do arquivo ETag	Ler, gravar e excluir
If-None-Match	Do arquivo ETag	Leituras e gravações
If-Modified-Since	O Last-Modified tempo do arquivo	Leituras apenas
If-Unmodified-Since	O Last-Modified tempo do arquivo	Leituras apenas

cabeçalho	Compara com	Homenageado em
If-Match	Do arquivo ETag	Ler, gravar e excluir
If-None-Match	Do arquivo ETag	Leituras e gravações
If-Modified-Since	O Last-Modified tempo do arquivo	Leituras apenas
If-Unmodified-Since	O Last-Modified tempo do arquivo	Leituras apenas

If-Modified-Since e If-Unmodified-Since se aplicam apenas a operações de leitura (GET e HEAD). Não há suporte para eles no upload ou exclusão.

Quando a condição não é atendida, 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. Isso confirma que sua cópia em cache ainda é válida, portanto não há necessidade de enviar o arquivo novamente.
• 412 Precondition Failed, quando qualquer outra condição falha. A leitura, o upload ou a exclusão não são executados.

Validadores: ETag e Last-Modified

Uma solicitação condicional compara um validador fornecido por você com o validador atual do arquivo. A Files API retorna os dois validadores como cabeçalhos de resposta para que você possa capturá-los e usá-los em uma solicitação posterior:

• ETag: um identificador opaco para o conteúdo atual do arquivo. Armazene o valor exato que o servidor retornou, incluindo as aspas ao redor, e envie-o de volta sem alterações. Não analise nem construa.
• Last-Modified: a hora da última modificação do arquivo, como uma data HTTP.

Ambos os validadores são retornados em respostas GET e HEAD. ETag também é retornado em PUT e na resposta complete-upload multipart.

Last-Modified tem uma precisão de um segundo. If-Modified-Since e If-Unmodified-Since não conseguem detectar várias alterações feitas no mesmo segundo, portanto, não dependa deles para um controle de concorrência preciso. Use ETag com If-Match ou If-None-Match em vez disso.

Leituras condicionais

No GET e no HEAD, todos os quatro cabeçalhos condicionais são honrados. O uso mais comum é a revalidação de cache : você tem uma cópia download anteriormente e deseja que o servidor envie os bytes novamente apenas se eles tiverem mudado.

Envie If-None-Match com o ETag da sua cópia em cache, ou If-Modified-Since com a hora em que você o buscou pela última vez. Se o arquivo não foi alterado, o servidor retorna 304 Not Modified sem corpo e você continua usando sua cópia armazenada em cache. Se ele mudou, o servidor retorna 200 OK com o novo conteúdo.

Para revalidar um arquivo em cache, envie seu ETag e download o corpo somente se o arquivo tiver sido alterado:

HTTP

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

304 Not Modified

Os outros dois cabeçalhos de leitura afirmam a condição oposta. If-Match retorna o arquivo apenas se seu ETag ainda corresponder; caso contrário, retorna 412. If-Unmodified-Since retorna o arquivo apenas se ele não tiver sido alterado desde o momento fornecido; caso contrário, retorna 412.

Você pode enviar no máximo dois cabeçalhos condicionais em uma leitura. Solicitações com mais não são compatíveis. Quando você envia dois, sua prioridade segue a RFC 9110.

Gravações condicionais

No PUT, você pode usar If-None-Match e If-Match para proteger um upload em relação ao estado atual do arquivo:

• If-None-Match: * salva o arquivo apenas se ele ainda não existir. Isso garante que o upload não sobrescreva acidentalmente outro upload e perca seus dados, o que é uma variação do problema de atualização perdida. Se um arquivo já existe no caminho, a solicitação retorna 412 Precondition Failed.
• If-Match: <etag> impede o problema de perda de atualização. Ele verifica se o upload não substituirá outra alteração feita desde que você buscou o arquivo. O upload só terá êxito se o ETag atual do arquivo corresponder ao que você forneceu. Caso contrário, a solicitação retorna 412 Precondition Failed. Se nenhum arquivo existir no caminho, a solicitação retorna 404.

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 sobrescrever 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

As seguintes formas não são suportadas em PUT: uma lista de ETags, If-Match: *, If-None-Match com um ETag específico, If-Modified-Since e If-Unmodified-Since.

Para um upload de várias partes, envie o cabeçalho condicional na chamada initiate-upload. A API de arquivos o armazena e avalia quando o upload é concluído, portanto, a condição se aplica ao arquivo montado final. Você pode usar os mesmos dois cabeçalhos que em PUT: If-None-Match: * e If-Match: <etag>. Não há suporte para cabeçalhos condicionais na própria chamada complete-upload ou abort-upload.

Exclusões condicionais

DELETE é idempotente. A exclusão de um arquivo que não existe ainda retorna 204 No Content. Isso torna a limpeza simples, mas um DELETE simples não pode 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 seu ETag atual corresponder ao que você forneceu. Se outro usuário modificou o arquivo depois que você o buscou, a solicitação retornará 412 Precondition Failed em vez de remover a alteração dele. Se o arquivo não existir mais, a solicitação retornará 404.
• If-Match: * exclui o arquivo somente se ele existir. A solicitação retorna 204 se o arquivo existia e 404 se não existia.

HTTP

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

204 No Content

Os cabeçalhos condicionais restantes (If-None-Match, If-Modified-Since e If-Unmodified-Since) não são suportados em DELETE.