ingest_items to domyślny sposób zbiorczego tworzenia lub aktualizowania elementów za pomocą API platformy. Operacja uwzględnia wszystkie skutki uboczne po stronie platformy - uruchamia automatyzacje, a dziennik aktywności zapisuje każdą zmianę. Dlatego sprawdza się przy integracjach działających na bieżąco i cyklicznym imporcie.

Do jednorazowego, początkowego wczytania danych przez administratora, które pomija automatyzacje i dziennik aktywności, użyj backfill_items. Porównanie obu procesów znajdziesz w przewodniku Zbiorcze importowanie elementów.

Proces importowania jest asynchroniczny:

1. Uruchom zadanie za pomocą ingest_items. Otrzymasz job_id i wstępnie podpisany adres upload_url.
2. Prześlij plik CSV na adres upload_url.
3. Odpytuj fetch_job_status za pomocą job_id, aż zadanie osiągnie stan końcowy.

Obsługiwane typy kolumn

Relacja z tablicą, Data, Lista rozwijana, E-mail, Link, Długi tekst, Liczba, Osoby, Telefon, Status, Tekst i Oś czasu. Wiersze zawierające nieobsługiwane typy kolumn mogą nie przejść walidacji.

Działanie endpointu

• Maksymalna liczba wierszy w przesyłanym pliku: 10 000
• Maksymalny rozmiar pliku: 150 MB
• Adresy URL przesyłania i raportu wygasają po: 10 minutach
• Wymagany zakres uprawnień: boards:write
• Opcjonalny parametr on_match umożliwia aktualizowanie istniejących elementów lub pomijanie duplikatów na podstawie wartości kolumn w zwykłym imporcie elementów.
• Import wlicza się do godzinowego limitu tworzenia i aktualizowania elementów na konto (19 000 elementów na godzinę).
• Obsługuje import hierarchii tylko do tworzenia elementów na tablicach z wielopoziomowymi podelementami. Użyj kolumn poziomów od name.l1 do name.l5. Pełny format CSV znajdziesz w przewodniku Zbiorcze importowanie elementów.
• Obsługuje kolumny Relacja z tablicą. Format wartości CSV i ograniczenia znajdziesz w przewodniku Zbiorcze importowanie elementów.

---

Zapytania

Pobieranie statusu zadania

Użyj fetch_job_status, aby sprawdzić status zadania importowania. Zwraca ono typ union JobStatus, którego aktualną implementacją jest ItemsJobStatus.

• Wymagany zakres uprawnień: boards:read
• Zwraca typ union JobStatus.
• Można go odpytywać bezpośrednio tylko na poziomie głównym; nie można go zagnieżdżać w innym zestawie wyboru.

query {
  fetch_job_status(job_id: "550e8400-e29b-41d4-a716-446655440000") {
    ... on ItemsJobStatus {
      status
      counts {
        submitted
        invalid
        skipped
        created
        updated
        failed
      }
      progress_percentage
      failure_reason
      failure_message
      fully_imported
      report_created
      report_url
    }
  }
}

Argumenty

Argument	Typ	Opis
job_id	ID!	Identyfikator zadania zwracany przez ingest_items

Pola (ItemsJobStatus)

Pole	Typ	Opis
counts	ItemsJobItemCounts	Liczba wierszy na poszczególnych etapach (przesłane, nieprawidłowe, pominięte, utworzone, zaktualizowane, nieudane).
failure_message	String	Czytelny dla człowieka opis błędu. Wartość null dla INTERNAL_ERROR.
failure_reason	BulkImportFailureReason	Powód niepowodzenia w formacie czytelnym dla maszyny, gdy status to FAILED lub REJECTED.
fully_imported	Boolean	Wartość true tylko wtedy, gdy status to COMPLETED, a counts.failed wynosi 0.
progress_percentage	Int	Przybliżony procent ukończenia (0–100).
report_created	Boolean	Informuje, czy istnieje raport do pobrania.
report_url	String	Adres URL raportu, który wygasa po 10 minutach.
status	BulkImportState	Bieżący stan zadania.

---

Mutacje

Wymagany zakres uprawnień: boards:write

Importowanie elementów

Uruchamia zadanie importowania i zwraca UploadJobInit z wartościami job_id i wstępnie podpisanym upload_url.

mutation {
  ingest_items(
    board_id: "1234567890"
    group_id: "topics"
    on_match: { behaviour: UPSERT, match_column_id: "email" }
  ) {
    job_id
    upload_url
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Tablica docelowa.
group_id	ID!	Grupa docelowa dla nowo utworzonych elementów. Nie ogranicza wyszukiwania wykonywanego przez on_match.
on_match	OnMatchInput	Opcjonalna reguła dopasowywania w zwykłym imporcie elementów. W przypadku importu hierarchii MLS pomiń on_match - import MLS zawsze tworzy nowe elementy hierarchii.

Pola odpowiedzi

Pole	Typ	Opis
job_id	ID	Identyfikator używany przez fetch_job_status.
upload_url	String	Wstępnie podpisany adres URL do przesłania pliku CSV metodą PUT. Wygasa po 10 minutach.

Podczas przesyłania pliku na wstępnie podpisany adres URL nie dodawaj x-amz-checksum-crc32 jako nagłówka żądania. Adres URL może zawierać parametry zapytania dotyczące sumy kontrolnej, ale przekazanie jej w niepodpisanym nagłówku żądania może spowodować, że S3 odrzuci przesyłanie błędem HTTP 403.

---

on_match

W zwykłym imporcie elementów parametr on_match pozwala aktualizować istniejące elementy lub pomijać duplikaty zamiast za każdym razem tworzyć nowy element. Jest dostępny tylko w ingest_items. backfill_items ignoruje reguły dopasowywania i zawsze tworzy nowe elementy.

W przypadku importu hierarchii MLS pomiń on_match. Import MLS zawsze tworzy nowe elementy hierarchii i nie dopasowuje, nie pomija ani nie aktualizuje elementów.

Zakres dopasowywania

Dopasowywanie odbywa się w obrębie całej tablicy. Argument group_id określa, gdzie zostaną dodane nowo utworzone elementy. Nie ogranicza wyszukiwania istniejących elementów.

Na przykład, jeśli on_match używa match_column_id: "email", a taki sam adres e-mail znajduje się w innej grupie na tablicy, istniejący element może zostać dopasowany nawet wtedy, gdy group_id wskazuje inną grupę.

OnMatchInput

Pole	Typ	Opis
behaviour	OnMatchBehaviour!	UPSERT aktualizuje dopasowany element; SKIP pomija wiersz, jeśli istnieje dopasowanie.
match_column_id	String!	Identyfikator kolumny używany do wykrywania dopasowań (np. email, phone lub dowolna obsługiwana kolumna).

OnMatchBehaviour

Wartość enum	Opis
UPSERT	Aktualizuje istniejący dopasowany element. Jeśli nie ma dopasowania, tworzy nowy element.
SKIP	Pomija wiersz, jeśli istnieje dopasowany element.

UPSERT i puste komórki

W trybie UPSERT, jeśli komórka danych jest pusta lub zawiera tylko białe znaki, kolumna jest pomijana. Istniejąca wartość dopasowanego elementu zostaje zachowana i nie jest nadpisywana.

UPSERT i czyszczenie wartości kolumn

W trybie UPSERT komórka danych zawierająca dokładnie ciąg <NULL> czyści wartość kolumny w dopasowanym elemencie.

Obsługiwane typy kolumn do dopasowywania

E-mail, Telefon, Tekst, Nazwa, Liczby, Link, Data, Długi tekst i Status. Jako match_column_id użyj identyfikatora kolumny z tablicy.

Uwagi dotyczące działania

• Wiersze z pustą wartością dopasowania są traktowane jako nowe elementy.
• Jeśli wiele wierszy w pliku wejściowym ma tę samą wartość dopasowania, używany jest tylko ostatni wiersz z tą wartością. Wcześniejsze wiersze są pomijane.
• Jeśli więcej niż jeden element na tablicy ma pasującą wartość, aktualizowany jest element utworzony najpóźniej.
• group_id nie jest częścią klucza dopasowania.

---

Import hierarchii wielopoziomowych podelementów

Opis formatu pliku MLS i reguł hierarchii znajdziesz w sekcji „Tablice z wielopoziomowymi podelementami” w przewodniku Zbiorcze importowanie elementów.

---

Limity pojemności i częstotliwości żądań

• Zadania uruchamiane w ciągu godziny. ingest_items i backfill_items mają wspólny limit 100 pomyślnych wywołań uruchamiających zadanie na konto na godzinę. Przekroczenie limitu zwraca RATE_LIMIT_EXCEEDED (HTTP 429) z extensions.retryAfterMs.
• Limit tworzenia i aktualizowania elementów. ingest_items rezerwuje zasoby z godzinowego limitu 19 000 elementów na konto. Jeśli liczba prawidłowych wierszy w zadaniu przekroczyłaby pozostały limit, zadanie zostanie odrzucone z failure_reason: ACCOUNT_CAPACITY_EXCEEDED. Zasoby zarezerwowane dla wierszy, które ostatecznie zakończą się niepowodzeniem, zostaną pominięte lub okażą się nieprawidłowe, są zwalniane.

---

Zobacz też

• Zbiorcze importowanie elementów - pełny przewodnik krok po kroku
• Dokumentacja API backfill_items - jednorazowe wczytywanie danych przez administratora
• Pozostałe typy importu zbiorczego - obiekty wejściowe, typy wyników i wartości enum

---

Zapytanie job_status

Zapytanie job_status pozwala sprawdzić status ogólnego zadania asynchronicznego za pomocą jego zewnętrznego identyfikatora. W przeciwieństwie do fetch_job_status, które dotyczy zadań importu zbiorczego, job_status to uniwersalny endpoint do sprawdzania statusu dowolnej operacji asynchronicznej zwracającej identyfikator zadania.

• Wymagany zakres uprawnień: boards:read
• Zwraca AsyncJobStatus!.
• Można go odpytywać bezpośrednio tylko na poziomie głównym.

query {
  job_status(job_id: "YOUR_JOB_ID") {
    id
    status
    created_at
    updated_at
    error
    result {
      total
      succeeded
      failed
    }
  }
}

Argumenty

Argument	Typ	Opis
job_id	ID!	Unikalny identyfikator zadania asynchronicznego, którego status chcesz sprawdzić.

Pola

Pole	Typ	Opis
id	ID	Unikalny identyfikator zadania.
status	JobState	Bieżący status zadania. Poniżej znajdziesz wartości enum JobState.
created_at	String	Znacznik czasu w formacie ISO 8601 określający, kiedy utworzono zadanie.
updated_at	String	Znacznik czasu w formacie ISO 8601 określający, kiedy ostatnio zaktualizowano zadanie.
error	String	Opis błędu, jeśli zadanie się nie powiodło. Zwraca null, jeśli zadanie zakończyło się powodzeniem.
result	AsyncJobResult	Ustrukturyzowane dane wynikowe ukończonych lub częściowo ukończonych operacji.

Wartości enum JobState

Wartość	Opis
PENDING	Zadanie jest w kolejce, ale jeszcze się nie rozpoczęło.
RUNNING	Trwa przetwarzanie zadania.
COMPLETED	Zadanie zakończyło się powodzeniem.
FAILED	Wystąpił błąd kończący zadanie.
EXPIRED	Wynik zadania wygasł i nie jest już dostępny.
CANCELLED	Zadanie anulowano przed jego ukończeniem.

Pola AsyncJobResult

Pole	Typ	Opis
total	Int	Łączna liczba przetworzonych elementów.
succeeded	Int	Liczba elementów przetworzonych pomyślnie.
failed	Int	Liczba elementów, których nie udało się przetworzyć.
details	JSON	Dodatkowe, ustrukturyzowane informacje o wyniku zadania.