DBFS API

DBFS-API:et är ett Databricks-API som gör det enkelt att interagera med olika datakällor utan att du behöver inkludera dina autentiseringsuppgifter varje gång du läser en fil. Mer information finns i Databricks-filsystemet (DBFS). En lättanvänd 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 Azure Databricks nu api-hastighetsbegränsningar för DBFS API-anrop. Gränserna anges per arbetsyta för att säkerställa en rättvis användning och hög tillgänglighet. Automatiska återförsök är tillgängliga med Hjälp av Databricks CLI version 0.12.0 och senare. Vi rekommenderar att alla kunder byter till den senaste Databricks CLI-versionen.

Viktigt

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

Begränsningar

Användning av DBFS-API:et med brandväggsaktiverade lagringscontainrar stöds inte. 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 löste det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST . Om datablocket överskrider 1 MB 000 000 000 000 000 med MAX_BLOCK_SIZE_EXCEEDED . Ett vanligt arbetsflöde för filuppladdning är:

  1. Anropa skapa och hämta en referens.
  2. Gör ett eller flera add-block anrop med den referens som du har.
  3. Anropa Close med den referens som du har.

Exempel

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

Begärandestruktur

Fältnamn Typ Beskrivning
Hantera INT64 Referensen för en öppen dataströ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.

Stäng

Slutpunkt HTTP-metod
2.0/dbfs/close POST

Stäng dataströmmen som anges av indatahandtaget. Om referensen inte finns löste det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST . Ett vanligt arbetsflöde för filuppladdning är:

  1. Anropa skapa och hämta en referens.
  2. Gör ett eller flera tilläggsblocks-anrop med den referens som du har.
  3. Anropa close med den referens som 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.

Begärandestruktur

Fältnamn Typ Beskrivning
Hantera INT64 Referensen för en öppen dataströ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 returnerar en referens till den här dataströmmen. Det finns en tidsgräns på 10 minuter för inaktivitet i den här referensen. Om det redan finns en fil eller katalog på den angivna sökvägen och har overwrite angetts till false, löste det här anropet ett undantag med RESOURCE_ALREADY_EXISTS . Ett vanligt arbetsflöde för filuppladdning är:

  1. Anropa create och hämta en referens.
  2. Gör ett eller flera tilläggsblocks-anrop med den referens som du har.
  3. Anropa Close med den referens som 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 }

Begärandestruktur

Fältnamn Typ Beskrivning
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.
skriva över BOOL Flaggan som anger om befintliga filer eller filer ska skrivas över.

Svarsstruktur

Fältnamn Typ Beskrivning
Hantera INT64 Hantera som därefter ska skickas till och add-block anropar close 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 kastar ett undantag med om sökvägen är en icke-tom katalog och rekursiv är inställd på IO_ERROR 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 anropa borttagningsåtgärden igen tills katalogstrukturen har tagits bort helt. Ett 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 fler än 10 000 filer rekommenderar vi inte att du använder DBFS REST API, men rekommenderar att du utför sådana åtgärder i kontexten för ett kluster med filsystemverktyget (dbutils.fs). dbutils.fs omfattar den funktionella omfattningen för DBFS-REST API, men från notebook-filer. Att köra sådana åtgärder med notebook-filer ger bättre kontroll och hanterbarhet, till exempel selektiva borttagningar och möjligheten att automatisera periodiska borttagningsjobb.

Exempel

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

Begärandestruktur

Fältnamn Typ Beskrivning
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 rekursivt ta bort katalogens innehåll. 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 kastar 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
}

Begärandestruktur

Fältnamn Typ Beskrivning
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 Beskrivning
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 epok millisekunder, ändrades filen eller katalogen.

Lista

Slutpunkt HTTP-metod
2.0/dbfs/list GET

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

När du list anropar på en stor katalog list tar åtgärden en time out efter cirka 60 sekunder. Vi rekommenderar starkt att du endast använder kataloger som innehåller färre än 10 000 filer och rekommenderar inte att DBFS-REST API för åtgärder som innehåller fler än list 10 000 filer. I stället rekommenderar vi att du utför sådana åtgärder i kontexten för ett kluster med filsystemsverktyget (dbutils.fs), som tillhandahåller samma funktioner utan någon tidsinställning.

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

Begärandestruktur

Fältnamn Typ Beskrivning
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 Beskrivning
filer En matris med FileInfo En lista med 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 löste det här anropet ett undantag med RESOURCE_ALREADY_EXISTS . Om den här åtgärden misslyckas kan det ha lyckats skapa några av de nödvändiga överordnade katalogerna.

Exempel

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

Begärandestruktur

Fältnamn Typ Beskrivning
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 inom DBFS. Om källfilen inte finns kastar det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST . Om det redan finns en fil i målsökvägen kastar 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 tar API-anropet slut 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 DBFS-REST API. I stället rekommenderar vi att du utför sådana åtgärder i kontexten för ett kluster med filsystemsverktyget (dbutils.fs) från en notebook-fil, som ger samma funktioner utan någon tidsinställning.

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

Begärandestruktur

Fältnamn Typ Beskrivning
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.

Placera

Slutpunkt HTTP-metod
2.0/dbfs/put POST

Ladda upp en fil med hjälp av multipart formulär post. Den används främst för direktuppladdningar, men kan även användas som ett enkelt anrop för datauppladdning.

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

Exempel

Så här laddar du upp en lokal fil HelloWorld.txt med namnet 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 Hello, World! upp innehåll 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 Beskrivning
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 kan saknas och i stället används en publicerad fil.
skriva ö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 kastar det här anropet ett undantag med RESOURCE_DOES_NOT_EXIST . Om sökvägen är en katalog, läslängden är negativ, eller om förskjutningen är negativ kastar det här anropet ett undantag med INVALID_PARAMETER_VALUE . Om läslängden överskrider 1 MB kastar 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 Beskrivning
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 som ska läsas 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 Beskrivning
bytes_read INT64 Antalet lästa byte (kan vara mindre än längden om vi trycker på slutet av filen). Detta avser antalet byte som lästs i en okodad version (svarsdata är base64-kodade).
data BYTES Det base64-kodade innehållet i den lästa filen.

Datastrukturer

I det här avsnittet:

FileInfo

Attributen för en fil eller katalog.

Fältnamn Typ Beskrivning
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 epok millisekunder, ändrades filen eller katalogen.