Przewodnik po API rekordów

Rekord to cyfrowy zapis jednego fizycznego przedmiotu — składnika majątku, części, dokumentu lub elementu przepływu pracy. Zawiera nazwę i opis, typowane dane pól, załączone pliki, powiązane identyfikatory oraz historię zdarzeń. Właścicielem rekordów jest zespół, więc każde żądanie wymaga tokenu Bearer oraz nagłówka Dust-Ctx-Org-Id (i Dust-Ctx-Team-Id, aby działać jako konkretny zespół) — zobacz Uwierzytelnianie i Konwencje.

Ten przewodnik omawia główne przepływy. Wszystkie parametry i schematy odpowiedzi znajdziesz w dokumentacji API.

Punkty końcowe w skrócie

Operacja	Metoda i ścieżka
Utwórz jeden lub wiele rekordów	`POST /api/v1/threads`
Wyświetl / wyszukaj rekordy	`GET /api/v1/threads`
Policz rekordy	`GET /api/v1/threads/count`
Pobierz jeden rekord	`GET /api/v1/threads/{thread_id}`
Aktualizuj metadane i pola	`POST /api/v1/threads/{thread_id}`
Aktualizuj tylko pola	`POST /api/v1/threads/{thread_id}/data`
Wyświetl zarchiwizowane dane pól	`GET /api/v1/threads/{thread_id}/data/archived`
Przywróć zarchiwizowane dane pól	`POST /api/v1/threads/{thread_id}/data/restore`
Archiwizuj rekordy	`PATCH /api/v1/threads/archive`
Przywróć rekordy	`PATCH /api/v1/threads/restore`
Sprawdź uprawnienia wywołującego	`POST /api/v1/threads/permissions`
Sygnał obecności	`POST /api/v1/threads/{thread_id}/presence`
Wyświetl pliki rekordu	`GET /api/v1/threads/{thread_id}/files`
Ustaw / prześlij miniaturę	`PATCH` / `POST /api/v1/threads/{thread_id}/thumbnail`

Aktualizacje miniatury akceptują autoryzowany resourceId lub osadzony obraz rastrowy w base64 w polu imageUri o rozmiarze maksymalnie 5 MiB po zdekodowaniu. Zdalne adresy URL obrazów są odrzucane. Przesyłanie plików pozostaje dostępne przez punkt końcowy przesyłania miniatury. Miniatury oparte na zasobie podlegają bieżącym uprawnieniom do odczytu zasobu źródłowego: gdy dostęp zostanie odmówiony lub źródło nie jest już załączone, odpowiedzi zwracają null zarówno dla thumbnail, jak i thumbnailId. Przesłane miniatury bez zasobu źródłowego podlegają widoczności rekordu.

Tworzenie rekordu

POST /api/v1/threads przyjmuje trzy postacie treści, wybierane przez type: single (jeden rekord), list (wiele znormalizowanych rekordów) i raw (płaskie wpisy klucz-wartość). Wszystkie trzy przyjmują opcjonalny bundleId, aby utworzyć rekordy w folderze.

curl
TypeScript

curl -fsS "$APID_URL/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "thread": { "name": "Tire SZ3J-11-ZJ17" },
    "data": [
      { "name": "Serial Number", "type": "text", "value": { "text": "SZ3J-11-ZJ17" } },
      { "name": "Max PSI", "type": "number", "value": { "number": 51 } }
    ]
  }'

const created = await client.threads.create({
  type: "single",
  thread: { name: "Tire SZ3J-11-ZJ17" },
  data: [
    { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
    { name: "Max PSI", type: "number", value: { number: 51 } },
  ],
});

Wartości pól są zagnieżdżone w value zgodnie z typem — { "text": … }, { "number": … } itd. Specyfikacja definiuje dane wejściowe dla tekstu, długiego tekstu, liczby, wartości logicznej, daty, zakresu dat, daty z godziną, godziny, czasu trwania, adresu e-mail, telefonu, URL, JSON, listy wyboru, wielokrotnego wyboru, słów kluczowych, odwołań do zasobów (plików) i odwołań do rekordów.

Import zbiorczy

Użyj type: "list", gdy masz już znormalizowane obiekty { thread, data }, lub type: "raw", aby przekazać do API płaskie wpisy — API tworzy pola na podstawie par klucz-wartość każdego obiektu, używając nameKey i descriptionKey (domyślnie name / description) dla metadanych samego rekordu:

{
  "type": "raw",
  "nameKey": "serial",
  "raw": [
    { "serial": "SZ3J-11-ZJ17", "part": "P355/30R19", "maxPsi": 51 }
  ]
}

Aby niepodzielnie zaimportować całe struktury złożeń, zobacz POST /api/v1/imports/plan i POST /api/v1/imports/commit w dokumentacji.

Odczytywanie rekordów

GET /api/v1/threads/{thread_id} zwraca rekord wraz z danymi jego pól (opcjonalny parametr zapytania maxEvents dołącza ostatnie zdarzenia). GET /api/v1/threads zwraca listę z paginacją kursorową (cursor, pageSize, order, orderCol) i obsługuje filtry, w tym:

Filtr	Znaczenie
`q`, `queryCol`	Wyszukiwanie tekstowe, opcjonalnie ograniczone do jednej kolumny
`bundleId`	Rekordy w folderze lub kategorii
`templateId`	Rekordy utworzone z szablonu
`tagType`	Rekordy z powiązanym identyfikatorem tego typu
`hasResources`	Rekordy z załączonymi plikami
`includeArchived`, `archivedOnly`	Widoczność zarchiwizowanych
`createdBy`, `ownedByTeam`	Filtry pochodzenia
`excludeTransferred`, `transferredOnly`	Rekordy wysłane dalej
`withActiveShipment`	Dodaje do każdego elementu jego aktywną przesyłkę, jeśli istnieje

GET /api/v1/threads/count przyjmuje te same filtry i zwraca tylko liczbę — przydatne w pulpitach i podsumowaniach paginacji.

Aktualizowanie rekordu

Dwa punkty końcowe, jeden cel podzielony na dwa:

POST /api/v1/threads/{thread_id} — przyjmuje { thread, update?, remove? }: metadane rekordu (nazwę, opis, szablon, …) oraz opcjonalne zmiany pól w jednym wywołaniu.
POST /api/v1/threads/{thread_id}/data — tylko pola: { threadId, update, remove?, expectedUpdatedAt? }. Pola w update są wstawiane lub aktualizowane (dopasowywane według nazwy/ID); remove przyjmuje ID pól.

{
  "threadId": "9f6a…",
  "update": [
    { "name": "VIN", "type": "text", "value": { "text": "1HGCM82633A004352" } }
  ],
  "remove": []
}

Zarchiwizowane dane pól

Usunięcie pola archiwizuje je zamiast trwale niszczyć. GET /api/v1/threads/{thread_id}/data/archived zwraca listę zarchiwizowanych pól, a POST /api/v1/threads/{thread_id}/data/restore przywraca je według ID ({ threadId, restore: ["field-id", …] }).

Archiwizowanie i przywracanie rekordów

Archiwizowanie działa zbiorczo i jest odwracalne:

PATCH /api/v1/threads/archive — { threadIds: […], toggle? }. Z toggle: true zarchiwizowane rekordy z listy są przywracane z archiwum, a aktywne archiwizowane — w jednym wywołaniu.
PATCH /api/v1/threads/restore — przywraca zarchiwizowane rekordy.

Zarchiwizowane rekordy znikają z domyślnych list; użyj includeArchived lub archivedOnly, aby je zobaczyć.

Uprawnienia

Przed wyświetleniem kontrolek edycji lub próbą zapisu w wielu rekordach sprawdź, co wywołujący może faktycznie zrobić:

curl -fsS "$APID_URL/api/v1/threads/permissions" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "threadIds": ["9f6a…", "c2d1…"] }'

POST /api/v1/threads/permissions zwraca efektywne uprawnienia wywołującego dla każdego rekordu w bieżącym kontekście zespołu. Powiązane odczyty: GET /api/v1/threads/{thread_id}/access (które zespoły zapewniają dostęp) i GET /api/v1/threads/{thread_id}/shared (komu udostępniono rekord) — oba opisano w sekcji Zespoły, udostępnianie i połączenia.

Obecność

POST /api/v1/threads/{thread_id}/presence to sygnał obecności: wysyłaj go okresowo, gdy użytkownik wyświetla rekord (opcjonalnie z wyświetlanymi name / image oraz z leaving: true przy wyjściu), a odpowiedź zawiera listę bieżących osób przeglądających rekord. DICE używa tego do wskaźnika „kto jeszcze tu jest”.

Pliki i miniatury

Pliki są załączane do rekordów za pomocą API plików; odczyty po stronie rekordu opisano tutaj:

GET /api/v1/threads/{thread_id}/files — pliki rekordu z paginacją kursorową (includeArchived jest wymagany).
GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — odczyt i aktualizacja pojedynczego załączonego pliku.
POST /api/v1/threads/{thread_id}/thumbnail — przesyła obraz (multipart, pole thumbnail) i w jednym kroku ustawia go jako miniaturę rekordu.
PATCH /api/v1/threads/{thread_id}/thumbnail — ustawia miniaturę na podstawie istniejącego ID zasobu lub URI obrazu.

Model podstawowy — jak rekordy łączą się ze wszystkim innym
Przewodnik po API identyfikatorów — wiązanie fizycznych identyfikatorów z rekordami
Przewodnik po API plików — przesyłanie i pobieranie
Dokumentacja API — pełne schematy wszystkich powyższych punktów końcowych

Pomoc techniczna i zgłoszenia Zgłoś problem z dokumentacją