Zaloguj się
Nowe zgłoszenie
Dokumentacja dla programistów›Dokumentacja API (rdzeń)›Tagi
Dokumentacja dla programistów

Tagi

Dokumentacja API (rdzeń)Dokumentacja API
Aktualizacja 2026-09-06

Kolumna tagów (Tags) przechowuje jedną lub więcej wartości tagów, które pozwalają kategoryzować elementy lub grupować je według słów kluczowych na różnych tablicach. Tagi są dostępne na całym koncie - ten sam tag można przypisać do elementów na różnych tablicach.

Za pomocą API kolumna tagów obsługuje odczyt, filtrowanie, aktualizowanie i czyszczenie wartości.

Typ kolumny Typ implementacji Obsługiwane operacje
tags TagsValue
  • Odczyt: Tak
  • Filtrowanie: Tak
  • Aktualizowanie: Tak
  • Czyszczenie: Tak

Zapytania

Kolumny tagów można odpytywać za pomocą pola column_values w zapytaniach o elementy. Użyj do tego fragmentu inline dla typu TagsValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on TagsValue {
        id
        tag_ids
        text
        value
        tags {
          id
          name
          color
        }
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on TagsValue {
          id
          tag_ids
          text
          value
          tags {
            id
            name
            color
          }
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

const response = await mondayApiClient.request(query, variables);

Pola

Możesz użyć poniższych pól, aby określić, jakie informacje zwróci implementacja TagsValue.

Pole Opis
column Column! Kolumna, do której należy ta wartość.
id ID! Unikalny identyfikator kolumny.
tag_ids [Int!]! Unikalne identyfikatory przypisanych tagów.
tags [Tag!]! Lista obiektów tagów. Każdy zawiera pola id, name i color.
text String Wartość kolumny w postaci tekstu. Zwraca listę nazw tagów rozdzielonych przecinkami lub "", jeśli kolumna jest pusta.
type ColumnType! Typ kolumny.
value JSON Surowa wartość kolumny w postaci ciągu JSON. Zwraca {"tag_ids": [id1, id2]} lub null, jeśli kolumna jest pusta.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "tags",
            "tag_ids": [295026, 295064],
            "text": "Frontend, Urgent",
            "value": "{\"tag_ids\":[295026,295064]}",
            "tags": [
              {
                "id": "295026",
                "name": "Frontend",
                "color": "#579bfc"
              },
              {
                "id": "295064",
                "name": "Urgent",
                "color": "#e2445c"
              }
            ]
          }
        ]
      }
    ]
  }
}

Bezpośrednie odpytywanie tagów

Tagi są dostępne na całym koncie. Możesz odpytać wszystkie tagi albo wybrane tagi według ich identyfikatorów, używając głównego zapytania tags.

query {
  tags(ids: [295026, 295064]) {
    id
    name
    color
  }
}

Filtrowanie

Możesz filtrować elementy według wartości tagów za pomocą obiektu items_page. Kolumna tagów obsługuje następujące operatory:

Operator Wartość porównawcza Opis
any_of Tablica identyfikatorów tagów (np. [295026, 295064]) lub [-1] dla pustych wartości Zwraca elementy, którym przypisano dowolny z podanych tagów.
not_any_of Tablica identyfikatorów tagów (np. [295026]) lub [-1] dla pustych wartości Pomija elementy, którym przypisano dowolny z podanych tagów.
contains_text Wartość tekstowa (np. "Frontend") Zwraca elementy, których nazwy tagów zawierają podany tekst (dopasowanie częściowe).
contains_terms Wartość tekstowa (np. "Frontend") Zwraca elementy, których nazwy tagów pasują do podanego terminu.
is_empty [] Zwraca elementy, którym nie przypisano żadnych tagów.
is_not_empty [] Zwraca elementy, którym przypisano co najmniej jeden tag.

Przykłady

Filtrowanie według identyfikatora tagu

Ten przykład zwraca elementy, którym przypisano tag o identyfikatorze 295026.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "tags"
            compare_value: [295026]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on TagsValue {
            tag_ids
            text
          }
        }
      }
    }
  }
}

Filtrowanie według nazwy tagu

Ten przykład zwraca elementy, których tagi zawierają tekst „Frontend”.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "tags"
            compare_value: "Frontend"
            operator: contains_text
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filtrowanie elementów bez tagów

Ten przykład zwraca elementy, którym nie przypisano żadnych tagów.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "tags"
            compare_value: []
            operator: is_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Pomijanie konkretnego tagu

Ten przykład zwraca elementy, którym nie przypisano tagu o identyfikatorze 295026.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "tags"
            compare_value: [295026]
            operator: not_any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Mutacje

Tworzenie tagu lub pobieranie istniejącego

Zanim przypiszesz tagi do elementów, muszą one istnieć na poziomie konta. Użyj mutacji create_or_get_tag, aby utworzyć nowy tag lub pobrać istniejący na podstawie jego nazwy.

mutation {
  create_or_get_tag(tag_name: "Frontend") {
    id
    name
    color
  }
}

Argumenty

Argument Typ Wymagany Opis
tag_name String Tak Nazwa tagu. Spacje są automatycznie usuwane (np. „My Tag” zmieni się na „MyTag”).
board_id ID Nie Identyfikator prywatnej tablicy, na której ma zostać utworzony tag. Nie jest wymagany w przypadku tablic publicznych.

Jeśli tag o podanej nazwie już istnieje, mutacja zwraca istniejący tag zamiast tworzyć duplikat.

Aktualizowanie wartości

Możesz zaktualizować kolumnę tagów za pomocą change_multiple_column_values, przekazując w column_values obiekt JSON zawierający tablicę tag_ids.

Kolumna tagów nie obsługuje change_simple_column_value. Musisz użyć change_multiple_column_values.

Ustawianie jednego tagu

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"tags\": {\"tag_ids\": [295026]}}"
  ) {
    id
  }
}

Ustawianie wielu tagów

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"tags\": {\"tag_ids\": [295026, 295064]}}"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    tags: { tag_ids: [295026, 295064] }
  })
};

const response = await mondayApiClient.request(query, variables);

Aktualizacja kolumny tagów zastępuje wszystkie przypisane do niej tagi podaną listą. Aby dodać tag do tagów przypisanych do elementu, najpierw odczytaj bieżące wartości tag_ids, a następnie prześlij pełną listę, uwzględniającą nowy tag.

Ustawianie tagów podczas tworzenia elementu

Możesz ustawić wartości tagów podczas tworzenia elementu, przekazując wartość kolumny tagów w argumencie column_values.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"tags\": {\"tag_ids\": [295026, 295064]}}"
  ) {
    id
    name
  }
}

Czyszczenie wartości

Możesz wyczyścić kolumnę tagów za pomocą change_multiple_column_values, przekazując w column_values wartość null lub pusty obiekt.

Czyszczenie przez ustawienie wartości null

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"tags\": null}"
  ) {
    id
  }
}

Czyszczenie przez przekazanie pustego obiektu

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"tags\": {}}"
  ) {
    id
  }
}

Odczytywanie konfiguracji kolumny

Możesz odpytać ustawienia kolumny tagów za pomocą pola settings tej kolumny. Tagi są dostępne na całym koncie i nie mają konfiguracji specyficznej dla kolumny, dlatego pole settings dla kolumn tagów zwraca pusty obiekt.

Pole settings_str jest przestarzałe od wersji API 2025-10. Użyj zamiast niego typowanego obiektu settings, który zwraca uporządkowane dane JSON zamiast ciągu zakodowanego w formacie JSON.

query {
  boards(ids: 1234567890) {
    columns(ids: ["tags"]) {
      id
      title
      type
      settings
    }
  }
}

Przykładowa odpowiedź settings

{}

W przeciwieństwie do kolumn takich jak status czy lista rozwijana, kolumna tagów nie ma konfiguracji na poziomie kolumny. Tagi są zarządzane na poziomie konta i współdzielone między wszystkimi tablicami.

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny tagów za pomocą zapytania get_column_type_schema. Zwraca ono strukturę, reguły walidacji i dostępne właściwości konfiguracji kolumny.

query {
  get_column_type_schema(
    type: tags
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {},
            "additionalProperties": false
          }
        }
      }
    }
  }
}

Odpowiedź zawiera nazwy właściwości, typy, ograniczenia (takie jak maksymalna długość i dozwolone wartości) oraz opisy poszczególnych ustawień. Możesz wykorzystać te informacje do walidowania ustawień kolumn, dynamicznego generowania interfejsów użytkownika lub dostarczania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.


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