Utiliser l’API Files

Utilisez l’API Files pour lire, écrire, répertorier et supprimer des fichiers et des répertoires par chemin. Il fonctionne avec des fichiers dans les 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 Files API 3.0 utilisent le préfixe d’endpoint /api/3.0/fs et vont vers le hostname régional de votre workspace. Pour chaque opération, parameter et en-tête, consultez la documentation de l’API Files 3.0.

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.

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

Envoyer les requêtes vers le hostname régional

Envoyez les demandes de Send Files API 3.0 au hostname régional du workspace auquel appartient l’utilisateur demandeur. Le hostname régional est au 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 de workspace, URL et ID. 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 affiche la région sous le nom du workspace.

Configurer la connectivité réseau

La version 3.0 de l’API Files nécessite une connectivité réseau entre votre réseau et Databricks, ainsi qu’entre Databricks et votre stockage.

De votre réseau à Databricks

Si vous autorisez l'accès internet public à votre workspace mais le restreignez avec un pare-feu, mettez sur liste blanche les plages IP du plan de contrôle pour votre région.

Incluez les adresses IP sous Stockage default, OpenSharing SecureConnect, Ingestion Zerobus et Mise à l’échelle automatique de Lakebase. Voir Adresses IP entrantes.

Si vous n’autorisez pas l’accès à Internet vers Databricks et que vous vous connectez via un private link frontal, créez un second private link frontal pour les services gourmands en ressources. Voir Configurer un PrivateLink entrant pour les services gourmands en ressources.

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 en région, ajoutez le Databricks serverless OrgPath à la liste d’autorisation. Sinon, ajoutez les adresses IP sortantes de 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 aux ressources gérées par AWS.

remarque

La facturation réseau Serverless s’applique. Consultez Comprendre les coûts réseau de Databricks.

Upload des fichiers volumineux

Une demande d'upload unique accepte des fichiers jusqu'à 5000 Mio. Pour uploader un fichier plus volumineux ou un fichier dont la taille est inconnue au début de l'upload, utilisez un upload multi-parties Files API 3.0 : start une session avec l'action initiate-upload, uploadez chaque partie avec PUT, puis assemblez les parties avec l'action complete-upload. Pour les limites des parties et les détails de la demande, voir upload un fichier et Effectuer une action sur un fichier.

Reprendre un download interrompu

Pour reprendre un download interrompu, demandez les octets restants avec un header Range qui start au premier octet que vous n’avez pas reçu. Pour vous assurer que le fichier n’a pas changé entre les requêtes, envoyez également If-Match avec le ETag de votre première réponse :

HTTP

GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=1048576-
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

206 Partial Content
Content-Range: bytes 1048576-10485759/10485760
<binary data>

Si le fichier a changé, le serveur retourne 412 Precondition Failed, et vous devez start le download. La combinaison d’octets de différentes versions d’un fichier corrompt le résultat. Pour la syntaxe d’en-tête Range, voir Download a file.

Requêtes conditionnelles

Utilisez les en-têtes conditionnels pour exécuter une requête uniquement lorsque la valeur ETag ou Last-Modified actuelle du fichier remplit une condition que vous avez définie. Pour les en-têtes pris en charge par chaque opération, consultez la référence de l'API Files 3.0. Lorsque vous les utilisez, notez ce qui suit :

• Stockez le ETag exactement tel que le serveur le retourne, y compris les guillemets environnants, et renvoyez-le tel quel. N’analysez pas et ne construisez pas de ETag.
• Last-Modified a une précision d’une seconde ; If-Modified-Since et If-Unmodified-Since ne peuvent donc pas détecter plusieurs modifications au cours de la même seconde. Pour éviter que des rédacteurs simultanés ne remplacent les modifications des uns et des autres, utilisez If-Match ou If-None-Match.
• Une demande de lecture peut inclure au plus deux en-têtes conditionnels. Lorsque vous en envoyez deux, leur priorité suit la norme RFC 9110.

Versions de l’API Files

Les API Files 2.0 envoient des requêtes au hostname de votre workspace avec le préfixe d’endpoint /api/2.0/fs. Il ne prend pas en charge l’upload en plusieurs parties, et son seul en-tête conditionnel est If-Unmodified-Since lors des download. Voir la référence des API Files 2.0.

Pour déplacer le code de l'API Files 2.0 vers la version 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.
• Envoyer l'en-tête Content-Length à chaque upload. Si vous ne connaissez pas la taille du fichier à l'avance, utilisez l'upload multipart.
• Attendez-vous à 200 OK au lieu de 204 No Content suite à un upload réussi.
• Attendez-vous à 204 No Content lorsque vous supprimez un fichier qui n’existe pas. Pour obtenir 404 Not Found à la place, comme dans l’API Files 2.0, envoyez If-Match: *.