DBFS API 2.0

DBFS-API:et är ett Databricks-API som gör det enkelt att interagera med olika datakällor utan att behöva inkludera dina autentiseringsuppgifter varje gång du läser en fil. Mer information finns i Databricks-filsystem (DBFS). En enkel kommandoradsklient för DBFS-API:et finns i Databricks CLI.

Anteckning

För att säkerställa hög tjänstkvalitet under hög belastning tillämpar Azure Databricks nu API-hastighetsbegränsningar för DBFS API-anrop. Gränser anges per arbetsyta för att säkerställa rättvis användning och hög tillgänglighet. Automatiska återförsök är tillgängliga med Databricks CLI version 0.12.0 och senare. Vi rekommenderar att alla kunder växlar till den senaste Databricks CLI-versionen.

Viktigt

För att få åtkomst till Databricks REST API:er måste du autentisera.

Begränsningar

Det går inte att använda DBFS-API:et med brandväggsaktiverade lagringscontainrar. Databricks rekommenderar att du använder Databricks Connect eller az storage.

Lägg till block

Slutpunkt HTTP-metod
2.0/dbfs/add-block POST

Lägg till ett datablock i dataströmmen som anges av indatahandtaget. Om referensen inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST. Om datablocket överskrider 1 MB utlöser det här anropet ett undantag med MAX_BLOCK_SIZE_EXCEEDED. Ett vanligt arbetsflöde för filuppladdning är:

  1. Anropa skapa och få ett handtag.
  2. Ring ett eller flera add-block samtal med handtaget du har.
  3. Ring nära med handtaget du har.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
Hantera INT64 Handtaget på en öppen ström. Det här fältet är obligatoriskt.
data BYTES Base64-kodade data som ska läggas till i dataströmmen. Detta har en gräns på 1 MB. Det här fältet är obligatoriskt.

Nära

Slutpunkt HTTP-metod
2.0/dbfs/close POST

Stäng strömmen som anges av indatahandtaget. Om handtaget inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST. Ett vanligt arbetsflöde för filuppladdning är:

  1. Anropa skapa och få ett handtag.
  2. Gör ett eller flera tilläggsblocksanrop med handtaget som du har.
  3. Ring close med handtaget du har.

Exempel

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

Om anropet lyckas visas inga utdata.

Struktur för begäranden

Fältnamn Typ Description
Hantera INT64 Handtaget på en öppen ström. Det här fältet är obligatoriskt.

Skapa

Slutpunkt HTTP-metod
2.0/dbfs/create POST

Öppna en dataström för att skriva till en fil och returnera ett handtag till den här dataströmmen. Det finns en tidsgräns på 10 minuter för inaktivitet i det här handtaget. Om en fil eller katalog redan finns på den angivna sökvägen och overwrite är inställd på false utlöser det här anropet ett undantag med RESOURCE_ALREADY_EXISTS. Ett vanligt arbetsflöde för filuppladdning är:

  1. Ring create och få ett handtag.
  2. Gör ett eller flera tilläggsblocksanrop med handtaget som du har.
  3. Ring nära med handtaget du har.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
path STRING Sökvägen till den nya filen. Sökvägen ska vara den absoluta DBFS-sökvägen (till exempel
/mnt/my-file.txt). Det här fältet är obligatoriskt.
skriv över BOOL Flaggan som anger om du vill skriva över befintlig fil eller filer.

Svarsstruktur

Fältnamn Typ Description
Hantera INT64 Hantera som därefter ska skickas till add-block och close anropar när du skriver till en fil via en dataström.

Ta bort

Slutpunkt HTTP-metod
2.0/dbfs/delete POST

Ta bort filen eller katalogen (om du vill kan du rekursivt ta bort alla filer i katalogen). Det här anropet utlöser ett undantag med IO_ERROR om sökvägen är en icke-tom katalog och rekursiv är inställd på falskt eller på andra liknande fel.

När du tar bort ett stort antal filer utförs borttagningsåtgärden i steg. Anropet returnerar ett svar efter cirka 45 sekunder med ett felmeddelande (503 Tjänsten är inte tillgänglig) där du uppmanas att åter anropa borttagningsåtgärden tills katalogstrukturen har tagits bort helt. Till exempel:

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

För åtgärder som tar bort mer än 10 000 filer avråder vi från att använda DBFS REST API, men rekommenderar att du utför sådana åtgärder i kontexten för ett kluster med hjälp av filsystemverktyget (dbutils.fs). dbutils.fs omfattar det funktionella omfånget för DBFS REST API, men från notebook-filer. Om du kör sådana åtgärder med notebook-filer får du bättre kontroll och hanterbarhet, till exempel selektiva borttagningar, och möjligheten att automatisera regelbundna borttagningsjobb.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
path STRING Sökvägen till filen eller katalogen som ska tas bort. Sökvägen ska vara den absoluta DBFS-sökvägen (t.ex. /mnt/foo/). Det här fältet är obligatoriskt.
Rekursiv BOOL Om du vill ta bort katalogens innehåll rekursivt eller inte. Du kan ta bort tomma kataloger utan att ange den rekursiva flaggan.

Hämta status

Slutpunkt HTTP-metod
2.0/dbfs/get-status GET

Hämta filinformationen för en fil eller katalog. Om filen eller katalogen inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST.

Exempel

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
}

Struktur för begäranden

Fältnamn Typ Description
path STRING Sökvägen till filen eller katalogen. Sökvägen ska vara den absoluta DBFS-sökvägen (till exempel /mnt/my-folder/). Det här fältet är obligatoriskt.

Svarsstruktur

Fältnamn Typ Description
path STRING Sökvägen till filen eller katalogen.
is_dir BOOL Om sökvägen är en katalog.
file_size INT64 Längden på filen i byte eller noll om sökvägen är en katalog.
modification_time INT64 Den senaste gången, i epoker millisekunder, ändrades filen eller katalogen.

Lista

Slutpunkt HTTP-metod
2.0/dbfs/list GET

Visa en lista över innehållet i en katalog eller information om filen. Om filen eller katalogen inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST.

När du anropar list i en stor katalog överskrider åtgärden tidsgränsen list efter cirka 60 sekunder. Vi rekommenderar starkt att du endast använder list på kataloger som innehåller mindre än 10 000 filer och avråder från att använda DBFS REST API för åtgärder som visar fler än 10 000 filer. I stället rekommenderar vi att du utför sådana åtgärder i kontexten för ett kluster med hjälp av filsystemverktyget (dbutils.fs) som ger samma funktioner utan tidsgräns.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
path STRING Sökvägen till filen eller katalogen. Sökvägen ska vara den absoluta DBFS-sökvägen (t.ex. /mnt/foo/). Det här fältet är obligatoriskt.

Svarsstruktur

Fältnamn Typ Description
filer En matris med FileInfo En lista över FileInfo som beskriver innehållet i katalogen eller filen.

Mkdirs

Slutpunkt HTTP-metod
2.0/dbfs/mkdirs POST

Skapa den angivna katalogen och nödvändiga överordnade kataloger om de inte finns. Om det finns en fil (inte en katalog) vid något prefix för indatasökvägen utlöser det här anropet ett undantag med RESOURCE_ALREADY_EXISTS. Om den här åtgärden misslyckas kan den ha lyckats skapa några av de överordnade kataloger som krävs.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
path STRING Sökvägen till den nya katalogen. Sökvägen ska vara den absoluta DBFS-sökvägen (till exempel
/mnt/my-folder/). Det här fältet är obligatoriskt.

Flytta

Slutpunkt HTTP-metod
2.0/dbfs/move POST

Flytta en fil från en plats till en annan plats i DBFS. Om källfilen inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST. Om det redan finns en fil i målsökvägen utlöser det här anropet ett undantag med RESOURCE_ALREADY_EXISTS. Om den angivna källsökvägen är en katalog flyttar det här anropet alltid rekursivt alla filer.

När du flyttar ett stort antal filer överskrider API-anropet tidsgränsen efter cirka 60 sekunder, vilket kan resultera i delvis flyttade data. För åtgärder som flyttar fler än 10 000 filer rekommenderar vi därför starkt att du använder DBFS REST API. I stället rekommenderar vi att du utför sådana åtgärder i kontexten för ett kluster med hjälp av filsystemverktyget (dbutils.fs) från en notebook-fil, vilket ger samma funktioner utan tidsgräns.

Exempel

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

Struktur för begäranden

Fältnamn Typ Description
source_path STRING Källsökvägen för filen eller katalogen. Sökvägen ska vara den absoluta DBFS-sökvägen (till exempel /mnt/my-source-folder/). Det här fältet är obligatoriskt.
destination_path STRING Målsökvägen för filen eller katalogen. Sökvägen ska vara den absoluta DBFS-sökvägen (till exempel /mnt/my-destination-folder/). Det här fältet är obligatoriskt.

Sätta

Slutpunkt HTTP-metod
2.0/dbfs/put POST

Upload en fil med hjälp av formulärinlägg med flera delar. Det används främst för strömmande uppladdningar, men kan också användas som ett bekvämt enda anrop för datauppladdning.

Mängden data som kan skickas med parametern contents är begränsad till 1 MB om den anges som en sträng (MAX_BLOCK_SIZE_EXCEEDED genereras om den överskrids) och 2 GB som en fil.

Exempel

Så här laddar du upp en lokal fil med namnet HelloWorld.txt i den aktuella katalogen:

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

Så här laddar du upp innehåll Hello, World! som en base64-kodad sträng:

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

Begärandestruktur

Fältnamn Typ Description
path STRING Sökvägen till den nya filen. Sökvägen ska vara den absoluta DBFS-sökvägen (t.ex. /mnt/foo/). Det här fältet är obligatoriskt.
Innehållet BYTES Den här parametern kanske saknas och i stället används en postad fil.
skriv över BOOL Flaggan som anger om befintliga filer ska skrivas över.

Läsa

Slutpunkt HTTP-metod
2.0/dbfs/read GET

Returnera innehållet i en fil. Om filen inte finns utlöser det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST. Om sökvägen är en katalog är läslängden negativ eller om förskjutningen är negativ utlöser det här anropet ett undantag med INVALID_PARAMETER_VALUE. Om läslängden överskrider 1 MB utlöser det här anropet ett undantag med MAX_READ_SIZE_EXCEEDED. Om offset + length överskrider antalet byte i en fil läser innehållet till slutet av filen.

Exempel

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

Begärandestruktur

Fältnamn Typ Description
path STRING Sökvägen till filen som ska läsas. Sökvägen ska vara den absoluta DBFS-sökvägen (t.ex. /mnt/foo/). Det här fältet är obligatoriskt.
offset INT64 Förskjutningen för att läsa från i byte.
length INT64 Antalet byte som ska läsas med början från förskjutningen. Detta har en gräns på 1 MB och ett standardvärde på 0,5 MB.

Svarsstruktur

Fältnamn Typ Description
bytes_read INT64 Antalet lästa byte (kan vara mindre än längden om vi når slutet av filen). Detta avser antalet byte som läss i en okodad version (svarsdata är base64-kodade).
data BYTES Det base64-kodade innehållet i filen lästes.

Datastrukturer

I det här avsnittet:

FileInfo

Attributen för en fil eller katalog.

Fältnamn Typ Description
path STRING Sökvägen till filen eller katalogen.
is_dir BOOL Om sökvägen är en katalog.
file_size INT64 Längden på filen i byte eller noll om sökvägen är en katalog.
modification_time INT64 Förra gången, i epok millisekunder, ändrades filen eller katalogen.