Utiliser des demandes conditionnelles

info

Bêta

Cette fonctionnalité est en version bêta. Pour l'utiliser, un administrateur de workspace doit activer Files API V3 with Large File Upload Support depuis la page Previews . Consultez Gérer les aperçus Databricks.

Les demandes conditionnelles vous permettent de faire dépendre une opération de l'état actuel du fichier cible, de sorte que la demande ne prenne effet que si le fichier est dans l'état que vous attendez. Cela vous permet d'éviter les transferts inutiles, d'empêcher les mises à jour perdues provenant d'auteurs concurrents et de créer ou de supprimer des fichiers en toute sécurité.

L'API Files 3.0 prend en charge les quatre en-têtes conditionnels HTTP standard de la RFC 9110.

En-tête	Compare à	Récompensé le
If-Match	Du fichier ETag	Lit, écrit et supprime
If-None-Match	Du fichier ETag	Lectures et écritures
If-Modified-Since	Le Last-Modified du fichier	Lire uniquement
If-Unmodified-Since	Le Last-Modified du fichier	Lire uniquement

En-tête	Compare à	Récompensé le
If-Match	Du fichier ETag	Lit, écrit et supprime
If-None-Match	Du fichier ETag	Lectures et écritures
If-Modified-Since	Le Last-Modified du fichier	Lire uniquement
If-Unmodified-Since	Le Last-Modified du fichier	Lire uniquement

If-Modified-Since et If-Unmodified-Since s'appliquent uniquement aux opérations de lecture (GET et HEAD). Ils ne sont pas pris en charge lors de l'upload ou de la suppression.

Lorsque la condition n'est pas remplie, le serveur n'effectue pas l'opération et renvoie l'un des statuts suivants :

• 304 Not Modified, lorsqu'une requête GET ou HEAD avec If-None-Match ou If-Modified-Since échoue. Elle confirme que votre copie en cache est toujours valide, donc il n’est pas nécessaire d’envoyer le fichier à nouveau.
• 412 Precondition Failed, lorsque toute autre condition échoue. La lecture, le upload ou la suppression n’est pas effectué.

Validateurs : ETag et Last-Modified

Une requête conditionnelle compare un validateur que vous fournissez au validateur actuel du fichier. L'API Files renvoie les deux validateurs sous forme d'en-têtes de réponse. Vous pouvez donc les capturer et les utiliser dans une requête ultérieure :

• ETag: un identifiant opaque pour le contenu actuel du fichier. Stockez la valeur exacte renvoyée par le serveur, y compris les guillemets qui l’entourent, et renvoyez-la sans modification. Ne pas l’analyser ou le construire.
• Last-Modified: date de dernière modification du fichier, au format HTTP-date.

Les deux validateurs sont renvoyés sur les réponses GET et HEAD. ETag est également renvoyé sur PUT et la réponse multipart complete-upload.

Last-Modified a une précision d'une seconde. If-Modified-Since et If-Unmodified-Since ne peuvent pas détecter plusieurs changements effectués dans la même seconde, donc ne vous fiez pas à eux pour un contrôle précis de la concurrence. Utilisez plutôt ETag avec If-Match ou If-None-Match.

Lectures conditionnelles

Sur GET et HEAD, les quatre en-têtes conditionnels sont respectés. L'utilisation la plus courante est la revalidation du cache : vous avez une copie précédemment download et vous voulez que le serveur renvoie les octets uniquement s'ils ont été modifiés.

Envoyez If-None-Match avec le ETag de votre copie mise en cache, ou If-Modified-Since avec l'heure à laquelle vous l'avez récupérée pour la dernière fois. Si le fichier n'est pas modifié, le serveur renvoie 304 Not Modified sans corps et vous continuez à utiliser votre copie mise en cache. S'il a été modifié, le serveur renvoie 200 OK avec le nouveau contenu.

Pour revalider un fichier mis en cache, envoyez son ETag et download le corps uniquement si le fichier a changé :

HTTP

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

304 Not Modified

Les deux autres en-têtes de lecture affirment la condition opposée. If-Match renvoie le fichier uniquement si son ETag correspond toujours, sinon il renvoie 412. If-Unmodified-Since ne la renvoie que si le fichier n'a pas changé depuis l'heure indiquée, et renvoie sinon 412.

Vous pouvez envoyer au plus deux en-têtes conditionnels lors d'une lecture. Les demandes avec plus ne sont pas prises en charge. Lorsque vous en envoyez deux, leur priorité suit la RFC 9110.

Écritures conditionnelles

Sur PUT, vous pouvez utiliser If-None-Match et If-Match pour protéger un upload contre l'état actuel du fichier :

• If-None-Match: * enregistre le fichier uniquement s'il n'existe pas déjà. Cela garantit que l'upload ne va pas accidentellement écraser un autre upload et perdre ses données, ce qui est une variante du problème de mise à jour perdue. Si un fichier existe déjà au niveau du chemin d'accès, la requête renvoie 412 Precondition Failed.
• If-Match: <etag> empêche le problème de mise à jour perdue. Il vérifie que l’upload n’écrasera pas une autre modification effectuée depuis que vous avez récupéré le fichier. L’upload réussit uniquement si le ETag actuel du fichier correspond à celui que vous fournissez. Sinon, la demande renvoie 412 Precondition Failed. Si aucun fichier n’existe sur le chemin d’accès, la demande renvoie 404.

Pour créer un fichier uniquement s'il n'existe pas déjà, envoyez 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

Pour écraser un fichier seulement s'il correspond toujours à la version que vous avez récupérée en dernier, envoyez son ETag avec 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

Les formes suivantes ne sont pas prises en charge sur PUT: une liste de ETag, If-Match: *, If-None-Match avec un ETag spécifique, If-Modified-Since et If-Unmodified-Since.

Pour un upload multipart, envoyez l'en-tête conditionnel lors de l'appel initiate-upload. L'API Files la stocke et l'évalue une fois l'upload terminé, de sorte que la condition s'applique au fichier final assemblé. Vous pouvez utiliser les deux mêmes en-têtes que sur PUT: If-None-Match: * et If-Match: <etag>. Les en-têtes conditionnels lors de l'appel complete-upload ou abort-upload lui-même ne sont pas pris en charge.

Suppressions conditionnelles

DELETE est idempotent. La suppression d'un fichier qui n'existe pas renvoie tout de même 204 No Content. Cela simplifie le nettoyage, mais un DELETE simple ne peut pas vous dire si vous avez supprimé la version que vous souhaitiez. Pour rendre une suppression conditionnelle, envoyez If-Match:

• If-Match: <etag> supprime le fichier uniquement si son ETag actuel correspond à celui que vous fournissez. Si un autre utilisateur a modifié le fichier après que vous l'avez récupéré, la requête renvoie 412 Precondition Failed au lieu de supprimer sa modification. Si le fichier n'existe plus, la requête renvoie 404.
• If-Match: * supprime le fichier uniquement s'il existe. La requête renvoie 204 si le fichier existait et 404 s'il n'existait pas.

HTTP

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

204 No Content

Les en-têtes conditionnels restants (If-None-Match, If-Modified-Since et If-Unmodified-Since) ne sont pas pris en charge sur DELETE.