Utiliser l’API Files avec des volumes Unity Catalog

Utilisez l’API Files pour lire, écrire, répertorier et supprimer des fichiers et des répertoires par chemin. Cela fonctionne avec des fichiers dans des volumes Unity Catalog, auxquels vous faites référence par leur chemin de volume absolu, tel que /Volumes/<catalog>/<schema>/<volume>/<path>. Les requêtes de l’API Files 3.0 utilisent le préfixe d’endpoint /api/3.0/fs et sont envoyées au hostname régional de votre workspace. Pour chaque opération, parameter et en-tête, consultez la référence de l’API Files 3.0.

L’utilisation de l’API Files peut entraîner des frais de transfert de données Databricks.

Envoyer des requêtes à l’hostname régional

info

Bêta

Cette fonctionnalité est en 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.

Envoyez les demandes de l’API Files 3.0 à l’hostname régional du workspace auquel appartient l’utilisateur qui fait la demande. Le hostname régional a le format suivant :

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

Par exemple, 1234567890123456.storage.us-west-2.cloud.databricks.com.

Pour trouver votre ID de workspace et votre région, utilisez la console de compte. Voir Noms d'instance, URL et ID de workspace. Vous pouvez également trouver l’ID de workspace dans l’URL de déploiement : dans https://<databricks-instance>/?o=1234567890123456, le nombre après o= est l’ID de workspace. L'interface utilisateur du workspace indique la région sous le nom du workspace.

Configurer la connectivité réseau

info

Bêta

Cette fonctionnalité est en 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.

Files API 3.0 nécessite une connectivité réseau de votre réseau vers Databricks et de Databricks vers votre stockage.

Depuis votre réseau vers Databricks

Si vous autorisez l’accès internet public à votre workspace mais que vous le restreignez avec un pare-feu, ajoutez les plages d’adresses IP du plan de contrôle de votre région à la liste d’autorisation.

Incluez les IP sous Default storage, OpenSharing SecureConnect, Zerobus Ingestion et Lakebase Autoscaling. Voir Adresses IP entrantes.

Si vous n’autorisez pas l’accès à Internet vers Databricks et que vous vous connectez via un Link privé frontal, créez un second Link privé frontal pour les services exigeants en termes de performances. Voir Configurer PrivateLink entrant pour les services exigeants en termes de performances.

De Databricks vers votre stockage

Si vous autorisez l’accès public à votre stockage, mais que vous appliquez des restrictions réseau pour le stockage intra-région, ajoutez le Databricks serverless OrgPath à la liste d’autorisation. Sinon, ajoutez les adresses IP sortantes Databricks à la liste d’autorisation.

Si vous n’autorisez pas l’accès public à votre stockage, créez un Link privé vers Amazon S3. Voir Configurer la connectivité privée vers des ressources gérées par AWS.

remarque

La facturation du réseau serverless s’applique. Voir Comprendre les coûts réseau de Databricks.

Upload de fichiers volumineux avec l’upload multipart

info

Bêta

Cette fonctionnalité est en 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.

Une seule demande d’upload accepte des fichiers jusqu’à 5000 MiB. Pour upload un fichier plus volumineux ou un fichier dont la taille est inconnue au start de l’upload, utilisez l’upload multipart : vous upload le fichier en plusieurs parties et Databricks les assemble en un seul fichier.

Les numéros de partie vont de 1 à 10 000. Toutes les parties sauf la dernière doivent être d’au moins 5 Mio, et chaque partie peut être d’au plus 4000 Mio. Databricks assemble les parties dans l’ordre croissant des numéros de partie. Pour chaque parameter, consultez Upload un fichier et Effectuer une action sur un fichier.

Exemple d’upload en plusieurs parties

L’exemple suivant effectue l’upload d’un fichier en deux parties.

Pour start la session d’upload, lancez l’upload. La réponse contient le upload_id qui identifie la session :

HTTP

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

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

Pour upload la première partie, envoyez son contenu avec le upload_id et part_number. La réponse inclut le ETag de la partie :

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"

Pour upload la seconde partie, répétez la demande avec le part_number suivant :

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"

Pour finir, complétez l’upload avec un corps qui liste chaque partie et son ETag stocké :

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"

Le ETag dans cette réponse appartient à l’ensemble du fichier assemblé, et non à une partie. Vous pouvez l’utiliser dans des requêtes conditionnelles ultérieures, par exemple pour écraser le fichier uniquement s’il n’a pas été modifié depuis son upload.

Pour annuler l’upload au lieu de le terminer, envoyez l’action abort-upload avec upload_id:

HTTP

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

200 OK

Download des fichiers volumineux avec des requêtes de plage

Utilisez des requêtes de plage pour download un fichier volumineux en plusieurs requêtes plus petites, ou pour reprendre un download interrompu.

Demander une plage

Envoyez l’en-tête Range avec les positions basées sur zéro du premier et du dernier octet souhaités. La plage inclut les deux positions. Par exemple, bytes=0-1048575 demande les 1 Mio de données d’un fichier de 10 Mio :

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>

La réponse 206 Partial Content ne contient que les octets demandés, et Content-Range indique les octets qu’elle contient et la taille totale du fichier. Pour lire jusqu’à la fin du fichier, omettez la dernière position, comme dans bytes=1048576-. Si la dernière position est située après la fin du fichier, la réponse contient les octets jusqu’à la fin. Pour toute autre syntaxe Range, consultez Download d’un fichier.

Une demande HEAD avec un en-tête Range retourne le même statut et les mêmes en-têtes que la demande GET correspondante, sans le corps.

Reprendre un download interrompu

Pour reprendre un download, demandez les octets restants avec une plage qui start au premier octet que vous n’avez pas reçu. Envoyez également If-Match avec le ETag de votre première réponse, pour ne pas combiner les octets de deux versions du fichier :

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>

Si le fichier a changé, le serveur retourne 412 Precondition Failed, et vous devez start le download à nouveau.

Utiliser des requêtes conditionnelles

info

Bêta

Cette fonctionnalité est en 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.

Une requête conditionnelle n’a d’effet que si le fichier est dans l’état attendu. Utilisez des requêtes conditionnelles pour éviter les download répétés, empêcher les rédacteurs simultanés d’écraser les modifications des autres et créer ou supprimer des fichiers en toute sécurité. Files API 3.0 prend en charge les quatre en-têtes conditionnels HTTP standard de RFC 9110:

En-tête	Compare avec	Honoré le
If-Match	Le fichier ETag	Lit, écrit et supprime
If-None-Match	Le fichier ETag	Lit et écrit
If-Modified-Since	La date Last-Modified du fichier	Lit uniquement
If-Unmodified-Since	La date Last-Modified du fichier	Lit uniquement

En-tête	Compare avec	Honoré le
If-Match	Le fichier ETag	Lit, écrit et supprime
If-None-Match	Le fichier ETag	Lit et écrit
If-Modified-Since	La date Last-Modified du fichier	Lit uniquement
If-Unmodified-Since	La date Last-Modified du fichier	Lit uniquement

Quand la condition n’est pas remplie, le serveur n’effectue pas l’opération et retourne l’un des statuts suivants :

• 304 Not Modified, lorsqu’une requête GET ou HEAD avec If-None-Match ou If-Modified-Since échoue. Votre copie en cache est toujours valide.
• 412 Precondition Failed, lorsque toute autre condition échoue.

Validateurs : ETag et Last-Modified

Les en-têtes conditionnels comparent une valeur que vous fournissez avec l’un des validateurs du fichier. L’API Files retourne les deux validateurs comme en-têtes de réponse sur GET et HEAD:

• ETag: un identifiant opaque pour le contenu du fichier, également renvoyé sur PUT et la réponse multipart complete-upload. Stockez-le exactement tel qu’il est renvoyé, y compris les guillemets environnants, et ne l’analysez pas et ne le construisez pas.
• Last-Modified: la dernière heure de modification du fichier, en tant qu’ HTTP-date. Sa précision est d’une seconde, ainsi If-Modified-Since et If-Unmodified-Since ne peuvent pas détecter plusieurs changements dans la même seconde. Pour le contrôle de concurrence, utilisez ETag avec If-Match ou If-None-Match.

Lectures conditionnelles

La lecture conditionnelle la plus courante est la revalidation du cache. 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. Dans le cas contraire, il renvoie 200 OK avec le nouveau contenu :

HTTP

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

304 Not Modified

If-Match et If-Unmodified-Since fonctionnent dans l’autre sens : le serveur retourne le fichier uniquement s’il n’a pas changé, et autrement retourne 412. Une lecture peut inclure au plus deux en-têtes conditionnels, et leur priorité suit RFC 9110.

Écritures conditionnelles

Sur PUT, utilisez If-None-Match et If-Match pour éviter d’écraser des modifications que vous n’avez pas vues, ce qu’on appelle également le problème de mise à jour perdue:

• If-None-Match: * upload le fichier uniquement si aucun fichier n’existe au chemin d’accès. Sinon, la requête renvoie 412 Precondition Failed.
• If-Match: <etag> upload le fichier uniquement si son ETag actuel correspond à celui que vous fournissez. Sinon, la requête renvoie 412 Precondition Failed ou 404 si aucun fichier n’existe au chemin spécifié.

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 remplacer un fichier uniquement s’il s’agit encore de 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

Pour un multipart upload, envoyez l’en-tête conditionnel lors de l’appel initiate-upload. L’API Files l’évalue une fois l’upload terminé, la condition s’applique donc au fichier assemblé. Pour les formulaires d’en-tête pris en charge par chaque appel, consultez Upload un fichier et Effectuer une action sur un fichier.

Suppressions conditionnelles

Un DELETE simple réussit même si le fichier n’existe pas, il ne peut donc pas vous dire si vous avez supprimé la version prévue. 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 quelqu’un a modifié le fichier après que vous l’avez récupéré, la demande retourne 412 Precondition Failed. Si le fichier n’existe plus, elle retourne 404.
• If-Match: * supprime le fichier uniquement s’il existe et renvoie 404 si ce n’est pas le cas.

HTTP

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

204 No Content

Versions de l’API Files

Files API 2.0 envoie des requêtes à votre hostname de workspace avec le préfixe d’endpoint /api/2.0/fs. Elle ne prend pas en charge l’upload partitionné et son seul en-tête conditionnel est If-Unmodified-Since sur les download. Voir la référence de Files API 2.0.

Pour migrer du code de l’API Files 2.0 vers 3.0, effectuez les modifications suivantes :

• Envoyez des requêtes au hostname régional avec le préfixe d’endpoint /api/3.0/fs, et configurez la connectivité réseau.
• Envoyez l’en-tête Content-Length lors de chaque upload. Si vous ne connaissez pas la taille du fichier à l’avance, utilisez multipart upload.
• Attendez-vous à 200 OK au lieu de 204 No Content pour un upload réussi.
• Attendez-vous à 204 No Content, pas 404 Not Found, quand vous supprimez un fichier qui n’existe pas. Voir Suppressions conditionnelles.