Samouczek szybkiego startu z API - Python
Ten artykuł pokaże Ci, jak korzystać z API GraphQL monday.com i Pythona. Zaczniemy od prostych przykładów, a następnie przejdziemy do bardziej złożonych zapytań. Możesz przejść przez niego tak szybko lub powoli, jak chcesz.
Czym jest API monday.com?
API monday.com umożliwia aplikacjom zewnętrznym pobieranie i edytowanie danych z systemu Work OS monday.com.
Możesz na przykład używać 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 Ciebie narzędziami.
Nasze API opiera się na GraphQL, który nieco różni się od znanych Ci interfejsów API REST. Schemat GraphQL określa obiekty i pola, o które można wysyłać zapytania za pośrednictwem naszego API.
Omówione zagadnienia
- Czym jest GraphQL i dlaczego warto go używać
- Jak zbudować żądanie do API monday.com
- Jak pisać proste zapytania
- Jak pisać mutacje, aby zmieniać dane w monday.com
Wymagania wstępne
- Działające środowisko Pythona na Twoim komputerze
- Aktywne konto monday.com (jeśli jeszcze go nie masz, zarejestruj się tutaj)
- Podstawowa znajomość internetowych interfejsów API i żądań HTTP
- Podstawowa znajomość Pythona
Uwaga: W Pythonie dostępnych jest wiele modułów do obsługi żądań HTTP. Możesz użyć dowolnego z nich, aby komunikować się z naszym API. W tym samouczku skorzystamy z biblioteki requests.
Struktura żądań API
Przy tworzeniu pierwszego wywołania API pamiętaj o kilku rzeczach:
- 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: wszystkie żądania do API powinny mieć treść w formacie JSON. Wyjątkiem są przesyłane pliki, które wymagają żądań typu multipart.
Wykonaj pierwsze wywołanie API
API monday.com umożliwia pobieranie obiektów i powiązanych z nimi pól z systemu Work OS.
Zacznijmy od pobrania listy tablic wraz z ich nazwami i identyfikatorami. W tym celu w zapytaniu określimy obiekt „boards”, a następnie określimy
Uruchom poniższy kod w swoim środowisku Pythona:
import requests
import json
apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query = '{ boards (limit:5) {name id} }'
data = {'query' : query}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())
Otrzymasz odpowiedź zawierającą listę tablic, na przykład:
Zwróć uwagę, że zwrócone dane są w formacie JSON. Możesz więc przekształcić je w słownik i zrobić z nimi, co chcesz: przeiterować po nich, zbudować drzewo albo wykorzystać je w dowolny inny sposób.
Pobieranie wszystkich danych z tablicy
Wykorzystajmy teraz elastyczność GraphQL i pobierzmy 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 w poprzednim przykładzie, wklej ten kod do swojego środowiska Pythona:
import requests
import json
apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query2 = '{boards(limit:1) { name id description items_page { items { name column_values{id type text } } } } }'
data = {'query' : query2}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())
To zapytanie zwróci znacznie więcej danych.
Tworzenie nowego elementu
W tej sekcji napiszemy mutację, która utworzy nowy element na tablicy.
Mutacje to operacje, które 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
} }
Oto kod, który wysyła to żądanie. Zwróć uwagę, że argument „item_name” zapisujemy w podwójnych cudzysłowach, aby odróżnić zawarty w nim tekst od samego zapytania.
import requests
import json
apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query3 = 'mutation{ create_item (board_id:YOUR_BOARD_ID, item_name:"WHAT IS UP MY FRIENDS!") { id } }'
data = {'query' : query3}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())
Jeśli mutacja się powiedzie, otrzymasz odpowiedź zawierającą identyfikator utworzonego elementu.
Tworzenie nowego elementu za pomocą zmiennych GraphQL
Do tej pory pisaliśmy zapytania i mutacje ze stałymi wartościami. Jeśli na przykład zechcę utworzyć element na innej tablicy, muszę odpowiednio zmodyfikować tekst zapytania, co może być uciążliwe.
Możemy jednak dynamicznie uzupełniać argumenty w zapytaniu za pomocą zmiennych GraphQL. Przekazujemy zmienne jako obiekt JSON, a GraphQL wstawia je do zapytania.
Musimy zadeklarować typ zmiennych w zapytaniu i przekazać je jako osobny obiekt JSON w żądaniu API.
Tak wygląda to w praktyce:
import requests
import json
apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query4 = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName) { id } }'
vars = {'myItemName' : 'Hello everyone!'}
data = {'query' : query4, 'variables' : vars}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())
Tak jak poprzednio, jeśli mutacja się powiedzie, zwróci identyfikator utworzonego elementu.
Tworzenie nowego 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 JSON zawierający pary klucz-wartość. Kluczami obiektu column_values muszą być identyfikatory kolumn, a wartości należy sformatować odpowiednio do typu kolumny.
Ten przykład aktualizuje kolumnę statusu i kolumnę daty. Aby go wykonać, możesz utworzyć tablicę na podstawie szablonu „Od zera (Start from scratch)”.
import requests
import json
apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query5 = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName, column_values:$columnVals) { id } }'
vars = {
'myItemName' : 'Hello everyone!',
'columnVals' : json.dumps({
'status' : {'label' : 'Done'},
'date4' : {'date' : '1993-08-27'}
})
}
data = {'query' : query5, 'variables' : vars}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())
Gratulacje! Ukończono samouczek.
Zrób sobie przyjemność
Zasługujesz na to. 🔮