Przewodnik po API plików

Pliki (w niektórych schematach nazywane zasobami, ang. resources) przechowują materiały dowodowe załączone do rekordów: obrazy, pliki PDF, dokumenty i artefakty skanowania. Plik można załączyć bezpośrednio do rekordu lub przypisać do pola typu zasób jako jego wartość.

Istnieją dwie ścieżki przesyłania: proste, jednorazowe żądanie POST dla małych plików oraz wznawialny protokół tus dla dużych. Pełne schematy: dokumentacja referencyjna API.

Punkty końcowe w skrócie

Operacja	Metoda i ścieżka
Proste przesyłanie	POST /api/v1/files
Wznawialne przesyłanie (tus)	POST /api/v1/files/upload, a następnie PATCH /api/v1/files/upload/{id}
Finalizacja przesyłania tus	POST /api/v1/files/finalize
Pobieranie	GET /api/v1/files/{resource_id}/download
Podpisane adresy URL	POST /api/v1/files/urls
Wyszukiwanie plików	GET /api/v1/files/search
Lista plików (kursor)	GET /api/v1/files
Lista plików rekordu	GET /api/v1/threads/{thread_id}/files

Żądania dotyczące plików wymagają bieżącego członkostwa w wybranym zespole, który musi należeć do wybranej organizacji. Dotyczy to zarówno osób, jak i kont usług. Przesyłanie do rekordu wymaga uprawnień do edycji; prywatne przesyłanie musi wskazywać rekord i wymaga uprawnień do zarządzania jego prywatnymi zasobami. Niezałączone pliki może odczytać zespół, do którego należą, tylko wtedy, gdy nie są prywatne.

Proste przesyłanie

W przypadku plików, które bez problemu zmieszczą się w jednym żądaniu, wyślij żądanie POST typu multipart/form-data z polem file i opcjonalnymi miejscami docelowymi załączenia. Odpowiedź zawiera utworzony zasób z podpisanym adresem URL:

curl

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

TypeScript

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId przypisuje plik do pola typu zasób jako jego wartość; isPrivate ogranicza jego widoczność.

Wznawialne przesyłanie (tus)

Duże pliki są przesyłane za pomocą wznawialnego protokołu przesyłania tus 1.0 pod adresem /api/v1/files/upload, po czym wywołanie finalizacji zamienia ukończone przesyłanie w rekord zasobu. Przebieg wygląda następująco: przesłanie → finalizacja → (plik jest już załączony lub przypisujesz go do pól).

1. Utwórz przesyłanie. Wyślij żądanie POST z nagłówkami tus; wartości Upload-Metadata są kodowane w base64, a filename jest wymagane (opcjonalnie fieldId, threadId, isPrivate):

   curl -i -X POST "$APID_URL/api/v1/files/upload" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 52428800" \
     -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
   # → 201 Created
   # → Location: …/api/v1/files/upload/<upload-id>

   Zachowaj <upload-id> z nagłówka Location na potrzeby finalizacji. Ostateczna odpowiedź podaje stały identyfikator zasobu, który może się od niego różnić. Docelowy rekord, pole i ustawienie prywatności zadeklaruj podczas tworzenia; nie można ich zmienić podczas finalizacji. Upload-Length musi być dodatnią, znaną liczbą bajtów.

2. Wyślij bajty (wznawialnie — kolejne żądania PATCH kontynuują od Upload-Offset):

   curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" \
     -H "Content-Type: application/offset+octet-stream" \
     --data-binary @video.mp4

   Żądania przesyłania tolerują dłuższe przerwy w aktywności. Aby wznowić przesyłanie po przerwaniu, wyślij żądanie HEAD na ten sam adres URL, aby odczytać bieżącą wartość Upload-Offset, a następnie kontynuuj od tego miejsca żądaniem PATCH. Każda biblioteka kliencka tus 1.0 (np. tus-js-client) obsługuje ten protokół za ciebie.

3. Sfinalizuj. Przesłane pliki stają się rekordami zasobów dopiero po finalizacji:

   curl -fsS "$APID_URL/api/v1/files/finalize" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "'"$THREAD_ID"'",
       "requests": [
         { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
       ]
     }'

   POST /api/v1/files/finalize przyjmuje wiele przesłań naraz; każdy element żądania przyjmuje identyfikator przesyłania tus jako resId oraz filename i size (opcjonalnie fieldId, isPrivate). Nazwa pliku, rozmiar, rekord, pole i ustawienie prywatności muszą być zgodne z żądaniem utworzenia przesyłania. Do utworzenia, wysyłania fragmentów, żądań HEAD i DELETE oraz finalizacji używaj tej samej uwierzytelnionej tożsamości i tego samego kontekstu organizacji/zespołu. Sesje przesyłania wygasają po siedmiu dniach od utworzenia. Sfinalizować można tylko ukończone przesłania.

   Identyczna ponowna próba finalizacji w tym okresie zwraca pierwotne zasoby z nowymi podpisanymi adresami URL. Partia musi zawierać albo wyłącznie nowe ukończone przesłania, albo wyłącznie przesłania już sfinalizowane. Sfinalizowanych przesłań nie można modyfikować żądaniem PATCH ani przerywać za pomocą protokołu tus.

Notatka

Punkty końcowe tus komunikują się za pomocą protokołu tus, a nie JSON, dlatego w dokumentacji referencyjnej API są opisane tylko skrótowo. Opisane powyżej zachowanie wynika z konfiguracji tus na serwerze (/upload i /upload/{id} w ramach /api/v1/files).

Pobieranie i podpisane adresy URL

• GET /api/v1/files/{resource_id}/download — przekierowanie do podpisanego adresu URL pliku.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — generuje krótkotrwałe podpisane adresy URL do bezpośredniego dostępu do magazynu obiektów; używaj ich, gdy przeglądarka lub system odbiorcy potrzebuje zawartości pliku bez pośrednictwa serwera proxy.

Uwaga

Podpisane adresy URL wygasają. Przechowuj identyfikatory zasobów, a nigdy podpisane adresy URL — gdy potrzebujesz nowego dostępu, ponownie zażądaj adresów URL.

Wyszukiwanie i wyświetlanie list

Dostępne są dwa style zapytań:

• GET /api/v1/files/search — wyszukiwanie z paginacją według numerów stron, z parametrami q, threadId, mimeFilters i includeArchived.
• GET /api/v1/files — lista z paginacją opartą na kursorze (cursor, pageSize; parametr includeArchived jest wymagany), filtrowana według threadId lub createdBy.

W przypadku plików w kontekście jednego rekordu lepiej użyć GET /api/v1/threads/{thread_id}/files (zobacz przewodnik po API rekordów).

Powiązane strony

• Przewodnik po API rekordów — przypisywanie plików do pól rekordu i ustawianie miniatur
• Model podstawowy — miejsce plików w modelu domeny
• Dokumentacja referencyjna API — pełne szczegóły parametrów i schematów