Przegląd GraphQL
API monday.com jest zbudowane w oparciu o GraphQL - elastyczny język zapytań, który pozwala zwracać tyle danych, ile potrzebujesz. Warto wiedzieć, że GraphQL to warstwa aplikacji, która przetwarza wysłane zapytanie i odpowiednio zwraca lub zmienia dane.
W przeciwieństwie do interfejsów API REST, w których różne punkty końcowe zwracają różne dane, GraphQL zawsze udostępnia jeden punkt końcowy i pozwala określić strukturę zwracanych danych. Nasze API korzysta z następującego punktu końcowego: https://api.monday.com/v2.
W tym dokumencie omówimy operacje GraphQL i typy obiektów, aby pomóc Ci zrozumieć podstawowe elementy zapytania. Opowiemy też o wizualnym interfejsie GraphQL, który pozwala testować zapytania i mutacje, a na koniec pokażemy, gdzie znajdziesz schemat monday.com. Zaczynajmy!
👍 Wskazówka
Zapoznaj się z tym wprowadzeniem do GraphQL, aby dowiedzieć się, co możesz zrobić za pomocą GraphQL!
Operacje
W GraphQL dostępne są dwa rodzaje operacji: zapytania i mutacje.
Zapytanie
Zapytania wykonują operację ODCZYTU i nie zmieniają żadnych danych. Wynik każdego zapytania jest sformatowany tak samo jak samo zapytanie. Poniższy przykład pobiera identyfikator, tytuł i typ każdej kolumny na tablicy 1234567890.
Przykładowe zapytanie
query {
boards {
columns {
id
title
type
}
}
}
Przykładowa odpowiedź
{
"columns": [
{
"id": "name",
"title": "Name",
"type": "name"
},
{
"id": "subitems",
"title": "Subitems",
"type": "subtasks"
},
{
"id": "person",
"title": "Person",
"type": "people"
},
{
"id": "status",
"title": "Status",
"type": "status"
}
]
}
Mutacja
Mutacje to specjalne zapytania, które wykonują operacje CUD (Create, Update, Delete - tworzenie, aktualizowanie i usuwanie) w celu zmodyfikowania danych. Mutacje zwracają obiekt, który został właśnie zmodyfikowany, więc możesz pobrać zmienione dane. Poniższy przykład tworzy nowy element na tablicy 1234567890 i zwraca identyfikator oraz nazwę nowego elementu.
Przykładowa mutacja
mutation{
create_item (board_id: 1234567890, item_name: "New Item"){
id
name
}
}
Przykładowa odpowiedź
{
"data": {
"create_item": {
"id": "9876543210",
"name": "New Item"
}
},
"account_id": 12345678
}
Wiele operacji w jednym żądaniu
Możesz też wysłać wiele zapytań w jednym żądaniu. Zostaną wykonane jedno po drugim. Poniższe zapytanie zwraca identyfikatory i nazwy tablic 1234567890 i 9876543210. Mutacja tworzy nowy element i pobiera jego identyfikator oraz nazwę na obu tablicach: 1234567890 i 9876543210.
Przykładowe zapytanie
query {
checkBoard1: boards (ids:1234567890) {
id
name
}
checkBoard2: boards (ids:9876543210) {
id
name
}
}
Przykładowa odpowiedź
{
"data": {
"checkBoard1": [
{
"id": "1234567890",
"name": "Test Board 1"
}
],
"checkBoard2": [
{
"id": "9876543210",
"name": "Test Board 2"
}
]
},
"account_id": 12345678
}
Przykładowa mutacja
mutation{
createItem1: create_item (board_id: 1234567890, item_name:"Test Item 1") {
id
name
}
createItem2: create_item(board_id: 9876543210, item_name:"Test Item 2") {
id
name
}
}
Przykładowa odpowiedź
{
"data": {
"createItem1": {
"id": "11223344",
"name": "Test Item 1"
},
"createItem2": {
"id": "44332211",
"name": "Test Item 2"
}
},
"account_id": 12345678
}
Typy obiektów
Typy obiektów to zestawy pól opisujących dostępne dane, które możesz pobrać za pomocą API. Pola mogą też przyjmować argumenty, za pomocą których przekazujesz parametry podczas pobierania danych.
Pola
Pola określają właściwości lub atrybuty obiektów, dzięki czemu możesz wskazać, jakie informacje mają zostać pobrane w zapytaniu. Każdy obiekt w schemacie zawiera pola, które możesz pobierać po nazwie, aby uzyskać konkretne właściwości obiektu.
Weźmy na przykład obiekt boards. Możesz użyć tych pól, aby pobrać konkretne informacje o swoich tablicach. Poniższy przykład zwraca identyfikator i nazwę tablic oraz identyfikator, tytuł i typ każdej kolumny na tych tablicach.
query {
boards {
id
name
columns {
id
title
type
}
}
}
Argumenty
Możesz przekazywać argumenty w zapytaniu, aby określić, jakie dane zwrócić, czyli filtrować wyniki i ograniczyć je do tych, których potrzebujesz.
Korzystając z przykładu boards powyżej, możesz użyć tych argumentów, aby ograniczyć liczbę wyników zwracanych przez zapytanie. Poniższy przykład zwraca identyfikatory i nazwy wyłącznie tablic 1234567890 i 9876543210 oraz identyfikator, tytuł i typ każdej kolumny na tych tablicach.
query {
boards (ids: [1234567890, 9876543210]) {
id
name
columns {
id
title
type
}
}
}
Zmienne
Możesz używać zmiennych, aby przekazywać dynamiczne wartości do argumentów. Zapisuje się je poza samym ciągiem zapytania, w sekcji zmiennych, a następnie przekazuje do argumentów.
Aby skorzystać ze zmiennych, wykonaj trzy czynności:
- Zastąp statyczną wartość w zapytaniu zmienną
$variableName - Zadeklaruj
$variableNamejako jedną ze zmiennych akceptowanych przez zapytanie - Przekaż
variableName: valuew oddzielnym słowniku zmiennych zależnym od transportu, zwykle w formacie JSON
mutation change_column_value($value: JSON!) {
change_column_value (board_id: 157244624,item_id: 9539475, column_id: "status", value: $value) {
id
}
}
query variables:
{
"value": "{\"index\": 1}"
}
Schemat monday.com
Nasz schemat GraphQL określa strukturę danych dostępnych przez API i zawiera wszystkie dostępne zapytania oraz mutacje. To przydatne źródło informacji, które pozwala weryfikować odpowiedzi API i uzyskiwać przydatne informacje z metadanych.
Schemat udostępniamy tutaj. Domyślnie jest dostępny w formacie JSON z introspekcją dla wersji API Current. Możesz zażądać innej wersji, podając jej nazwę w opcjonalnym parametrze version=<API-Version>.
Na przykład: https://api.monday.com/v2/get_schema?version=2024-04
Możesz też pobrać schemat w języku definicji schematu (SDL), używając opcjonalnego parametru format=sdl.
Na przykład: https://api.monday.com/v2/get_schema?format=sdl
📘 Dołącz do naszej społeczności deweloperów!
Stworzyliśmy społeczność dla deweloperów. Możesz w niej wyszukiwać wcześniejsze dyskusje, aby znaleźć rozwiązania, zadawać pytania, poznawać nowe funkcje i aktualizacje, a także uczyć się wskazówek i trików od innych deweloperów. Dołącz do nas! 😎