# Prześlij dokumenty ze swoich systemów Source: https://nordvec.com/pl/docs/guides/how-to/push-documents Utwórz źródło danych, prześlij do niego dokumenty za pomocą klucza API do indeksowania, wybierz, kto może je czytać, i wstrzymaj je lub usuń, gdy źródło się zmieni. Interfejs push API indeksuje dokumenty z systemów, dla których Nordvec nie ma łącznika: eksport wewnętrznej wiki, archiwum zgłoszeń, baza notatek. Przesyłasz tekst i informację, kto może go przeczytać; Nordvec przechowuje go w UE, indeksuje i sprawia, że jest przeszukiwalny i cytowalny jak każdy inny dokument. Każdy przesłany dokument trafia do **źródła danych**, nazwanej przestrzeni w Twojej przestrzeni roboczej, którą najpierw tworzy administrator przestrzeni roboczej. Przesłanie, które wskazuje źródło danych nieistniejące lub wstrzymane, jest odrzucane. ## Utwórz źródło danych [#utwórz-źródło-danych] Otwórz **Ustawienia przestrzeni roboczej > Źródła danych** i wybierz **Utwórz źródło danych**. Mogą to zrobić administratorzy i właściciele przestrzeni roboczej; w osobistej przestrzeni roboczej to ty. | Pole | Uwagi | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Nazwa | To, co widzą użytkownicy na liście ustawień. Do 200 znaków. | | Slug | To, co każde przesłanie wskazuje. Małe litery, cyfry, `-` i `_`, zaczynające się od litery lub cyfry, do 200 znaków. Nie można go później zmienić. | Slug `confluence-export` jest używany w przykładach poniżej. ## Utwórz klucz API do indeksowania [#utwórz-klucz-api-do-indeksowania] Uwierzytelnianie żądań push odbywa się za pomocą klucza API klasy **Indexing**, który zawiera zakres `index:write`. Dodaj `index:status`, aby śledzić proces indeksowania, oraz `index:delete`, aby usuwać dokumenty lub zastępować cały źródło danych. Utwórz go w **Ustawieniach przestrzeni > Klucze API**. Surowy klucz zaczyna się od `nv_eu_idx_` i jest wyświetlany tylko raz. Więcej informacji znajdziesz w [Uwierzytelnianiu](/docs/guides/authentication). Każde żądanie musi również zawierać identyfikator twojej przestrzeni roboczej jako `tenantId`, czyli identyfikator z adresu przestrzeni w aplikacji (`/w//...`), i musi to być przestrzeń, do której należy klucz. ## Prześlij jeden dokument [#prześlij-jeden-dokument] `/documents/push` tworzy dokument lub aktualizuje go, gdy dokument o tym samym `id` już istnieje w źródle danych. ```bash curl https://nordvec.com/api/v1/documents/push \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: page-4711-2026-09-28" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "document": { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/markdown", "content": "# Travel expenses\n..." }, "permissions": {}, "sourceUrl": "https://wiki.example.com/pages/4711", "type": "policy" } }' ``` ```json { "documentId": "page-4711", "status": "queued", "updated": false } ``` * `id` to Twój stabilny identyfikator dokumentu w źródle danych. Ponowne przesłanie tego samego `id` aktualizuje go; niezmieniona treść jest rozpoznawana po jej skrócie i nie jest indeksowana dwukrotnie. * `body.mimeType` to jeden z `text/plain`, `text/markdown`, `text/html`, `application/pdf` lub typy Word, Excel i PowerPoint (`.docx`, `.xlsx`, `.pptx`). Zawartość binarna jest przesyłana zakodowana base64. * `sourceUrl` staje się linkiem "przejdź do źródła" przy każdym cytowaniu dokumentu. Pomiń go przy ponownym przesłaniu, aby zachować zapisany, lub wyślij `null`, aby go wyczyścić. * `type` ustawia `content_type` dokumentu, według którego przeszukiwanie i filtrowanie listy są filtrowane. Całe ciało żądania jest ograniczone do 1 MB, więc duży plik lub duża partia odpowiada `413`; podziel ją. ## Wybierz, kto może go przeczytać [#wybierz-kto-może-go-przeczytać] `permissions` jest wymagane przy każdym przesłaniu, więc decyzja o udostępnieniu nigdy nie jest podejmowana przez pominięcie pola. W źródle danych widocznym dla przestrzeni roboczej: | `permissions` | Kto może przeczytać dokument | | ----------------------------------------- | -------------------------------------------------------------------- | | `{}` | Każdy członek przestrzeni roboczej | | `{ "allowedUsers": ["ana@example.com"] }` | Tylko wymienione osoby | | `{ "allowedGroups": ["GROUP_ID"] }` | Członkowie tych grup przestrzeni roboczej, w tym grup zagnieżdżonych | | `{ "allowAllTenantMembers": false }` | Odrzucane: dokument, którego nikt nie może przeczytać, jest usuwany | Aby zmienić, kto może przeczytać dokument bez ponownego wysyłania jego treści, użyj `POST /documents/push/permissions`. Udostępnienie dokumentu już ograniczonego całej przestrzeni roboczej wymaga dodatkowo zakresu `index:acl-widen`, więc rutynowa synchronizacja nie może potajemnie cofnąć ograniczenia ustawionego ręcznie. ## Prześlij w partiach [#prześlij-w-partiach] `/documents/push/bulk` przyjmuje do 100 dokumentów dla jednego źródła danych na jedno wywołanie. Odpowiedź zlicza `accepted` i `rejected` i podaje wynik dla każdego dokumentu, więc jeden zły dokument nie powoduje niepowodzenia całej partii. Limit 1 MB na ciało żądania obowiązuje na jedno wywołanie, więc podziel duże przesyłki na kilka wywołań z tym samym `uploadId`. ```bash curl https://nordvec.com/api/v1/documents/push/bulk \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "uploadId": "nightly-2026-09-28", "datasource": "confluence-export", "documents": [ { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/plain", "content": "..." }, "permissions": {} } ] }' ``` ## Zastąp całe źródło danych [#zastąp-całe-źródło-danych] Gdy twój system może wyświetlić pełną listę dokumentów, które powinno zawierać źródło danych, wyślij całą listę jako jedną **sesję przesyłania**. Dokumenty, których nie ma już na liście, zostaną przeniesione do kosza po zamknięciu sesji. Sesje wymagają klucza API do indeksowania z uprawnieniami `index:delete` oraz `index:write`, ponieważ zamknięcie sesji usuwa dokumenty. Tylko klucz, który ją otworzył, może ją kontynuować. 1. Wyślij pierwszą stronę z `"isFirstPage": true`. To strona `0`. 2. Wyślij każdą kolejną stronę z jej `pageIndex` (`1`, `2`, ...), w dowolnej kolejności. Strona wysłana dwukrotnie jest liczona raz, więc ponowienie jest zawsze bezpieczne. 3. Wyślij ostatnią stronę z `"isLastPage": true` i jej `pageIndex`. Lista, która mieści się na jednej stronie, wysyła `isFirstPage` i `isLastPage` razem. Ostatnia strona może nie zawierać dokumentów. Każda strona używa tego samego `uploadId`, a każda odpowiedź zawiera postęp sesji w polu `upload`. Sesja zamyka się dopiero po otrzymaniu wszystkich stron od `0` do ostatniej. Zamknięcie sesji przenosi do kosza każdy dokument ze źródła danych, który nie został wymieniony w żadnej stronie sesji i istniał przed jej otwarciem. Każde inne żądanie push do źródła danych podczas trwania sesji zachowuje dokument, który wskazuje: pojedyncze żądanie push, wsad bez pól sesji, aktualizację uprawnień czy ponowne przesłanie niezmienionej treści. Kosz przechowuje usunięte dokumenty przez 30 dni. Ponowne przesłanie dokumentu przywraca go, podobnie jak przywrócenie całej sesji (patrz poniżej). Sesja, która nie otrzyma żadnej strony przez 24 godziny, wygasa i zamyka się bez usuwania czegokolwiek. Odrzucona strona otrzymuje odpowiedź z `409 Conflict`, nic nie zapisuje, a jej `data.reason` wyjaśnia przyczynę: | `reason` | Co zrobić | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_incomplete` | Wyślij strony wymienione w `missingPageIndexes`, a następnie ponownie ostatnią stronę | | `deletion_confirmation_required` | Zamknięcie sesji usunęłoby ponad 20% źródła danych. Jeśli to poprawne, wyślij ostatnią stronę ponownie z `"confirmDeletions"` ustawionym na `wouldTombstone` | | `deletion_confirmation_too_large` | `confirmDeletions` jest większe niż liczba dokumentów, które źródło danych zawierało w momencie otwarcia sesji. Wyślij oczekiwaną liczbę dokumentów do usunięcia | | `upload_in_progress` | Na tym źródle danych trwa inna sesja. Jeśli należy do twojego klucza, zakończ ją, poczekaj na jej wygaśnięcie lub rozpocznij od nowa z `"forceRestartUpload": true` w pierwszej stronie. Jeśli otworzył ją inny klucz, `forceRestartUpload` zastąpi ją dopiero po godzinie braku aktywności, od czasu podanego w `restartableAt` | | `upload_expired`, `upload_missing`, `upload_restarted` | Sesja została usunięta. Rozpocznij nową z nowym `uploadId` | | `upload_closed`, `upload_id_reused` | `uploadId` został wykorzystany. Użyj nowego | | `page_index_required` | Twój klucz ma otwartą sesję na tym źródle danych. Wyślij `pageIndex` wraz ze stroną | Aby wznowić po awarii, odczytaj sesję za pomocą `GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (zakres `index:status`). Jej `missingPageIndexes` zawiera listę stron, które nadal trzeba wysłać. ### Cofnij zamknięcie sesji [#cofnij-zamknięcie-sesji] Jeśli sesja usunęła dokumenty, których nie powinna, na przykład dlatego, że przesłana lista była niekompletna, przywróć je jednym wywołaniem: ```bash curl https://nordvec.com/api/v1/documents/push/upload/restore \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "datasource": "confluence-export", "uploadId": "nightly-2026-09-28" }' ``` Klucz, który otworzył sesję, może ją przywrócić, podobnie jak administrator przestrzeni roboczej zalogowany do Nordvec, w przypadku sesji otwartej przez dowolny klucz. Każdy dokument, który zamknięcie przeniosło do kosza, wraca z treścią, jaką miał, a odpowiedź zlicza je: `restored` są ponownie aktywne, `purged` zostały już trwale usunięte przez kosz, a `skipped` zmieniły się od czasu zamknięcia (zostały ponownie przesłane lub usunięte) i pozostały w obecnym stanie. Przywrócenie sesji po raz drugi odpowiada zliczeniami z pierwszego przywrócenia i `"replayed": true`, a także kolejkuje każdy przywrócony dokument, który nadal czeka na indeksowanie, więc powtórzenie przywracania, które nie zakończyło się odpowiedzią, jest bezpieczne. Sesję można przywrócić w ciągu 35 dni od jej zamknięcia oraz tak długo, jak kosz nadal przechowuje jakikolwiek dokument, który usunęła. Odmowa przywrócenia jest sygnalizowana odpowiedzią `409 Conflict` i jej `data.reason`: | `reason` | Co to oznacza | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_not_closed` | Sesja nigdy nie została zamknięta, więc nic nie usunęła | | `upload_in_progress` | Sesja jest otwarta na źródle danych. Przywróć ją po zamknięciu lub wygaśnięciu | | `restore_purged` | Minęło ponad 30 dni, a kosz usunął wszystkie dokumenty. Prześlij je ponownie | | `workspace_not_entitled` | Plan przestrzeni roboczej nie pozwala obecnie na przywracanie z kosza | | `corpus_cap_exceeded` | Przywrócenie dokumentów przekroczyłoby limit dokumentów przestrzeni roboczej, więc żaden nie wrócił. `data.wouldRestore` to liczba potrzebnych miejsc, a `data.headroom` to liczba dostępnych miejsc. Zwolnij miejsce, a następnie spróbuj przywrócić ponownie | ## Śledź ingestię [#śledź-ingestię] Przesłanie odpowiada, gdy tylko dokument zostanie zakolejkowany. Sprawdź jego postęp za pomocą `GET /documents/push/status` (zakres `index:status`), filtrowanego według źródła danych lub identyfikatora dokumentu. Dokument przechodzi ze stanu `queued` przez `processing` do `completed` lub do `failed` z `error`. ## Gdy przesłanie jest odrzucane [#gdy-przesłanie-jest-odrzucane] Przesłanie, które wskazuje nieznane lub wstrzymane źródło danych, jest odrzucane z odpowiedzią `422 Unprocessable Content`. Wiadomość zawiera slug i link do **Ustawienia przestrzeni roboczej > Źródła danych** w Twojej przestrzeni roboczej, a `data` błędu mówi, dlaczego i co zrobić: ```json { "defined": true, "code": "UNPROCESSABLE_CONTENT", "status": 422, "message": "Datasource \"confluence-export\" is paused and accepts no documents. A workspace admin resumes it under Workspace settings > Datasources: https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources", "data": { "why": "The datasource \"confluence-export\" is paused", "fix": "Resume it at https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources, then retry the push", "link": "https://nordvec.com/docs/guides/how-to/push-documents" } } ``` Nie ponawiaj tych automatycznie: udają się tylko po tym, jak administrator utworzy lub wznowi źródło danych. ## Usuń dokument [#usuń-dokument] `POST /documents/push/delete` (zakres `index:delete`) usuwa wypchnięty dokument za pomocą jego `datasource` i `id`. Dokumenty, których przestajesz wypychać, nie są usuwane automatycznie: usuń każdy, który wycofujesz, lub wyślij pełną listę źródła danych jako sesję przesyłania, jak opisano powyżej. ## Wstrzymaj, wznów i usuń [#wstrzymaj-wznów-i-usuń] * **Wstrzymaj** odrzuca każde dalsze przesłanie do źródła danych. Jego dokumenty pozostają przeszukiwalne. Przesłanie już zapisywane w momencie wstrzymania zostanie ukończone. * **Wznów** ponownie akceptuje przesłania. * **Usuń** usuwa źródło danych i każdy przesłany do niego dokument, wraz z ich indeksem wyszukiwania. Twój własny system zachowuje swoją kopię, więc ponowne przesłanie po odtworzeniu źródła danych przywraca je. Usunięcia nie można cofnąć. Jeśli inny administrator zmienił źródło danych po załadowaniu Twojej listy, akcja jest odrzucana, a lista jest ponownie ładowana, więc decydujesz ponownie na podstawie tego, co jest teraz. Każde utworzenie, wstrzymanie, wznowienie i usunięcie jest rejestrowane w dzienniku audytu przestrzeni roboczej. Lista ustawień pokazuje, komu widoczne jest każde źródło danych. Kto może przeczytać przesłany dokument, decyduje `permissions` przesłany wraz z nim; tworzenie, wstrzymywanie lub usuwanie źródła danych nigdy nie poszerza dostępu do niczego. Zapisy push są idempotentne: powtórz to samo `Idempotency-Key` przy każdej próbie jednego zapisu, a duplikat jest odpowiadany z pierwszej próby zamiast być stosowany dwukrotnie. Zobacz [Błędy i limity szybkości](/docs/guides/errors-and-rate-limits). ## Następne kroki [#następne-kroki]