Utilisez la Files API avec les volumes du catalogue Unity

Utilisez Files API pour lire, écrire, lister et supprimer des fichiers et répertoires par chemin. Il fonctionne avec les fichiers dans les volumes Unity Catalog, auxquels vous faites référence par leur chemin de volume absolu, comme /Volumes/<catalog>/<schema>/<volume>/<path>. Les requêtes de l’API Files 3.0 utilisent le préfixe /api/3.0/fs du point de terminaison et vont au nom d’hôte régional de votre espace de travail. Pour chaque opération, paramètre et en-tête, voir la référence Files API 3.0.

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

Envoyer les requêtes au nom d’hôte régional

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer Files API V3 with Large File Upload Support depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Envoyez les requêtes API Send Files 3.0 au nom d’hôte régional de l’espace de travail auquel appartient l’utilisateur demandeur. Le nom d’hôte régional suit le format suivant :

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

Par exemple : 1234567890123456.storage.westus.azuredatabricks.net.

Pour trouver l’identifiant et la région de votre espace de travail, utilisez la console de compte. Consultez Noms d’instance, URL et ID d’espace de travail. Vous pouvez également trouver l’ID de l’espace de travail dans l’URL de déploiement : dans https://<databricks-instance>/?o=1234567890123456, le numéro suivant o= est l’ID de l’espace de travail. L’interface de l’espace de travail affiche la région sous le nom de l’espace de travail.

Configurer la connectivité réseau

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer Files API V3 with Large File Upload Support depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Files API 3.0 nécessite une connectivité réseau de votre réseau à Azure Databricks et d’Azure Databricks à votre stockage.

De votre réseau à Azure Databricks

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

Incluez les IP sous les IP du plan de contrôle, y compris le stockage par défaut et l’application web. Voir Trafic entrant vers le plan de contrôle Azure Databricks.

Si vous n'autorisez pas l'accès à Internet à Azure Databricks et que vous vous connectez via un lien privé front-end, créez un second lien privé front-end pour des services gourmands en performance. Consultez Configurer les Private Link entrants pour les services gourmands en performances.

De Azure Databricks vers votre stockage

Si vous autorisez l'accès public à votre stockage, mais appliquez des restrictions réseau, pour le stockage situé dans la même région, ajoutez vos comptes de stockage à un périmètre de sécurité réseau (NSP) Azure, puis ajoutez à la liste d'autorisation la balise de service AzureDatabricksServerless. Le périmètre de sécurité réseau doit rester en mode transition. Sinon, ajoutez les IP sortantes d’Azure Databricks à la liste d’autorisation.

Si vous n'autorisez pas l'accès public à votre stockage, configurez un lien privé vers votre stockage Azure. Consultez Configurer la connectivité privée aux ressources Azure.

Note

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

Charger des fichiers volumineux à l’aide du chargement multipartite

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer Files API V3 with Large File Upload Support depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Une seule requête de téléversement accepte des fichiers jusqu’à 5000 Mio. Pour téléverser un fichier plus volumineux, ou un fichier dont la taille est inconnue au début du téléversement, utilisez le téléversement multipartie : vous téléversez le fichier en parties, et Azure Databricks les assemble en un seul fichier.

Les numéros de pièce vont de 1 à 10 000. Chaque partie sauf la dernière doit faire au moins 5 Mio, et chaque partie peut atteindre au maximum 4000 Mio. Azure Databricks assemble les pièces dans un ordre croissant par numéros de pièce. Pour chaque paramètre, voir Téléverser un fichier et Exécuter une action sur un fichier.

Exemple de téléversement en plusieurs parties

L’exemple suivant téléverse un fichier en deux parties.

Pour lancer la session de téléversement, lancez le téléversement. La réponse contient le upload_id qui identifie la session :

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

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

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

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 charger la deuxième partie, répétez la requête avec le part_number suivant :

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 terminer, finalisez le chargement en fournissant un corps de requête qui répertorie chaque partie et son ETag stocké :

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é, pas à une partie. Vous pouvez l’utiliser dans les requêtes conditionnelles ultérieures, par exemple pour écraser le fichier seulement s’il n’a pas changé depuis que vous l’avez téléversé.

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

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

200 OK

Télécharger de gros fichiers avec des requêtes par plage

Utilisez les requêtes par plage pour télécharger un fichier volumineux dans plusieurs petites requêtes, ou pour reprendre un téléchargement interrompu.

Demander une plage

Envoyez l’en-tête Range avec les positions indexées à partir de zéro des premier et dernier octets que vous souhaitez. La plage inclut les deux positions. Par exemple, bytes=0-1048575 demande le premier 1 Mio d’un fichier de 10 Mio :

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 206 Partial Content réponse ne contient que les octets demandés, et Content-Range indique quels octets elle contient ainsi que la taille totale du fichier. Pour lire jusqu’à la fin du fichier, omettez la position finale, comme dans bytes=1048576-. Si la dernière position est au-delà de la fin du fichier, la réponse contient les octets jusqu’à la fin. Pour connaître les autres syntaxes de Range, consultez Télécharger un fichier.

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

Reprendre un téléchargement interrompu

Pour reprendre un téléchargement, demandez les octets restants en spécifiant une plage commençant au premier octet que vous n’avez pas encore reçu. Envoyez If-Match aussi avec le ETag depuis votre première réponse, pour ne pas combiner des octets provenant de deux versions du fichier :

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 renvoie 412 Precondition Failed, et vous devez relancer le téléchargement.

Utiliser des requêtes conditionnelles

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer Files API V3 with Large File Upload Support depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Une requête conditionnelle n’entre en vigueur que si le fichier est dans l’état que vous attendez. Utilisez des requêtes conditionnelles pour éviter les téléchargements répétés, empêcher les rédacteurs concurrents d’écraser les modifications des uns et des autres, et créer ou supprimer des fichiers en toute sécurité. L’API des fichiers 3.0 prend en charge les quatre en-têtes conditionnels HTTP standards de la RFC 9110 :

Header Compare avec Honoré le
If-Match Le ETag du fichier Lit, écrit et supprime
If-None-Match Le ETag du fichier Lit et écrit
If-Modified-Since L’heure du Last-Modified dossier Lecture seule
If-Unmodified-Since L'heure Last-Modified du fichier Lecture seule

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. Votre copie mise 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 Fichiers renvoie 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é dans PUT et la réponse multipartite complete-upload. Conservez-le exactement tel qu’il a été renvoyé, y compris les guillemets qui l’entourent, et ne l’analysez pas et ne le reconstituez pas.
  • Last-Modified: le dernier temps de modification du fichier, sous forme de date HTTP. Sa précision est d’une seconde, donc If-Modified-Since et If-Unmodified-Since ne peuvent pas détecter plusieurs changements dans la même seconde. Pour le contrôle de la 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 la 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 reste inchangé, le serveur renvoie 304 Not Modified sans corps. Sinon, il renvoie 200 OK avec le nouveau contenu :

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 ne renvoie le fichier que s’il n’a pas changé, et sinon retourne 412. Une lecture peut inclure au maximum deux en-têtes conditionnels, et leur préséance suit la 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, aussi appelé problème de mise à jour perdue :

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

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

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

Pour un chargement en plusieurs parties, envoyez l'en-tête conditionnel lors de l'appel initiate-upload. L’API Fichiers l’évalue lorsque le téléchargement est terminé, donc la condition s’applique au fichier assemblé. Pour les formulaires d’en-tête pris en charge par chaque appel, voir Télécharger un fichier et Exécuter une action sur un fichier.

Suppressions conditionnelles

Une requête DELETE simple réussit même si le fichier n’existe pas. Elle ne permet donc pas de savoir si vous avez supprimé la version souhaitée. Pour rendre la 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’ayez récupéré, la requête renvoie 412 Precondition Failed. Si le fichier n’existe plus, il retourne 404.
  • If-Match: * supprime le fichier uniquement s’il existe et renvoie 404 dans le cas contraire.
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Versions de l’API Files

L’API Fichiers 2.0 envoie des requêtes à votre nom d’hôte d’espace de travail avec le préfixe de point de terminaison /api/2.0/fs. Il ne prend pas en charge le téléversement multipart, et son seul en-tête conditionnel est If-Unmodified-Since lors des téléchargements. Voir la référence Files API 2.0.

Pour transférer du code de l’API Files 2.0 vers la 3.0, effectuez les modifications suivantes :

  • Dernière mise à jour :