API do DBFS

A API DBFS é uma API databricks que torna simples interagir com várias fontes de dados sem ter de incluir as suas credenciais sempre que lê um ficheiro. Consulte o Databricks File System (DBFS) para obter mais informações. Para um cliente de linha de comando fácil de utilizar da DBFS API, consulte Databricks CLI.

Nota

Para garantir uma elevada qualidade de serviço sob carga pesada, a Azure Databricks está agora a impor limites de taxa de API para chamadas DBFS API. Os limites são definidos por espaço de trabalho para garantir uma utilização justa e uma elevada disponibilidade. Estão disponíveis retrações automáticas utilizando a versão CLI 0.12.0 da Databricks. Aconselhamos todos os clientes a mudarem para a versão CLI mais recente da Databricks.

Importante

Para aceder às APIs REST do Databricks, tem de se autenticar.

Limitações

A utilização da API DBFS com recipientes de armazenamento ativados por firewall não é suportada. O Databricks recomenda a utilização do Databricks Connect ou az storage.

Adicionar bloco

Ponto final Método HTTP
2.0/dbfs/add-block POST

Anexar um bloco de dados ao fluxo especificado pelo manípulo de entrada. Se a pega não existir, esta chamada lançará uma exceção com RESOURCE_DOES_NOT_EXIST . Se o bloco de dados exceder 1 MB, esta chamada lançará uma exceção com MAX_BLOCK_SIZE_EXCEEDED . Um fluxo de trabalho típico para o upload de ficheiros seria:

  1. Ligue criar e obter uma maçaneta.
  2. Faça uma ou mais add-block chamadas com a alça que tem.
  3. Ligue perto com a pega que tem.

Exemplo

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

Estrutura de pedido

Nome do Campo Tipo Description
cabo INT64 A pega num riacho aberto. Este campo é obrigatório.
dados BYTES Os dados codificados de base64 para anexar ao fluxo. Isto tem um limite de 1 MB. Este campo é obrigatório.

Fechar

Ponto final Método HTTP
2.0/dbfs/close POST

Feche o fluxo especificado pelo manípulo de entrada. Se a pega não existir, esta chamada abre uma exceção com RESOURCE_DOES_NOT_EXIST . Um fluxo de trabalho típico para o upload de ficheiros seria:

  1. Ligue criar e obter uma maçaneta.
  2. Faça uma ou mais chamadas de blocos adicionais com a pega que tem.
  3. Ligue close com a maçaneta que tem.

Exemplo

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

Se a chamada for bem sucedida, não aparece a saída.

Estrutura de pedido

Nome do Campo Tipo Description
cabo INT64 A pega num riacho aberto. Este campo é obrigatório.

Criar

Ponto final Método HTTP
2.0/dbfs/create POST

Abra um fluxo para escrever a um ficheiro e devolva uma pega a este fluxo. Há um tempo de 10 minutos para o manipulsão nesta pega. Se um ficheiro ou diretório já existir no caminho certo e overwrite estiver definido como falso, esta chamada abre uma exceção com RESOURCE_ALREADY_EXISTS . Um fluxo de trabalho típico para o upload de ficheiros seria:

  1. Liga create e arranja uma manípula.
  2. Faça uma ou mais chamadas de blocos adicionais com a pega que tem.
  3. Ligue perto com a pega que tem.

Exemplo

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

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do novo ficheiro. O caminho deve ser o caminho absoluto DBFS (por exemplo
/mnt/my-file.txt). Este campo é obrigatório.
sobrepor BOOL A bandeira que especifica se deve substituir ficheiros ou ficheiros existentes.

Estrutura de resposta

Nome do Campo Tipo Description
cabo INT64 Manuseie o que deve ser posteriormente passado para o add-block e chama ao escrever para um ficheiro através de um close fluxo.

Excluir

Ponto final Método HTTP
2.0/dbfs/delete POST

Elimine o ficheiro ou o diretório (eliminando opcionalmente todos os ficheiros do diretório). Esta chamada abre uma exceção IO_ERROR se o caminho for um diretório não vazio e se recursivo for definido para falso ou em outros erros semelhantes.

Quando elimina um grande número de ficheiros, a operação de eliminação é feita em incrementos. A chamada retorna uma resposta após aproximadamente 45 segundos com uma mensagem de erro (Serviço 503 Indisponível) pedindo-lhe para voltar a invocar a operação de eliminação até que a estrutura do diretório seja totalmente eliminada. Por exemplo:

{
  "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."
}

Para operações que eliminem mais de 10K ficheiros, desencorajamos a utilização da API DBFS REST, mas aconselhamos a realizar tais operações no contexto de um cluster, utilizando o utilitário do sistema de ficheiros (dbutils.fs). dbutils.fs abrange o âmbito funcional da API DBFS REST, mas a partir de cadernos. A execução destas operações utilizando cadernos proporciona um melhor controlo e gestão, como eliminações seletivas, e a possibilidade de automatizar postos de trabalho periódicos.

Exemplo

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

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do ficheiro ou diretório para apagar. O caminho deve ser o caminho absoluto da DBFS (por /mnt/foo/ exemplo). Este campo é obrigatório.
recursivo BOOL Se apagar ou não o conteúdo do diretório de forma recursiva. A eliminação de diretórios vazios pode ser feita sem fornecer a bandeira recursiva.

Obter estado

Ponto final Método HTTP
2.0/dbfs/get-status GET

Obtenha a informação do arquivo de um ficheiro ou diretório. Se o ficheiro ou diretório não existir, esta chamada abre uma exceção com RESOURCE_DOES_NOT_EXIST .

Exemplo

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
}

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do arquivo ou diretório. O caminho deve ser o caminho absoluto DBFS (por exemplo, /mnt/my-folder/ ). Este campo é obrigatório.

Estrutura de resposta

Nome do Campo Tipo Description
caminho STRING O caminho do arquivo ou diretório.
is_dir BOOL Se o caminho é um diretório.
file_size INT64 O comprimento do ficheiro em bytes ou zero se o caminho for um diretório.
modification_time INT64 A última vez, em milissegundos de época, o ficheiro ou diretório foi modificado.

Lista

Ponto final Método HTTP
2.0/dbfs/list GET

Listar o conteúdo de um diretório ou detalhes do ficheiro. Se o ficheiro ou diretório não existir, esta chamada abre uma exceção com RESOURCE_DOES_NOT_EXIST .

Ao ligar list para um grande diretório, a list operação irá esgotar-se após aproximadamente 60 segundos. Recomendamos vivamente a utilização list apenas em diretórios que contenham menos de 10K ficheiros e desencorajamos a utilização da API DBFS REST para operações que listam mais de 10K ficheiros. Em vez disso, recomendamos que realize tais operações no contexto de um cluster, utilizando o utilitário do sistema De ficheiro (dbutils.fs), que fornece a mesma funcionalidade sem o tempo de saída.

Exemplo

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
    },
    ...
  ]
}

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do arquivo ou diretório. O caminho deve ser o caminho absoluto da DBFS (por /mnt/foo/ exemplo). Este campo é obrigatório.

Estrutura de resposta

Nome do Campo Tipo Description
ficheiros Uma matriz de FileInfo Uma lista de FileInfo que descrevem conteúdos de diretório ou arquivo.

Mkdirs

Ponto final Método HTTP
2.0/dbfs/mkdirs POST

Crie o diretório e os directórios-mãe necessários se não existirem. Se existir um ficheiro (não um diretório) em qualquer prefixo do caminho de entrada, esta chamada abre uma exceção com RESOURCE_ALREADY_EXISTS . Se esta operação falhar, pode ter conseguido criar alguns dos directórios-mãe necessários.

Exemplo

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

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do novo diretório. O caminho deve ser o caminho absoluto da DBFS (por exemplo,
/mnt/my-folder/). Este campo é obrigatório.

Mover-se

Ponto final Método HTTP
2.0/dbfs/move POST

Mover um ficheiro de um local para outro dentro do DBFS. Se o ficheiro de origem não existir, esta chamada abre uma exceção com RESOURCE_DOES_NOT_EXIST . Se já existe um ficheiro no caminho de destino, esta chamada abre uma exceção com RESOURCE_ALREADY_EXISTS . Se o caminho de origem dado for um diretório, esta chamada move sempre de forma recorrente todos os ficheiros.

Ao mover um grande número de ficheiros, a chamada da API irá esgotar-se após aproximadamente 60 segundos, potencialmente resultando em dados parcialmente movidos. Portanto, para operações que movem mais de 10K ficheiros, desencorajamos fortemente a utilização da API DBFS REST. Em vez disso, recomendamos que realize tais operações no contexto de um cluster, utilizando o utilitário do sistema De ficheiro (dbutils.fs) a partir de um portátil, que fornece a mesma funcionalidade sem o tempo de saída.

Exemplo

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" }'
{}

Estrutura de pedido

Nome do Campo Tipo Description
source_path STRING O caminho de origem do ficheiro ou diretório. O caminho deve ser o caminho absoluto DBFS (por exemplo, /mnt/my-source-folder/ ). Este campo é obrigatório.
destination_path STRING O caminho de destino do arquivo ou diretório. O caminho deve ser o caminho absoluto DBFS (por exemplo, /mnt/my-destination-folder/ ). Este campo é obrigatório.

Colocar

Ponto final Método HTTP
2.0/dbfs/put POST

Faça o upload de um ficheiro através da utilização de um post de formulário multipart. É usado principalmente para streaming de uploads, mas também pode ser usado como uma chamada única conveniente para upload de dados.

A quantidade de dados que podem ser passados usando o contents parâmetro limita-se a 1 MB se especificado como uma corda MAX_BLOCK_SIZE_EXCEEDED (é lançado se excedido) e 2 GB como ficheiro.

Exemplo

Para carregar um ficheiro local nomeado HelloWorld.txt no diretório atual:

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 carregar o conteúdo Hello, World! como uma cadeia codificada 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 }'
{}

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do novo ficheiro. O caminho deve ser o caminho absoluto da DBFS (por /mnt/foo/ exemplo). Este campo é obrigatório.
conteúdos BYTES Este parâmetro pode estar ausente e, em vez disso, será utilizado um ficheiro registado.
sobrepor BOOL A bandeira que especifica se deve substituir os ficheiros existentes.

Ler

Ponto final Método HTTP
2.0/dbfs/read GET

Devolva o conteúdo de um ficheiro. Se o ficheiro não existir, esta chamada abre uma exceção com RESOURCE_DOES_NOT_EXIST . Se o caminho for um diretório, o comprimento de leitura é negativo, ou se o offset for negativo, esta chamada lança uma exceção com INVALID_PARAMETER_VALUE . Se o comprimento de leitura exceder 1 MB, esta chamada abre uma exceção com MAX_READ_SIZE_EXCEEDED . Se offset + length exceder o número de bytes num ficheiro, lê o conteúdo até ao fim do ficheiro.

Exemplo

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="
}

Estrutura de pedido

Nome do Campo Tipo Description
caminho STRING O caminho do arquivo para ler. O caminho deve ser o caminho absoluto da DBFS (por /mnt/foo/ exemplo). Este campo é obrigatório.
offset INT64 A contrapartida para ler de in bytes.
length INT64 O número de bytes para ler a partir do offset. Isto tem um limite de 1 MB, e um valor padrão de 0,5 MB.

Estrutura de resposta

Nome do Campo Tipo Description
bytes_read INT64 O número de bytes lidos (pode ser inferior ao comprimento se atingirmos a extremidade do ficheiro). Isto refere-se ao número de bytes lidos em versão não codificada (os dados de resposta estão codificados com base64).
dados BYTES O conteúdo codificado base64 do ficheiro é lido.

Estruturas de dados

Nesta secção:

FileInfo

Os atributos de um ficheiro ou diretório.

Nome do Campo Tipo Description
caminho STRING O caminho do arquivo ou diretório.
is_dir BOOL Se o caminho é um diretório.
file_size INT64 O comprimento do ficheiro em bytes ou zero se o caminho for um diretório.
modification_time INT64 A última vez, em milissegundos de época, o ficheiro ou diretório foi modificado.