Ten artykuł przeprowadzi Cię przez podstawowe operacje z użyciem API GraphQL monday.com, a potem pokaże bardziej złożone zapytania. Przejdź przez niego w swoim tempie. Wszystkie przykładowe fragmenty kodu możesz pobrać tutaj.

Czym jest API monday.com?

API monday.com pozwala aplikacjom zewnętrznym pobierać i edytować dane z Work OS monday.com.

Możesz na przykład użyć API do synchronizowania danych między monday.com a inną platformą. Dzięki temu działania Twojego zespołu w monday.com będą synchronizowane z innymi używanymi przez Was narzędziami.

Nasze API jest oparte na GraphQL, który nieco różni się od znanych Ci interfejsów API REST. Schemat GraphQL określa obiekty i pola, których można używać w zapytaniach wysyłanych przez nasze API.

Tematy omówione w artykule

• Czym jest GraphQL i dlaczego warto go używać
• Jak przygotować żądanie do API monday.com
• Jak tworzyć proste zapytania
• Jak pisać mutacje, aby zmieniać dane w monday.com

Wymagania wstępne

• Działające środowisko JavaScript na komputerze
• Aktywne konto monday.com (jeśli jeszcze go nie masz, zarejestruj się na monday.com)
• Podstawowa znajomość internetowych interfejsów API i żądań HTTP
• Podstawowa znajomość JavaScriptu

Uwaga: Nasze API nie obsługuje żądań między różnymi domenami. Uruchamiaj więc ten kod na serwerze, a nie w konsoli JavaScript przeglądarki. Przykładowy kod został przygotowany w NodeJS i korzysta z zależności „node-fetch”.

Przygotowywanie żądań do API

Tworząc pierwsze wywołanie API, pamiętaj o kilku kwestiach:

• Struktura żądania: wszystkie żądania do API muszą być żądaniami POST. Zapytania muszą być zgodne ze schematem GraphQL.
• Uwierzytelnianie: wszystkie żądania do API powinny zawierać token uwierzytelniający w nagłówku żądania. Dowiedz się, jak uzyskać klucz API tutaj.
• Treść żądania: treść wszystkich żądań do API powinna być w formacie JSON. Wyjątkiem są przesyłane pliki, które wymagają żądań multipart.

Wykonaj pierwsze wywołanie API

API monday.com może pobierać obiekty i powiązane z nimi pola z Work OS.

Zacznijmy od pobrania listy tablic wraz z ich nazwami i identyfikatorami. W tym celu określimy w zapytaniu obiekt „boards”, a następnie wskażemy, ile wyników ma zostać zwróconych, oraz poprosimy o nazwę i identyfikator każdej tablicy.

Wklej poniższy kod do swojego środowiska JavaScript:

let query = '{ boards (limit:5) {name id} }';  

fetch ("https://api.monday.com/v2", {  
  method: 'post',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization' : 'YOUR_API_KEY_HERE'  
   },  
   body: JSON.stringify({  
     'query' : query  
   })  
  })  
   .then(res => res.json())  
   .then(res => console.log(JSON.stringify(res, null, 2)));

Otrzymasz odpowiedź zawierającą listę tablic, podobną do tej:

Zwróć uwagę, że dane są zwracane w formacie JSON. Możesz więc przekształcić je w obiekt JavaScript i zrobić z nimi, co chcesz: iterować po nich, utworzyć strukturę drzewa - albo puścić wodze fantazji.

Pobieranie wszystkich danych z tablicy

Wykorzystajmy teraz elastyczność GraphQL, aby pobrać więcej danych z wybranej tablicy. Pobierzemy jej nazwę, identyfikator i opis, a także wszystkie elementy na tablicy. Dla każdego elementu pobierzemy wartość i typ każdej kolumny.

Oto nasze zapytanie:

{ boards (limit:1) {  
  name  
  id  
  description  
  items_page {  
    items {  
    name  
    column_values {  
      id  
      type  
      text  
} } } } }

Tak jak poprzednio, wklej ten kod do swojego środowiska JavaScript:

let query = '{boards(limit:1) { name id description items_page { items { name column_values{id type text } } } } }';  

fetch ("https://api.monday.com/v2", {  
  method: 'post',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization' : 'YOUR_API_KEY_HERE'  
  },  
  body: JSON.stringify({  
    'query' : query  
  })  
})  
  .then(res => res.json())  
  .then(res => console.log(JSON.stringify(res, null, 2)));

To zapytanie zwróci znacznie więcej danych.

Tworzenie nowego elementu

W tej sekcji napiszemy mutację, która utworzy nowy element na Twojej tablicy.

Mutacje dodają lub aktualizują dane, a także zwracają pola utworzonego lub zmienionego obiektu. Zmieniane dane przekazuje się jako argumenty mutacji.

Oto zapytanie, którego użyjemy:

mutation {  
  create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {  
  id  
} }

Poniżej znajdziesz kod, który wysyła to żądanie. Zwróć uwagę, że przed każdym cudzysłowem w argumencie „item_name” dodajemy znak \ (znak ucieczki). Dzięki temu odróżniamy wewnętrzny ciąg znaków od samego zapytania.

let query3 = 'mutation{ create_item (board_id:YOUR_BOARD_ID_HERE, item_name:\"WHAT IS UP MY FRIENDS!\") { id } }';  

fetch ("https://api.monday.com/v2", {  
  method: 'post',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization' : 'YOUR_API_KEY_HERE'  
  },  
  body: JSON.stringify({  
    'query' : query3  
  })  
})  
  .then(res => res.json())  
  .then(res => console.log(JSON.stringify(res, null, 2)));

Jeśli mutacja się powiedzie, otrzymasz odpowiedź zawierającą identyfikator utworzonego elementu:

Tworzenie elementu z użyciem zmiennych GraphQL

Do tej pory zapisywaliśmy zapytania i mutacje ze stałymi wartościami. Jeśli chcielibyśmy zmienić tablicę, na której tworzymy element, musielibyśmy ręcznie przerobić ciąg zapytania, co może być kłopotliwe.

Możemy jednak dynamicznie przekazywać argumenty do zapytania za pomocą zmiennych GraphQL. Przekazujemy zmienne jako obiekt JSON, a GraphQL dynamicznie wstawia je do zapytania.

Musimy zadeklarować typ zmiennych w zapytaniu i przekazać je jako osobny obiekt JSON w żądaniu do API.

Tak to wygląda w praktyce:

let query4 = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID_HERE, item_name:$myItemName) { id } }';  
let vars = {"myItemName" : "Hello, world!"};  

fetch ("https://api.monday.com/v2", {  
  method: 'post',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization' : 'YOUR_API_KEY_HERE'  
  },  
  body: JSON.stringify({  
    'query' : query4,  
    'variables' : JSON.stringify(vars);  
  })  
})  
  .then(res => res.json())  
  .then(res => console.log(JSON.stringify(res, null, 2)));

Tak jak poprzednio, jeśli mutacja się powiedzie, otrzymasz identyfikator utworzonego elementu.

Tworzenie elementu z uzupełnionymi wartościami kolumn

W ostatnim przykładzie utworzymy nowy element i określimy wartości jego kolumn.

Schemat GraphQL definiuje zestaw wartości kolumn jako ciąg znaków JSON (pary klucz-wartość). Kluczami obiektu column_values muszą być identyfikatory kolumn. Wartości muszą mieć strukturę dopasowaną do typu kolumny.

Ten przykład aktualizuje kolumnę statusu i kolumnę daty. Możesz przygotować tablicę do tego przykładu, korzystając z szablonu „Zacznij od zera”.

let query5 = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID_HERE, item_name:$myItemName, column_values:$columnVals) { id } }';  
let vars = {  
  "myItemName" : "Hello, world!",  
  "columnVals" : JSON.stringify({  
    "status" : {"label" : "Done"},  
    "date4" : {"date" : "1993-08-27"}  
  })  
};  

fetch ("https://api.monday.com/v2", {  
  method: 'post',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization' : 'YOUR_API_KEY_HERE'  
  },  
  body: JSON.stringify({  
    'query' : query5,  
    'variables' : JSON.stringify(vars)  
  })  
})  
  .then(res => res.json())  
  .then(res => console.log(JSON.stringify(res, null, 2)));

Gratulacje! Ukończyłeś ten samouczek.

Zrób sobie małą przyjemność!

Zasłużyłeś na to. 🔮