DBFS API

La API de DBFS es una API de Databricks que facilita la interacción con varios orígenes de datos sin tener que incluir las credenciales cada vez que se lee un archivo. Consulte Databricks File System (DBFS) para obtener más información. Para obtener un cliente de línea de comandos fácil de usar de la API de DBFS, consulte CLI de Databricks.

Nota

Para garantizar una alta calidad de servicio bajo una carga elevada, Azure Databricks ahora está aplicando límites de velocidad de API para las llamadas API de DBFS. Los límites se establecen por área de trabajo para garantizar un uso justo y una alta disponibilidad. Los reintentos automáticos están disponibles mediante la CLI de Databricks versión 0.12.0 y posteriores. Recomendamos a todos los clientes que cambien a la versión más reciente de la CLI de Databricks.

Importante

Para acceder a las API REST de Databricks, es preciso autenticarse.

Limitaciones

No se admite el uso de la API de DBFS con contenedores de almacenamiento habilitados para firewall. Databricks recomienda usar Databricks Connect o az storage.

Agregar bloque

Punto de conexión Método HTTP
2.0/dbfs/add-block POST

Anexe un bloque de datos al flujo especificado por el identificador de entrada. Si el identificador no existe, esta llamada producirá una excepción con RESOURCE_DOES_NOT_EXIST . Si el bloque de datos supera 1 MB, esta llamada producirá una excepción con MAX_BLOCK_SIZE_EXCEEDED . Un flujo de trabajo típico para la carga de archivos sería:

  1. Llame a create y obtenga un identificador.
  2. Realice una o varias add-block llamadas con el identificador que tiene.
  3. Llame a Close con el identificador que tiene.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/add-block \
--data '{ "data": "SGVsbG8sIFdvcmxkIQ==", "handle": 1234567890123456 }'
{}

Estructura de solicitudes

Nombre del campo Tipo Descripción
handle INT64 Identificador de una secuencia abierta. Este campo es obligatorio.
datos BYTES Datos codificados en base64 que se anexarán a la secuencia. Tiene un límite de 1 MB. Este campo es obligatorio.

Cerrar

Punto de conexión Método HTTP
2.0/dbfs/close POST

Cierre la secuencia especificada por el identificador de entrada. Si el identificador no existe, esta llamada produce una excepción con RESOURCE_DOES_NOT_EXIST . Un flujo de trabajo típico para la carga de archivos sería:

  1. Llame a create y obtenga un identificador.
  2. Realice una o varias llamadas de bloque de complementos con el identificador que tiene.
  3. Llame close a con el identificador que tiene.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/close \
--data '{ "handle": 1234567890123456 }'

Si la llamada se realiza correctamente, no se muestra ninguna salida.

Estructura de solicitudes

Nombre del campo Tipo Descripción
handle INT64 Identificador de una secuencia abierta. Este campo es obligatorio.

Crear

Punto de conexión Método HTTP
2.0/dbfs/create POST

Abra una secuencia para escribir en un archivo y devuelve un identificador a esta secuencia. Hay un tiempo de espera de inactividad de 10 minutos en este identificador. Si ya existe un archivo o directorio en la ruta de acceso especificada y se establece en false, esta llamada overwrite produce una excepción con RESOURCE_ALREADY_EXISTS . Un flujo de trabajo típico para la carga de archivos sería:

  1. Llame create a y obtenga un identificador.
  2. Realice una o varias llamadas de bloque de complementos con el identificador que tiene.
  3. Llame a Close con el identificador que tiene.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/create \
--data '{ "path": "/tmp/HelloWorld.txt", "overwrite": true }'
{ "handle": 1234567890123456 }

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del nuevo archivo. La ruta de acceso debe ser la ruta de acceso absoluta de DBFS (por ejemplo,
/mnt/my-file.txt). Este campo es obligatorio.
sobrescribir BOOL Marca que especifica si se deben sobrescribir archivos o archivos existentes.

Estructura de respuesta

Nombre del campo Tipo Descripción
handle INT64 Controlar que se debe pasar posteriormente a las add-block llamadas y al escribir en un archivo a través de una close secuencia.

Eliminar

Punto de conexión Método HTTP
2.0/dbfs/delete POST

Elimine el archivo o directorio (opcionalmente, elimine todos los archivos del directorio de forma recursiva). Esta llamada produce una excepción con si la ruta de acceso es un directorio no vacío y recursiva se establece en false o IO_ERROR en otros errores similares.

Cuando se elimina un gran número de archivos, la operación de eliminación se realiza en incrementos. La llamada devuelve una respuesta después de aproximadamente 45 segundos con un mensaje de error (503 Servicio no disponible) que le pide que vuelva a invocar la operación de eliminación hasta que la estructura de directorios se elimine por completo. Por ejemplo:

{
  "error_code": "PARTIAL_DELETE",
  "message": "The requested operation has deleted 324 files. There are more files remaining. You must make another request to delete more."
}

En el caso de las operaciones que eliminan más de 10 000 archivos, no se recomienda usar la API REST de DBFS, pero se recomienda realizar dichas operaciones en el contexto de un clúster, mediante la utilidad del sistema de archivos (dbutils.fs). dbutils.fs abarca el ámbito funcional de la API REST de DBFS, pero desde cuadernos. La ejecución de estas operaciones mediante cuadernos proporciona un mejor control y capacidad de administración, como eliminaciones selectivas, y la posibilidad de automatizar trabajos de eliminación periódicos.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/delete \
--data '{ "path": "/tmp/HelloWorld.txt" }'
{}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo o directorio que se eliminará. La ruta de acceso debe ser la ruta de acceso dbfs absoluta (por ejemplo, /mnt/foo/ ). Este campo es obligatorio.
recursive BOOL Si se debe eliminar o no de forma recursiva el contenido del directorio. La eliminación de directorios vacíos se puede realizar sin proporcionar la marca recursiva.

Obtener estado

Punto de conexión Método HTTP
2.0/dbfs/get-status GET

Obtenga la información de archivo de un archivo o directorio. Si el archivo o directorio no existe, esta llamada produce una excepción con RESOURCE_DOES_NOT_EXIST .

Ejemplo

curl --netrc -X GET \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/get-status \
--data '{ "path": "/tmp/HelloWorld.txt" }' \
| jq .
{
  "path": "/tmp/HelloWorld.txt",
  "is_dir": false,
  "file_size": 13,
  "modification_time": 1622054945000
}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo o directorio. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/my-folder/ ). Este campo es obligatorio.

Estructura de respuesta

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo o directorio.
is_dir BOOL Si la ruta de acceso es un directorio.
file_size INT64 Longitud del archivo en bytes o cero si la ruta de acceso es un directorio.
modification_time INT64 La última vez, en milisegundos de época, se modificó el archivo o directorio.

Lista

Punto de conexión Método HTTP
2.0/dbfs/list GET

Enumerar el contenido de un directorio o los detalles del archivo. Si el archivo o directorio no existe, esta llamada produce una excepción con RESOURCE_DOES_NOT_EXIST .

Al llamar a en un directorio grande, la operación se hará tiempo de list espera después de aproximadamente list 60 segundos. Se recomienda encarecidamente usar solo en directorios que contengan menos de 10 000 archivos y se desaconseja el uso de la API REST de DBFS para las operaciones que incluyen más de list 10 000 archivos. En su lugar, se recomienda realizar estas operaciones en el contexto de un clúster, mediante la utilidad del sistema de archivos (dbutils.fs),que proporciona la misma funcionalidad sin tiempo de ejecución.

Ejemplo

curl --netrc -X GET \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/list \
--data '{ "path": "/tmp" }' \
| jq .
{
  "files": [
    {
      "path": "/tmp/HelloWorld.txt",
      "is_dir": false,
      "file_size": 13,
      "modification_time": 1622054945000
    },
    ...
  ]
}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo o directorio. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/foo/ ). Este campo es obligatorio.

Estructura de respuesta

Nombre del campo Tipo Descripción
archivos Matriz de FileInfo Lista de FileInfo que describe el contenido del directorio o archivo.

Mkdirs

Punto de conexión Método HTTP
2.0/dbfs/mkdirs POST

Cree el directorio y los directorios primarios necesarios si no existen. Si existe un archivo (no un directorio) en cualquier prefijo de la ruta de acceso de entrada, esta llamada produce una excepción con RESOURCE_ALREADY_EXISTS . Si se produce un error en esta operación, es posible que haya creado correctamente algunos de los directorios primarios necesarios.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/mkdirs \
--data '{ "path": "/tmp/my-new-dir" }'
{}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del nuevo directorio. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo,
/mnt/my-folder/). Este campo es obligatorio.

Mover

Punto de conexión Método HTTP
2.0/dbfs/move POST

Mueva un archivo de una ubicación a otra dentro de DBFS. Si el archivo de origen no existe, esta llamada produce una excepción con RESOURCE_DOES_NOT_EXIST . Si ya existe un archivo en la ruta de acceso de destino, esta llamada produce una excepción con RESOURCE_ALREADY_EXISTS . Si la ruta de acceso de origen especificada es un directorio, esta llamada siempre mueve de forma recursiva todos los archivos.

Al mover un gran número de archivos, la llamada API dará tiempo de espera después de aproximadamente 60 segundos, lo que podría provocar datos movidos parcialmente. Por lo tanto, para las operaciones que mueven más de 10 000 archivos, se desaconseja encarecidamente el uso de la API REST de DBFS. En su lugar, se recomienda realizar estas operaciones en el contexto de un clúster, mediante la utilidad del sistema de archivos (dbutils.fs) de un cuaderno, que proporciona la misma funcionalidad sin tiempo de ejecución.

Ejemplo

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/move \
--data '{ "source_path": "/tmp/HelloWorld.txt", "destination_path": "/tmp/my-new-dir/HelloWorld.txt" }'
{}

Estructura de solicitudes

Nombre del campo Tipo Descripción
source_path STRING Ruta de acceso de origen del archivo o directorio. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/my-source-folder/ ). Este campo es obligatorio.
destination_path STRING Ruta de acceso de destino del archivo o directorio. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/my-destination-folder/ ). Este campo es obligatorio.

Put

Punto de conexión Método HTTP
2.0/dbfs/put POST

Upload un archivo mediante el uso de la publicación del formulario de varias partes. Se usa principalmente para cargas de streaming, pero también se puede usar como una llamada única adecuada para la carga de datos.

La cantidad de datos que se pueden pasar mediante el parámetro se limita a 1 MB si se especifica como una cadena ( se produce si se supera) y 2 GB como contents MAX_BLOCK_SIZE_EXCEEDED archivo.

Ejemplo

Para cargar un archivo local denominado HelloWorld.txt en el directorio actual:

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/put \
--form contents=@HelloWorld.txt \
--form path="/tmp/HelloWorld.txt" \
--form overwrite=true

Para cargar contenido Hello, World! como una cadena codificada en Base64:

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/put \
--data '{ "path": "/tmp/HelloWorld.txt", "contents": "SGVsbG8sIFdvcmxkIQ==", "overwrite": true }'
{}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del nuevo archivo. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/foo/ ). Este campo es obligatorio.
contenido BYTES Este parámetro podría no estar presente y, en su lugar, se usará un archivo publicado.
sobrescribir BOOL Marca que especifica si se sobrescribirán los archivos existentes.

Lectura

Punto de conexión Método HTTP
2.0/dbfs/read GET

Devuelve el contenido de un archivo. Si el archivo no existe, esta llamada produce una excepción con RESOURCE_DOES_NOT_EXIST . Si la ruta de acceso es un directorio, la longitud de lectura es negativa o si el desplazamiento es negativo, esta llamada produce una excepción con INVALID_PARAMETER_VALUE . Si la longitud de lectura supera 1 MB, esta llamada produce una excepción con MAX_READ_SIZE_EXCEEDED . Si offset + length supera el número de bytes de un archivo, lee el contenido hasta el final del archivo.

Ejemplo

curl --netrc -X GET \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/read \
--data '{ "path": "/tmp/HelloWorld.txt", "offset": 1, "length": 8 }' \
| jq .
{
  "bytes_read": 8,
  "data": "ZWxsbywgV28="
}

Estructura de solicitudes

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo que se leerá. La ruta de acceso debe ser la ruta de acceso de DBFS absoluta (por ejemplo, /mnt/foo/ ). Este campo es obligatorio.
offset INT64 Desplazamiento del que se leerá en bytes.
length INT64 Número de bytes que se leerán a partir del desplazamiento. Tiene un límite de 1 MB y un valor predeterminado de 0,5 MB.

Estructura de respuesta

Nombre del campo Tipo Descripción
bytes_read INT64 El número de bytes leídos (podría ser menor que la longitud si se pulsa el final del archivo). Esto hace referencia al número de bytes leídos en una versión sin codificar (los datos de respuesta están codificados en base64).
datos BYTES Contenido codificado en base64 del archivo leído.

Estructuras de datos

En esta sección:

FileInfo

Atributos de un archivo o directorio.

Nombre del campo Tipo Descripción
path STRING Ruta de acceso del archivo o directorio.
is_dir BOOL Si la ruta de acceso es un directorio.
file_size INT64 Longitud del archivo en bytes o cero si la ruta de acceso es un directorio.
modification_time INT64 La última vez, en milisegundos de época, se modificó el archivo o directorio.