backfill_items służy do jednorazowego początkowego wczytania elementów na tablicę, na przykład przed rozpoczęciem jej codziennego użytkowania. Nie jest przeznaczone do regularnego importowania danych. W tym celu użyj ingest_items.

Import początkowy różni się od ingest na dwa ważne sposoby:

• Automatyzacje nie są uruchamiane dla elementów utworzonych podczas importu początkowego.
• Utworzenie elementów nie jest rejestrowane w dzienniku aktywności (Activity Log).

Dzięki temu import początkowy sprawdza się przy jednorazowej migracji danych, gdy chcesz wczytać dane na tablicę bez wywoływania wielu zdarzeń automatyzacji. Porównanie obu procesów znajdziesz w przewodniku Importowanie elementów zbiorczo.

Proces importu początkowego jest asynchroniczny:

1. Uruchom zadanie za pomocą backfill_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, używając job_id, aż zadanie osiągnie stan końcowy.

Obsługiwane typy kolumn

Board Relation, Date, Dropdown, Email, Link, Long Text, Number, People, Phone, Status, Text i Timeline. Wiersze zawierające nieobsługiwane typy kolumn mogą nie przejść walidacji.

Działanie endpointu

• Maksymalna liczba wierszy w przesłanym pliku: 20 000
• Maksymalny rozmiar pliku: 150 MB
• Ważność adresów upload_url i report_url: 10 minut
• Wymagany zakres uprawnień: boards:write oraz rola administratora konta
• Funkcja nie obsługuje on_match - każdy wiersz tworzy nowy element.
• Import nie jest wliczany do godzinowego limitu tworzenia i aktualizowania elementów na konto, który obowiązuje w przypadku ingest.
• Obsługiwane są importy hierarchii, które tworzą wyłącznie elementy na tablicach z podelementami na wielu poziomach. Użyj kolumn poziomów od name.l1 do name.l5. Pełny format CSV znajdziesz w przewodniku Importowanie elementów zbiorczo.
• Obsługiwane są kolumny Board Relation. Format wartości CSV i ograniczenia znajdziesz w przewodniku Importowanie elementów zbiorczo.

---

Zapytania

Pobieranie stanu zadania

Użyj fetch_job_status, aby sprawdzić stan zadania importu początkowego. Zwraca ono typ union JobStatus, obecnie zaimplementowany jako ItemsJobStatus.

• Wymagany zakres uprawnień: boards:read
• Zwraca typ union JobStatus
• Można je wywołać bezpośrednio tylko na najwyższym poziomie; nie można zagnieżdżać go 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 zwrócony przez backfill_items.

Pola (ItemsJobStatus)

Pole	Typ	Opis
counts	ItemsJobItemCounts	Liczba wierszy na poszczególnych etapach (submitted, invalid, skipped, created, updated, failed).
failure_message	String	Szczegóły błędu w czytelnej dla człowieka formie. Wartość null dla INTERNAL_ERROR.
failure_reason	BulkImportFailureReason	Przyczyna błędu w formie odczytywanej przez maszynę, gdy stan to FAILED lub REJECTED.
fully_imported	Boolean	Wartość true tylko wtedy, gdy stan to COMPLETED, a counts.failed wynosi 0.
progress_percentage	Int	Przybliżony procent ukończenia (0–100).
report_created	Boolean	Informacja, czy dostępny jest raport do pobrania.
report_url	String	Adres URL pliku raportu ważny przez ograniczony czas (10 minut).
status	BulkImportState	Obecny stan zadania.

---

Mutacje

Wymagany zakres uprawnień: boards:write (tylko administrator konta)

Import początkowy elementów

Uruchamia zadanie importu początkowego i zwraca UploadJobInit zawierające job_id i wstępnie podpisany adres upload_url.

mutation {
  backfill_items(board_id: "1234567890", group_id: "topics") {
    job_id
    upload_url
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Docelowa tablica.
group_id	ID!	Docelowa grupa dla nowo utworzonych elementów.

Pola odpowiedzi

Pole	Typ	Opis
job_id	ID	Identyfikator używany z 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 jako niepodpisanego nagłówka żądania może spowodować, że S3 odrzuci przesyłanie błędem HTTP 403.

---

Importy hierarchii podelementów na wielu poziomach

Informacje o formacie pliku MLS i zasadach hierarchii znajdziesz w sekcji dotyczącej tablic z podelementami na wielu poziomach w przewodniku Importowanie elementów zbiorczo. backfill_items nadal jest dostępne tylko dla administratorów i nie uruchamia automatyzacji ani nie rejestruje tworzenia elementów w dzienniku aktywności.

---

Limity pojemności i szybkości

• Wywołania uruchamiające zadania. backfill_items i ingest_items podlegają wspólnemu limitowi 100 pomyślnych wywołań uruchamiających zadanie na konto w ciągu godziny. Przekroczenie limitu zwraca RATE_LIMIT_EXCEEDED (HTTP 429) wraz z extensions.retryAfterMs.
• Limit tworzenia i aktualizowania elementów. Import początkowy nie zużywa limitu 19 000 elementów na godzinę, z którego korzysta ingest_items.
• Rozmiar pliku. Pliki większe niż 150 MB są odrzucane z wartością failure_reason: FILE_TOO_LARGE.

---

Zobacz też

• Importowanie elementów zbiorczo - pełny przewodnik krok po kroku
• Dokumentacja API ingest_items - zalecane rozwiązanie do bieżących integracji
• Pozostałe typy importu zbiorczego - obiekty wejściowe, typy wyników i wartości wyliczeniowe