Prześlij dokumenty ze swoich systemów

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.

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.

Slug confluence-export jest używany w przykładach poniżej.

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. Każde żądanie musi również zawierać identyfikator twojej przestrzeni roboczej jako tenantId, czyli identyfikator z adresu przestrzeni w aplikacji (/w/<workspace id>/...), i musi to być przestrzeń, do której należy klucz.

/documents/push tworzy dokument lub aktualizuje go, gdy dokument o tym samym id już istnieje w źródle danych.

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

{ "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ą.

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:

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.

/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.

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

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ę:

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 sesjiKopiuj link do tego nagłówka

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:

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:

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.

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ć:

{
  "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.

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 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.