Zaloguj się
Nowe zgłoszenie
Dokumentacja dla programistów›Poradniki›Importowanie elementów zbiorczo
Dokumentacja dla programistów

Importowanie elementów zbiorczo

PoradnikiDokumentacja API
Aktualizacja 2026-09-06

Dostępne wyłącznie w wersjach API 2026-07 i nowszych

Za pomocą API platformy możesz importować duże ilości elementów na tablicę monday.com w asynchronicznym, trzyetapowym procesie:

  1. Rozpocznij zadanie importu (ingest_items lub backfill_items) i odbierz wstępnie podpisane wartości upload_url oraz job_id.
  2. Prześlij plik CSV pod adres upload_url.
  3. Sprawdzaj status zadania za pomocą fetch_job_status.

API udostępnia dwa sposoby rozpoczęcia importu. ingest_items to domyślna metoda w niemal każdym przypadku. backfill_items służy do jednorazowego, początkowego importu, który może uruchomić tylko administrator konta - na przykład do wypełnienia tablicy przed rozpoczęciem jej codziennego używania.

Wybór metody importu

ingest_items (zalecana) backfill_items
Zastosowanie Integracje, cykliczne importy oraz tworzenie lub aktualizowanie elementów w ramach zwykłej pracy na tablicy Jednorazowy, duży import początkowy przed rozpoczęciem pracy użytkowników lub automatyzacji na tablicy
Maksymalna liczba wierszy w zadaniu 10,000 20,000
Kto może wywołać tę metodę Każdy użytkownik z uprawnieniami do edycji tablicy przez API (boards:write) Administrator konta oraz boards:write
Aktualizowanie istniejących elementów lub ich pomijanie Zwykłe importy elementów: tak, za pomocą on_match. Importy klasycznych podelementów i hierarchii MLS: tylko tworzenie. Nieobsługiwane; zawsze tworzy nowe elementy
Godzinowy limit tworzenia i aktualizowania elementów Wlicza się do limitu 19,000 elementów na konto na godzinę Nie pomniejsza tego limitu
Wpływ na inne funkcje monday.com Brak Automatyzacje nie są uruchamiane. Utworzenie elementów nie jest zapisywane w dzienniku aktywności.

Obsługiwane typy kolumn

Oba punkty końcowe obsługują następujące typy kolumn:

  • Relacja z tablicą
  • Pole wyboru
  • Data
  • Lista rozwijana
  • E-mail
  • Link
  • Lokalizacja
  • Długi tekst
  • Liczba
  • Osoby
  • Telefon
  • Status
  • Tekst
  • Oś czasu

Wiersze zawierające nieobsługiwane typy kolumn mogą nie przejść walidacji. Format CSV dla poszczególnych typów znajdziesz w sekcji Walidacja typów kolumn.

Ograniczenia

Kategoria backfill_items ingest_items
Maksymalna liczba wierszy w pliku 20,000 10,000
Maksymalny rozmiar pliku 150 MB 150 MB
Ważność adresu URL do przesyłania pliku 10 minut 10 minut
Ważność adresu URL raportu 10 minut 10 minut
Liczba zadań rozpoczynanych na konto na godzinę 100 (wspólny limit z ingest_items) 100 (wspólny limit z backfill_items)
Godzinowy limit tworzenia i aktualizowania elementów Nie jest pomniejszany 19,000 elementów na konto
Maksymalna liczba elementów w imporcie klasycznych podelementów 20,000 (łącznie elementy nadrzędne i podelementy) 10,000 (łącznie elementy nadrzędne i podelementy)
Maksymalna liczba elementów w imporcie hierarchii MLS 5,000 5,000
Maksymalna liczba podelementów na element nadrzędny Limit podelementów na koncie Limit podelementów na koncie

Uwagi

  • Rozmiar pliku jest sprawdzany przez usługę importu po przesłaniu pliku, a nie przez sam adres URL do przesyłania. Zbyt duże pliki są odrzucane z wartością failure_reason: FILE_TOO_LARGE.
  • Nie można anulować trwającego zadania.
  • Limity liczby elementów w imporcie hierarchii obowiązują niezależnie od maksymalnej liczby wierszy w pliku.
  • Limit podelementów na element nadrzędny zależy od planu i jest taki sam jak limit obowiązujący w interfejsie. Element, którego liczba podelementów przekracza ten limit, zostaje odrzucony razem z wierszami jego podelementów.

Pierwsze kroki

Wymagania wstępne

Krok 1: Rozpocznij zadanie importu

  1. Pobierz wartości board_id i group_id, które wskazują, gdzie mają zostać dodane nowe elementy. W tym celu wykonaj zapytanie boards i groups.
  2. Wywołaj ingest_items, chyba że potrzebujesz jednorazowego importu początkowego dostępnego tylko dla administratora - w takim przypadku użyj backfill_items.
  3. Zapisz zwrócone wartości job_id i upload_url. Adres upload_url jest ważny tylko przez 10 minut.

Przykład użycia ingest (metoda domyślna)

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

Jeśli podasz on_match, dopasowanie jest sprawdzane na całej tablicy. group_id określa tylko, gdzie zostaną dodane nowe wiersze. Nie ogranicza zakresu dopasowania ani nie przenosi dopasowanych elementów.

Przykład użycia backfill (tylko jednorazowy import początkowy)

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

Krok 2: Prześlij plik CSV

Prześlij plik CSV pod adres upload_url zwrócony w kroku 1.

PUT <upload_url>
Content-Type: text/csv

<CSV file content>

Pomyślne przesłanie pliku zwraca kod HTTP 200 i nagłówek ETag.

HTTP/1.1 200 OK
ETag: "abc123def456"

Podczas przesyłania pliku pod wstępnie podpisany adres URL nie dodawaj nagłówka żądania x-amz-checksum-crc32. Adres URL może zawierać parametry zapytania z sumą kontrolną, ale przekazanie sumy kontrolnej w niepodpisanym nagłówku żądania może spowodować odrzucenie przesyłania przez S3 z kodem HTTP 403.

Krok 3: Monitoruj status importu

Wysyłaj zapytanie fetch_job_status co około 10 sekund, aż zadanie osiągnie stan końcowy (COMPLETED, FAILED lub REJECTED).

query {
  fetch_job_status(job_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7") {
    ... on ItemsJobStatus {
      status
      counts {
        submitted
        invalid
        skipped
        created
        updated
        failed
      }
      progress_percentage
      failure_reason
      failure_message
      fully_imported
      report_created
      report_url
    }
  }
}

Gdy report_created ma wartość true, jak najszybciej pobierz plik z adresu report_url. Adres raportu wygasa po 10 minutach.

Dokumentacja

Format CSV

  • Wymagane jest kodowanie UTF-8.
  • Jako separatora kolumn używaj przecinka (,).
  • Wartości zawierające przecinki, cudzysłowy lub znaki nowej linii ujmuj w cudzysłowy. Cudzysłów występujący wewnątrz wartości zastąp dwoma cudzysłowami ("").

Nagłówki

W przypadku zwykłych importów elementów:

  • Pierwszą wartością nagłówka musi być name.
  • Pozostałe wartości nagłówków muszą dokładnie odpowiadać wartościom column_id na tablicy (z uwzględnieniem wielkości liter).
  • Aby pobrać prawidłowe identyfikatory kolumn na docelowej tablicy, wykonaj zapytanie columns.

Nagłówki CSV muszą używać dokładnych identyfikatorów kolumn zwróconych przez zapytanie columns dla tablicy, a nie wyświetlanych nazw kolumn. Identyfikatory kolumn są przypisane do konkretnych tablic, więc nie ustalaj ich na podstawie typu ani nazwy kolumny.

Informacje o importach z podelementami znajdziesz w sekcji Tablice z klasycznymi podelementami. W nagłówkach podelementów użyj przyrostka .subitem.

Informacje o tablicach z wielopoziomowymi podelementami znajdziesz w sekcji Tablice z wielopoziomowymi podelementami. W importach hierarchii MLS użyj nagłówków name.l1, name.l2 i kolejnych poziomów aż do name.l5, aby określić hierarchię.

Wiersze

  • W zwykłych importach elementów pierwsza wartość w każdym wierszu to nazwa elementu.
  • Pozostałe wartości wiersza odpowiadają identyfikatorom kolumn z nagłówka.
  • Puste wartości są dozwolone. Wartości składające się wyłącznie z białych znaków są traktowane jako puste.
  • W trybie UPSERT (tylko ingest_items) pusta komórka w dopasowanym wierszu jest ignorowana - istniejąca wartość kolumny pozostaje bez zmian.
  • W trybie UPSERT komórka zawierająca dokładnie tekst <NULL> czyści wartość kolumny w dopasowanym elemencie.

Przykład

name,text,status,date,email,numeric,dropdown
Task 1,Description text,Working on it,2025-12-31,alice@monday.com,100,"Option A, Option B"
Task 2,Another task,Done,2026-01-15,bob@monday.com,200,Option C
Task 3,Third task,Stuck,2026-02-28,carol@monday.com,300,
Task 4,,,,,,

Tablice z klasycznymi podelementami

Import zbiorczy elementów pozwala tworzyć elementy razem z ich podelementami. Przyrostek .subitem wskazuje, które nagłówki i wiersze dotyczą podelementów. Informacje o tablicach z wielopoziomowymi podelementami znajdziesz w sekcji Tablice z wielopoziomowymi podelementami.

Użyj tych nagłówków:

  • name - nazwa elementu. Jest wymagana i może wystąpić tylko raz.
  • <column_id> - kolumna elementu.
  • name.subitem - nazwa podelementu. Dodaj ten nagłówek tylko wtedy, gdy plik zawiera wiersze podelementów.
  • <column_id>.subitem - kolumna podelementu. Wymaga nagłówka name.subitem.
name,status,name.subitem,text.subitem
Parent A,Done,,
,,Sub 1,First subitem of Parent A
,,Sub 2,Second subitem of Parent A
Parent B,Working on it,,
,,Sub 3,First subitem of Parent B

Zasady importowania klasycznych podelementów:

  • Każdy wiersz reprezentuje jeden element. W wierszu elementu wypełnij name, a kolumny podelementów pozostaw puste. W wierszu podelementu pozostaw name puste i wypełnij name.subitem. Wiersz, w którym wypełniono oba pola, zostaje odrzucony, a wiersz, w którym nie wypełniono żadnego z nich, zostaje pominięty.
  • Powiązania między elementami nadrzędnymi i podelementami są ustalane na podstawie kolejności wierszy. Wiersz podelementu jest przypisywany do najbliższego wiersza elementu znajdującego się powyżej. Wiersz podelementu, który występuje przed jakimkolwiek wierszem elementu, zostaje odrzucony.
  • Klasyczne podelementy obsługują dokładnie jeden poziom zagnieżdżenia. Nagłówki poziomów, takie jak name.l1 i name.l2, są niedozwolone. Jeśli występują w pliku, cały plik zostaje odrzucony.
  • Nagłówki .subitem muszą używać identyfikatorów kolumn podelementów. Aby je pobrać, wykonaj zapytanie columns na tablicy podelementów.
  • Wartość umieszczona w wierszu niewłaściwego typu jest ignorowana. Wartość .subitem w wierszu elementu ani wartość kolumny bez przyrostka w wierszu podelementu nie zostanie zapisana.
  • group_id określa, gdzie zostaną dodane nowe elementy. Nie dotyczy podelementów.
  • Import klasycznych podelementów umożliwia tylko tworzenie. Nie używaj on_match, UPSERT ani SKIP w pliku zawierającym nagłówki .subitem.
  • Jeśli wiersz elementu zostanie odrzucony lub jego przetwarzanie się nie powiedzie, jego podelementy nie zostaną utworzone. Raport wskaże wiersz elementu, który spowodował problem.
  • Nagłówki są dopasowywane bez uwzględniania wielkości liter, w tym przyrostek .subitem.
  • Plik bez nagłówka name.subitem jest traktowany jak zwykły import elementów.
  • Tablica musi już mieć kolumnę podelementów.
  • W raporcie zadania przyrostek .subitem pozostaje w nazwach kolumn podelementów.

Tablice z wielopoziomowymi podelementami

Import zbiorczy elementów pozwala tworzyć elementy na tablicach, które obsługują wielopoziomowe podelementy. Na takich tablicach hierarchię w pliku CSV określają kolumny poziomów, a nie jedna kolumna z nazwami elementów.

Użyj name.l1 dla elementów najwyższego poziomu, name.l2 dla ich elementów podrzędnych, name.l3 dla kolejnego poziomu i tak dalej - aż do name.l5. Tablice MLS obsługują obecnie maksymalnie 5 poziomów hierarchii. Nagłówek name jest również akceptowany jako kolumna elementów najwyższego poziomu, ale w plikach MLS zalecamy używanie name.l1, aby zapis był bardziej czytelny.

name.l1,name.l2,name.l3,status,text
Project A,,,,Top-level item
,Phase 1,,,Child item
,,Task 1,Stuck,Grandchild item
,,Task 2,Working on it,Another grandchild
,Phase 2,,Done,Another child
Project B,,,Working on it,Second top-level item

Zasady importowania hierarchii MLS:

  • Każdy wiersz reprezentuje jeden element. Wpisz nazwę elementu w kolumnie odpowiadającej jego poziomowi hierarchii, a pozostałe kolumny poziomów pozostaw puste.
  • Powiązania między elementami nadrzędnymi i podrzędnymi są ustalane na podstawie kolejności wierszy. Element nadrzędny wiersza to najnowszy wcześniejszy wiersz z poprzedniego poziomu.
  • W tym samym wierszu możesz podać wartości zwykłych kolumn, używając identyfikatorów kolumn z tablicy.
  • Import hierarchii MLS umożliwia tylko tworzenie. Nie używaj on_match, UPSERT ani SKIP w importach hierarchii MLS.
  • W wierszach tworzących elementy nadrzędne nie podawaj wartości kolumn z włączonym podsumowaniem. Wartości elementów nadrzędnych są obliczane na podstawie elementów podrzędnych, a wiersze zawierające takie wartości mogą zostać odrzucone.

Walidacja typów kolumn

Typ kolumny Format wartości CSV Zasady walidacji
Relacja z tablicą Rozdzielone przecinkami odwołania do połączonych elementów. W kolumnach wskazujących jedną tablicę docelową można użyć identyfikatorów elementów lub ich dokładnych nazw. W kolumnach wskazujących wiele tablic docelowych wymagany jest format board_id:item_id lub board_id:item_name. Nazwy zawierające przecinki ujmij w cudzysłowy zgodnie z formatem CSV. Każdy wskazany element musi istnieć na skonfigurowanej tablicy docelowej. W jednym imporcie możesz użyć maksymalnie 5 kolumn typu Relacja z tablicą. W jednej komórce może znajdować się maksymalnie 50 połączonych elementów. Połączone elementy wliczają się też do limitów relacji między tablicami.
Pole wyboru Wartość odpowiadająca typowi logicznemu. Wartości prawdziwe: true, yes, y, x, checked, 1, ✓, ✔. Wartości fałszywe: false, no, n, 0, unchecked. Wielkość liter nie ma znaczenia. Inne wartości nie przejdą walidacji.
Data Prawidłowa data Format ISO (YYYY-MM-DD). Inne formaty mogą zostać przekształcone do prawidłowego formatu.
Lista rozwijana Etykiety rozdzielone przecinkami Każda etykieta musi już istnieć w kolumnie i być aktywna. Wszystkie etykiety na rozdzielonej przecinkami liście muszą być prawidłowe. W przeciwnym razie wiersz się nie powiedzie.
E-mail Prawidłowy adres e-mail lub Name <email> Wartość musi mieć prawidłowy format adresu e-mail.
Link Prawidłowy adres URL lub [Display Text](URL) Adres URL musi zaczynać się od http:// lub https://.
Lokalizacja lat|lng|address, np. 37.7749|-122.4194|San Francisco, CA Szerokość i długość geograficzna muszą być prawidłowymi współrzędnymi, a pole adresu jest wymagane - wartość bez adresu nie przejdzie walidacji. Adres jest wyświetlany w komórce wraz z interaktywnym znacznikiem na mapie. Inne wartości nie przejdą walidacji.
Długi tekst Tekst Puste wartości są dozwolone.
Liczba Wartość liczbowa zapisana jako tekst Liczba całkowita lub dziesiętna.
Osoby Identyfikatory rozdzielone przecinkami. Każdy identyfikator może mieć jedną z postaci: adres e-mail (alice@example.com), user:<id> lub user:<name>, team:<id> lub team:<name>, albo sama nazwa (Jeremy), która zostanie dopasowana do użytkownika lub zespołu. Każdy identyfikator musi wskazywać dokładnie jednego aktywnego użytkownika lub zespół na koncie. Brak dopasowania, wiele dopasowań lub błędy podczas dopasowania powodują niepowodzenie. Powtórzone identyfikatory są usuwane. Obowiązuje ustawienie max_people_allowed kolumny.
Telefon Numer telefonu Akceptowane są różne formaty; można opcjonalnie podać wskazówki dotyczące kraju.
Status Tekst etykiety (dokładne dopasowanie) Etykieta musi już istnieć w kolumnie i być aktywna. Wielkość liter ma znaczenie.
Tekst Tekst Puste wartości są dozwolone.
Oś czasu YYYY-MM-DD/YYYY-MM-DD dla zakresu dat albo pojedyncza data w formacie YYYY-MM-DD (ustawia from = to = date) Obie daty muszą być prawidłowymi datami ISO. Inne separatory (myślnik ze spacjami, pionowa kreska, JSON) nie są akceptowane.

Sprawdzone metody

  1. Preferuj ingest_items w przypadku integracji i każdego importu, który ma przebiegać jak zwykła praca na tablicy.
  2. Używaj backfill_items tylko przy zaplanowanym, jednorazowym imporcie początkowym.
  3. Sprawdzaj status zadania mniej więcej co 10 sekund - nie częściej.
  4. Przed przesłaniem pliku sprawdź nagłówek CSV względem schematu tablicy.
  5. Obsługuj osobno błędy GraphQL zwrócone przez API i błędy HTTP występujące podczas przesyłania pliku.
  6. Pobierz raport od razu, gdy report_created ma wartość true.
  7. W przypadku RATE_LIMIT_EXCEEDED zaczekaj przez czas wskazany w extensions.retryAfterMs zamiast od razu ponawiać żądanie.
  8. W przypadku ingest rozłóż import dużej liczby elementów na całą godzinę, jeśli to możliwe, aby ograniczyć ryzyko odrzuceń z powodu ACCOUNT_CAPACITY_EXCEEDED.
  9. W importach hierarchii MLS ustaw wiersze od góry do dołu, tak aby każdy element podrzędny występował po elemencie nadrzędnym.
  10. W importach klasycznych podelementów ustaw wiersze tak, aby każdy podelement następował po elemencie, do którego należy.

Rozwiązywanie problemów

Problem Objawy Rozwiązanie
Wygasł adres URL do przesyłania pliku Kod HTTP 403 podczas przesyłania pliku metodą PUT (S3 zwraca komunikat "Request has expired") Rozpocznij nowe zadanie i prześlij plik w ciągu 10 minut.
Przesyłanie odrzucone z powodu niepodpisanego nagłówka sumy kontrolnej Kod HTTP 403 z S3 i komunikat HeadersNotSigned dotyczący x-amz-checksum-crc32 Usuń nagłówek żądania x-amz-checksum-crc32 i prześlij plik, używając tylko wymaganych nagłówków, takich jak Content-Type: text/csv.
Nieprawidłowy format CSV Status REJECTED, failure_reason: INVALID_UPLOAD Sprawdź, czy wymagane nagłówki nazw lub poziomów są obecne, wszystkie identyfikatory kolumn istnieją na tablicy, plik jest zakodowany w UTF-8, separatorem jest przecinek, a cudzysłowy wewnątrz wartości są odpowiednio zamienione na podwójne ("").
Nie utworzono elementów Status COMPLETED z wysoką wartością counts.invalid lub counts.failed i niską wartością counts.created Pobierz raport z adresu report_url i sprawdź błędy poszczególnych wierszy. Sprawdź literówki w identyfikatorach kolumn, pisownię i wielkość liter w etykietach statusu lub listy rozwijanej, format dat oraz to, czy wskazani użytkownicy lub zespoły istnieją.
Status zatrzymał się na UPLOAD_PENDING Brak postępu po przesłaniu pliku CSV Sprawdź, czy przesyłanie zakończyło się kodem HTTP 200 i zwróciło nagłówek ETag. Jeśli nie, rozpocznij nowe zadanie i prześlij plik ponownie.
Brak uprawnień do backfill Status REJECTED, failure_reason: PERMISSION_DENIED albo błąd GraphQL "Only admin users can perform this operation." Metoda backfill_items wymaga uprawnień administratora konta. Zamiast niej użyj ingest_items.
Plik jest za duży Status REJECTED, failure_reason: FILE_TOO_LARGE Podziel plik na części o rozmiarze nieprzekraczającym 150 MB.
Przekroczono godzinowy limit (ingest) Status REJECTED, failure_reason: ACCOUNT_CAPACITY_EXCEEDED Liczba prawidłowych wierszy w zadaniu przekroczyłaby pozostały limit 19,000 elementów na godzinę. Rozłóż import na całą godzinę albo poczekaj na odnowienie limitu.
Limit liczby rozpoczętych zadań Błąd GraphQL RATE_LIMIT_EXCEEDED (HTTP 429) podczas wywoływania ingest_items lub backfill_items Przed ponowieniem żądania zaczekaj przez czas wskazany w extensions.retryAfterMs. Limit 100 wywołań na godzinę jest wspólny dla ingest_items i backfill_items.
Nie znaleziono elementu relacji z tablicą albo użycie go jest niedozwolone Wiersz z wartością w kolumnie typu Relacja z tablicą jest nieprawidłowy lub jego przetwarzanie się nie powiodło Sprawdź, czy każdy wskazany element istnieje na skonfigurowanej tablicy docelowej. W kolumnach wskazujących wiele tablic docelowych użyj prefiksu board_id: i nie przekraczaj limitu połączonych elementów w komórce.
Odrzucono wiersz klasycznego podelementu Wiersz podelementu w imporcie klasycznych podelementów jest nieprawidłowy Sprawdź, czy wiersz wypełnia pole name albo name.subitem, ale nie oba naraz, oraz czy wcześniejszy wiersz w pliku zawiera element.
Zgłoszono, że nie znaleziono kolumn podelementów Wiersze są nieprawidłowe; błąd informuje, że nie znaleziono kolumn .subitem Wykonaj zapytanie columns na tablicy podelementów i użyj zwróconych identyfikatorów kolumn z dodanym przyrostkiem .subitem.
Odrzucono wiersz hierarchii MLS Wiersz w imporcie MLS jest nieprawidłowy Sprawdź, czy nazwa elementu znajduje się tylko w jednej kolumnie poziomu (name.l1–name.l5) oraz czy wiersz elementu nadrzędnego występuje wcześniej w pliku.

Powiązane strony dokumentacji


Mam problem z tym tematem Źródło: developer.monday.com