Użyj interfejsu API Files z woluminami Unity Catalog

Użyj Files API, aby czytać, zapisywać, listować i usuwać pliki oraz katalogi według ścieżek. Działa z plikami w woluminach Unity Catalog, do których odwołujesz się za pomocą ich bezwzględnej ścieżki woluminu, takich jak /Volumes/<catalog>/<schema>/<volume>/<path>. Żądania interfejsu API Files 3.0 używają prefiksu punktu końcowego /api/3.0/fs i są kierowane do regionalnej nazwy hosta Twojego workspace. Dla każdej operacji, parametru i nagłówka zobacz odniesienie do Files API 3.0.

Korzystanie z API Files może wiązać się z opłatami za transfer danych Azure Databricks.

Wysyłaj żądania do regionalnej nazwy hosta

Wysyłaj żądania interfejsu Send Files API 3.0 do regionalnej nazwy hosta przestrzeni roboczej, do której należy użytkownik wysyłający żądanie. Regionalna nazwa hosta ma następujący format:

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

Na przykład 1234567890123456.storage.westus.azuredatabricks.net.

Aby znaleźć identyfikator i region swojego workspace, użyj konsoli konta. Zobacz Nazwy wystąpień obszaru roboczego, adresy URL i identyfikatory. Możesz także znaleźć identyfikator workspace w adresie URL wdrożenia: w https://<databricks-instance>/?o=1234567890123456 liczba po o= to identyfikator workspace. Interfejs workspace pokazuje region poniżej nazwy workspace.

Konfigurowanie łączności sieciowej

API Files 3.0 wymaga łączności sieciowej z twojej sieci do Azure Databricks oraz z Azure Databricks do twojej pamięci masowej.

Z Twojej sieci do Azure Databricks

Jeśli zezwalasz na publiczny dostęp z internetu do swojej przestrzeni roboczej, ale ograniczasz go zaporą, dodaj zakresy IP płaszczyzny sterowania dla swojego regionu do listy dozwolonych.

Uwzględnij adresy IP w ramach adresów IP płaszczyzny sterowania, w tym domyślny magazyn i aplikację internetową. Zobacz Ruch przychodzący do płaszczyzny sterowania usługi Azure Databricks.

Jeśli nie zezwalasz na dostęp do internetu do Azure Databricks i łączysz się przez prywatne łącze front-end, utwórz drugie prywatne łącze front-end dla usług o wysokich wymaganiach wydajnościowych. Zobacz Konfigurowanie przychodzącego łącza prywatnego dla usług wymagających wysokiej wydajności.

Z usługi Azure Databricks do twojego magazynu

Jeśli zezwalasz na publiczny dostęp do swojego magazynu, ale stosujesz ograniczenia sieciowe, w przypadku magazynu w tym samym regionie dodaj konta magazynu do obwodu zabezpieczeń sieciowych platformy Azure (NSP), a następnie dodaj tag usługi AzureDatabricksServerless do listy dozwolonych. Perymetr zabezpieczeń sieci musi pozostać w trybie Transition. W przeciwnym razie dodaj do listy dozwolonych wychodzące adresy IP usługi Azure Databricks.

Jeśli nie zezwalasz na publiczny dostęp do swojego magazynu, skonfiguruj usługę Private Link dla swojego magazynu Azure. Zobacz Konfigurowanie łączności prywatnej z zasobami platformy Azure.

Przesyłaj duże pliki z przesyłaniem wieloczęściowym

Jedno żądanie przesłania umożliwia przesłanie plików do 5000 MiB. Aby przesłać większy plik lub plik o nieznanym rozmiarze w momencie rozpoczęcia przesyłania, użyj przesyłania wieloczęściowego: przesyłasz plik w częściach, a Azure Databricks łączy te części w jeden plik.

Numery części wahają się od 1 do 10000. Każda część oprócz ostatniej musi mieć co najmniej 5 MiB, a każda część może mieć maksymalnie 4000 MiB. Azure Databricks składa części w rosnącej kolejności numerów części. Dla każdego parametru zobacz Przekaż plik oraz Wykonaj akcję na pliku.

Przykład przesyłania wieloczęściowego

Poniższy przykład przesyła plik w dwóch częściach.

Aby rozpocząć sesję przesyłania, rozpocznij jej przesyłanie. Odpowiedź zawiera element upload_id, który identyfikuje sesję:

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

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

Aby przesłać pierwszą część, wyślij jej zawartość za pomocą upload_id i part_number. Odpowiedź zawiera elementy części ETag:

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"

Aby przesłać drugą część, ponów żądanie z następnym 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"

Aby zakończyć, dokończ przesyłanie treścią, która zawiera listę wszystkich elementów i zapisane w nim ETag:

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"

W tej odpowiedzi ETag odnosi się do całego zmontowanego pliku, a nie do części. Możesz go użyć w późniejszych żądaniach warunkowych, na przykład do nadpisania pliku tylko wtedy, gdy nie zmienił się od momentu jego przesłania.

Aby anulować przesyłanie zamiast je ukończyć, wyślij akcję abort-upload z upload_id:

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

200 OK

Pobieraj duże pliki przy użyciu żądań zakresowych

Użyj żądań zakresu, aby pobrać duży plik w kilku mniejszych żądaniach lub wznowić przerwane pobieranie.

Poproś o zakres

Wyślij nagłówek Range z pozycjami liczonymi od zera dla pierwszego i ostatniego bajtu, których potrzebujesz. Zakres obejmuje obie pozycje. Na przykład żąda bytes=0-1048575 pierwszego 1 MiB pliku o rozmiarze 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>

Odpowiedź 206 Partial Content zawiera jedynie żądane bajty i Content-Range pokazuje, które bajty zawiera oraz całkowity rozmiar pliku. Aby odczytać do końca pliku, pomiń ostatnią pozycję, jak w bytes=1048576-. Jeśli ostatnia pozycja jest po końcu pliku, odpowiedź zawiera bajty do końca. Informacje o innej składni Range znajdziesz w artykule Download a file.

Żądanie HEAD z nagłówkiem Range zwraca ten sam status i nagłówki co odpowiadające GET żądanie, bez treści ciała.

Wznowij przerwane pobieranie

Aby wznowić pobieranie, zażądaj pozostałych bajtów, używając zakresu zaczynającego się od pierwszego bajtu, którego nie otrzymałeś. Wyślij też If-Match wraz z ETag z pierwszej odpowiedzi, żeby nie łączyć bajtów z dwóch wersji pliku:

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>

Jeśli plik się zmienił, serwer zwraca 412 Precondition Failed, i musisz rozpocząć pobieranie od nowa.

Używaj żądań warunkowych

Żądanie warunkowe ma zastosowanie tylko wtedy, gdy plik jest w stanie, jakiego oczekujesz. Używaj żądań warunkowych, aby uniknąć powtarzających się pobrań, zapobiec nadpisywaniu zmian przez równoczesnych użytkowników zapisujących oraz bezpiecznie tworzyć lub usuwać pliki. API Files 3.0 obsługuje cztery standardowe nagłówki warunkowe HTTP z RFC 9110:

Gdy warunek nie jest spełniony, serwer nie wykonuje operacji i zwraca jeden z następujących statusów:

• 304 Not Modified, gdy żądanie GET lub HEAD z parametrem If-None-Match lub If-Modified-Since nie powiedzie się. Twoja kopia w pamięci podręcznej nadal jest ważna.
• 412 Precondition Failed, gdy jakikolwiek inny warunek zawodzi.

Walidatorzy: ETag i Last-Modified

Nagłówki warunkowe porównują wartość podaną przez Ciebie z jednym z walidatorów pliku. API Files zwraca oba walidatory jako nagłówki odpowiedzi na GET i HEAD:

• ETag: nieprzezroczysty identyfikator zawartości pliku, również zwracany w PUT oraz w odpowiedzi wieloczęściowej complete-upload. Przechowuj go dokładnie tak, jak został zwrócony, wraz z otaczającymi cudzysłowami, i nie analizuj ani nie konstruuj go.
• Last-Modified: ostatni czas modyfikacji pliku jako data HTTP. Jej precyzja to jedna sekunda, więc If-Modified-Since i If-Unmodified-Since nie mogą wykryć kilku zmian w tej samej sekundzie. Dla sterowania współbieżnością użyj ETag z If-None-Match lub If-Match.

Odczyty warunkowe

Najczęstszym odczytem warunkowym jest rewalidacja pamięci podręcznej. Wyślij If-None-Match z ETag swojej kopii z pamięci podręcznej lub If-Modified-Since z godziną, gdy ostatnio ją pobrałeś. Jeśli plik pozostaje niezmieniony, serwer zwraca 304 Not Modified bez treści. W przeciwnym razie zwraca 200 OK z nową zawartością:

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

304 Not Modified

If-Match i If-Unmodified-Since działa to w drugą stronę: serwer zwraca plik tylko wtedy, gdy nie uległ zmianie, a w przeciwnym razie zwraca 412. Odczyt może zawierać maksymalnie dwa warunkowe nagłówki, a ich pierwszeństwo jest określone zgodnie z RFC 9110.

Zapisy warunkowe

Na PUT, używaj If-None-Match i If-Match, aby uniknąć nadpisywania zmian, których nie zauważyłeś, zwanych także problem utraconej aktualizacji:

• If-None-Match: * przesyła plik tylko wtedy, gdy na ścieżce nie ma żadnego pliku. W przeciwnym razie w odpowiedzi na żądanie zwracane jest 412 Precondition Failed.
• If-Match: <etag> przesyła plik tylko wtedy, gdy bieżąca wartość ETag jest zgodna z podaną. W przeciwnym razie żądanie zwraca 412 Precondition Failed, lub 404 jeśli na ścieżce nie ma pliku.

Aby utworzyć plik tylko wtedy, gdy jeszcze nie istnieje, wyślij 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

Aby nadpisać plik tylko wtedy, gdy jest to wersja, którą ostatnio pobierałeś, wyślij jego ETag z 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

Dla przesyłania wieloczęściowego wyślij warunkowy nagłówek w wywołaniu initiate-upload. API Files ocenia go po zakończeniu przesyłania, więc warunek dotyczy zmontowanego pliku. Aby poznać formy nagłówków obsługiwane przez każde wywołanie, zobacz Upload a file oraz Perform an action on a file.

Usunięcia warunkowe

Samo DELETE kończy się powodzeniem nawet wtedy, gdy plik nie istnieje, więc nie pozwala stwierdzić, czy usunięto zamierzoną wersję. Aby wykonać warunkowe usunięcie, wyślij If-Match:

• If-Match: <etag> Usuwa plik tylko wtedy, gdy jego aktualny ETag odpowiada temu, który podajesz. Jeśli ktoś zmienił plik po jego pobraniu, żądanie zwraca 412 Precondition Failed. Jeśli plik już nie istnieje, zwraca 404.
• If-Match: * usuwa plik tylko wtedy, gdy istnieje, i zwraca 404 , jeśli nie istnieje.

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

204 No Content

Wersje interfejsu Files API

API Files 2.0 wysyła żądania do nazwy hosta twojej przestrzeni roboczej z prefiksem punktu końcowego /api/2.0/fs. Nie obsługuje przesyłania wieloczęściowego, a jego jedynym nagłówkiem warunkowym przy pobieraniu jest If-Unmodified-Since. Zobacz odniesienie do API Files 2.0.

Aby przenieść kod z Files API 2.0 do Files API 3.0, wprowadź następujące zmiany:

• Wysyłaj żądania do regionalną nazwę hosta z prefiksem punktu końcowego /api/3.0/fs i konfiguruj łączność sieciową.
• Wysyłaj nagłówek Content-Length przy każdym przesyłaniu. Jeśli nie znasz rozmiaru pliku z wyprzedzeniem, użyj multipart upload.
• Spodziewaj się 200 OK zamiast 204 No Content po pomyślnym przesłaniu.
• Spodziewaj się 204 No Content, a nie 404 Not Found, gdy usuwasz plik, który nie istnieje. Zobacz Usuwanie warunkowe.