Utiliza la API de Archivos con los volúmenes del Catálogo de Unity

Utiliza la API de Archivos para leer, escribir, listar y eliminar archivos y directorios por ruta. Funciona con archivos en volúmenes del Catálogo de Unity, a los que te refieres por su ruta absoluta del volumen, como /Volumes/<catalog>/<schema>/<volume>/<path>. Las solicitudes de la API de archivos 3.0 utilizan el prefijo del endpoint /api/3.0/fs y van al nombre de host regional de tu espacio de trabajo. Para cada operación, parámetro y cabecera, consulte la referencia API de archivos 3.0.

El uso de la API Files podría conllevar cargos por transferencia de datos de Azure Databricks.

Enviar solicitudes al host regional

Important

Esta característica se encuentra en su versión beta. Para utilizarla, un administrador de espacio de trabajo debe activar Files API V3 with Large File Upload Support desde la página Previews. Consulte Administrar versiones preliminares de Azure Databricks.

Envía las solicitudes de la API Send Files 3.0 al nombre de host regional del espacio de trabajo al que pertenece el usuario solicitante. El nombre de host regional tiene el siguiente formato:

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

Por ejemplo: 1234567890123456.storage.westus.azuredatabricks.net.

Para encontrar el ID y la región de tu espacio de trabajo, usa la consola de cuenta. Consulte Nombres, direcciones URL e identificadores de instancias de áreas de trabajo. También puedes encontrar el ID del espacio de trabajo en la URL de despliegue: en https://<databricks-instance>/?o=1234567890123456, el número después de o= es el ID del espacio de trabajo. La interfaz del espacio de trabajo muestra la región debajo del nombre del espacio de trabajo.

Configuración de la conectividad de red

Important

Esta característica se encuentra en su versión beta. Para utilizarla, un administrador de espacio de trabajo debe activar Files API V3 with Large File Upload Support desde la página Previews. Consulte Administrar versiones preliminares de Azure Databricks.

Files API 3.0 requiere conectividad de red desde tu red a Azure Databricks y desde Azure Databricks a tu almacenamiento.

Desde su red hasta Azure Databricks

Si permites el acceso público a internet a tu espacio de trabajo pero lo restringes con un cortafuegos, incluye en la lista de permitidos los rangos IP del plano de control para tu región.

Incluye las IPs bajo IPs del plano de control, incluyendo almacenamiento por defecto y aplicación web. Véase Tráfico entrante al plano de control de Azure Databricks.

Si no permites el acceso a internet a Azure Databricks y te conectas a través de un enlace privado front-end, crea un segundo enlace privado front-end para servicios intensivos en rendimiento. Consulte Configurar enlace privado entrante para servicios con altos requerimientos de rendimiento.

De Azure Databricks a su almacenamiento

Si permite el acceso público a su almacenamiento pero aplica restricciones de red, para el almacenamiento dentro de la región, añada sus cuentas de almacenamiento a un perímetro de seguridad de red (NSP) de Azure y, a continuación, incluya la AzureDatabricksServerlessetiqueta de servicio en la lista de permitidos. El perímetro de seguridad de la red debe permanecer en modo Transición. De lo contrario, agrega a la lista de permitidos las IPs salientes de Azure Databricks.

Si no permites el acceso público a tu almacenamiento, configura un enlace privado a tu almacenamiento de Azure. Consulte Configurar la conectividad privada con recursos Azure.

Note

Se aplica la facturación de red serverless. Consulte Descripción de los costos de red de Databricks.

Sube archivos grandes con carga multiparte

Important

Esta característica se encuentra en su versión beta. Para utilizarla, un administrador de espacio de trabajo debe activar Files API V3 with Large File Upload Support desde la página Previews. Consulte Administrar versiones preliminares de Azure Databricks.

Una sola solicitud de subida acepta archivos de hasta 5000 MiB. Para subir un archivo más grande, o un archivo cuyo tamaño es desconocido cuando comienza la subida, usa la carga multiparte: subes el archivo en partes, y Azure Databricks las ensambla en un solo archivo.

Los números de pieza van del 1 al 10000. Cada pieza excepto la última debe tener al menos 5 MiB, y cada pieza puede tener como máximo 4000 MiB. Azure Databricks ensambla las piezas en orden ascendente de número de parte. Para cada parámetro, consulta Subir un archivo y Realizar una acción sobre un archivo.

Ejemplo de carga multiparte

El siguiente ejemplo sube un archivo en dos partes.

Para iniciar la sesión de subida, inicia la subida. La respuesta contiene el upload_id que identifica la sesión:

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

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

Para subir la primera parte, envía su contenido con el upload_id y el part_number. La respuesta incluye el ETag de la parte:

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"

Para subir la segunda parte, repite la solicitud con la siguiente part_number:

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"

Para terminar, completa la subida con un cuerpo que enumere todas las partes y su ETag almacenado:

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"

El elemento ETag de esta respuesta pertenece a todo el archivo ensamblado, no a una parte. Puedes usarlo en solicitudes condicionales posteriores, por ejemplo, para sobrescribir el archivo solo si no ha cambiado desde que lo subiste.

Para cancelar la subida en lugar de completarla, envía la abort-upload acción con la upload_id:

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

200 OK

Descarga archivos grandes con solicitudes de rango

Utiliza peticiones por rango para descargar un archivo grande en varias peticiones más pequeñas, o para reanudar una descarga interrumpida.

Solicitar un rango

Envía la Range cabecera con las posiciones basadas en cero del primer y último byte que quieres. El rango incluye ambas posiciones. Por ejemplo, bytes=0-1048575 solicita el primer 1 MiB de un archivo de 10 MiB:

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 respuesta contiene solo los bytes solicitados y Content-Range muestra qué bytes contiene y el tamaño total del archivo. Para leer hasta el final del archivo, omita la última posición, como en bytes=1048576-. Si la última posición está después del final del archivo, la respuesta contiene los bytes hasta el final. Para conocer otras Range sintaxis, consulta Descargar un archivo.

Una HEAD solicitud con encabezado Range devuelve el mismo estado y encabezados que la solicitud correspondiente GET , sin el cuerpo.

Reanudar una descarga interrumpida

Para reanudar una descarga, solicita los bytes restantes con un rango que empiece en el primer byte que no hayas recibido. También envía If-Match con el ETag de tu primera respuesta, para no combinar bytes de dos versiones del archivo:

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 el archivo ha cambiado, el servidor devuelve 412 Precondition Failed, y tienes que empezar la descarga de nuevo.

Usa solicitudes condicionales

Important

Esta característica se encuentra en su versión beta. Para utilizarla, un administrador de espacio de trabajo debe activar Files API V3 with Large File Upload Support desde la página Previews. Consulte Administrar versiones preliminares de Azure Databricks.

Una solicitud condicional solo entra en vigor si el archivo está en el estado que esperas. Utiliza solicitudes condicionales para evitar descargas repetidas, para evitar que los escritores simultáneos sobrescriban los cambios de los demás y para crear o eliminar archivos de forma segura. Files API 3.0 soporta los cuatro encabezados condicionales HTTP estándar del RFC 9110:

Header Se compara con Se aplica en
If-Match El ETag del archivo Lee, escribe y elimina
If-None-Match El ETag del archivo Lee y escribe
If-Modified-Since La hora Last-Modified del archivo Solo lectura
If-Unmodified-Since La hora Last-Modified del archivo Solo lectura

Cuando no se cumple la condición, el servidor no realiza la operación y devuelve uno de los siguientes estados:

  • 304 Not Modified, cuando una solicitud de GET o HEAD con If-None-Match o If-Modified-Since falla. Tu copia en caché sigue siendo válida.
  • 412 Precondition Failed, cuando falla cualquier otra condición.

Validadores: ETag y Last-Modified

Los encabezados condicionales comparan un valor que proporcionas con uno de los validadores del archivo. La API de Archivos devuelve ambos validadores como encabezados de respuesta en GET y HEAD:

  • ETag: un identificador opaco para el contenido del archivo, también se devuelve en PUT y en la respuesta multiparte complete-upload. Guárdalo exactamente tal como se devuelve, incluyendo las comillas que lo rodean, y no lo analices ni lo construyas.
  • Last-Modified: el tiempo de última modificación del archivo, como fecha HTTP. Su precisión es de un segundo, por lo que If-Unmodified-Since y If-Modified-Since no pueden detectar varios cambios en el mismo segundo. Para el control de concurrencia, use ETag con If-Match o If-None-Match.

Lecturas condicionales

La lectura condicional más común es la revalidación de caché. Envía If-None-Match con la ETag de tu copia en caché, o If-Modified-Since con la hora de la última vez que la recuperaste. Si el archivo no cambia, el servidor regresa 304 Not Modified sin cuerpo. De lo contrario, devuelve 200 OK con el contenido nuevo:

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

304 Not Modified

If-Match y If-Unmodified-Since funcionan al revés: el servidor devuelve el archivo solo si no ha cambiado, y en caso contrario devuelve 412. Una operación de lectura puede incluir como máximo dos encabezados condicionales, y su precedencia sigue la RFC 9110.

Escrituras condicionales

En PUT, usa If-None-Match y If-Match para evitar sobrescribir cambios que no has visto, también llamado el problema de la actualización perdida:

  • If-None-Match: * sube el archivo solo si no existe ningún archivo en la ruta. De lo contrario, la solicitud devuelve 412 Precondition Failed.
  • If-Match: <etag> sube el archivo solo si su ETag actual coincide con el que tú proporcionas. De lo contrario, la solicitud devuelve 412 Precondition Failed, o 404 si no existe ningún archivo en la ruta.

Para crear un archivo solo si no existe ya, envíe 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

Para sobrescribir un archivo solo si sigue siendo la versión que recuperaste por última vez, envía su ETag con 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

Para una subida multiparte, envía el encabezado condicional en la initiate-upload llamada. La API de Archivos lo evalúa cuando se completa la subida, por lo que la condición se aplica al archivo ensamblado. Para los formularios de cabecera que soporta cada llamada, consulte Subir un archivo y Realizar una acción sobre un archivo.

Eliminaciones condicionales

Un DELETE simple se ejecuta con éxito incluso si el archivo no existe, por lo que no puede indicarte si has eliminado la versión que pretendías. Para hacer una eliminación condicional, envíe If-Match:

  • If-Match: <etag> elimina el archivo solo si su ETag actual coincide con el que proporcionas. Si alguien cambió el archivo después de que lo obtuviste, la solicitud devuelve 412 Precondition Failed. Si el archivo ya no existe, devuelve 404.
  • If-Match: * elimina el archivo solo si existe y devuelve 404 si no existe.
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Versiones de la API de archivos

La API de Archivos 2.0 envía solicitudes al nombre de host de tu espacio de trabajo con el /api/2.0/fs prefijo endpoint. No soporta subida multiparte, y su único encabezado condicional es If-Unmodified-Since en descargas. Consulta la referencia Files API 2.0.

Para mover código de la API de archivos 2.0 a la 3.0, realiza los siguientes cambios:

  • Se actualizó por última vez el