Samouczek szybkiego startu z API - PHP
Ten artykuł przeprowadzi Cię przez kilka podstawowych operacji z użyciem monday.com GraphQL API, a następnie pokaże bardziej złożone zapytania. Możesz przejść przez samouczek szybko albo poświęcić na niego tyle czasu, ile potrzebujesz. Tutaj pobierzesz cały przykładowy kod.
Czym jest API monday.com?
API monday.com pozwala zewnętrznym aplikacjom pobierać i edytować dane z monday.com Work OS.
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 narzędziami, których używasz.
Nasze API jest oparte na GraphQL, który działa nieco inaczej niż znane Ci API REST. Schemat GraphQL definiuje obiekty i pola, o które można pytać za pośrednictwem naszego API.
Omówione zagadnienia
- Czym jest GraphQL i dlaczego warto go używać
- Jak przygotować żą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 PHP
- Aktywne konto monday.com (jeśli jeszcze go nie masz, zarejestruj się w monday.com)
- Podstawowa znajomość interfejsów API sieciowych i żądań HTTP
- Podstawowa znajomość PHP
Przygotowywanie żądań API
Podczas przygotowywania pierwszego wywołania 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. Tutaj dowiesz się, jak uzyskać klucz API.
- Treść żądania: wszystkie żądania do API powinny mieć treść w formacie JSON. Wyjątkiem jest przesyłanie plików, które wymaga żą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 uruchomimy poniższy skrypt na serwerze PHP:
<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];
$query = '{ boards { id name } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => json_encode(['query' => $query]),
]
]));
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
?>
Otwórz w przeglądarce adres URL swojego serwera. Powinna pojawić się odpowiedź zawierająca listę tablic, na przykład:
Zwrócone dane są w formacie JSON. Możesz więc przekształcić je w tablicę i zrobić z nimi, co chcesz: przejść po nich, utworzyć drzewo - możliwości są nieograniczone.
Pobieranie danych z wybranych elementów
Skorzystajmy teraz z elastyczności GraphQL i pobierzmy nazwę elementu oraz jego kolumny, a także typ, tytuł i identyfikator każdej kolumny.
Oto nasze zapytanie:
{ items (ids: [1234567890, 9876543210, 1122334455]) {
name
column_values {
column {
title
id
type
}
}
}
}
Korzystając z poprzedniego przykładu, uruchom ten kod na serwerze PHP:
<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];
$query = '{items(ids:[1234567890, 9876543210, 1122334455]) { name column_values { column { title id text } } } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => json_encode(['query' => $query]),
]
]));
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
?>
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 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
} }
Poniżej znajdziesz kod, który wysyła to żądanie. Zwróć uwagę, że argument „item_name” zapisujemy w cudzysłowie, aby odróżnić jego wartość tekstową od samego zapytania.
<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];
$query = 'mutation{ create_item (board_id:YOUR_BOARD_ID, item_name:"WHAT IS UP MY FRIENDS!") { id } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => json_encode(['query' => $query]),
]
]));
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
?>
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 z wartościami wpisanymi bezpośrednio w kodzie. Jeśli na przykład chcesz utworzyć element na innej tablicy, musisz ręcznie zmienić ciąg zapytania, co może być czasochłonne.
Możemy jednak dynamicznie przekazywać argumenty w zapytaniu za pomocą zmiennych GraphQL. Przekazujemy zmienne jako obiekt JSON, a GraphQL automatycznie wstawia je do zapytania.
Musimy zadeklarować typ zmiennych w zapytaniu i przekazać je jako osobny obiekt JSON w żądaniu API.
W praktyce wygląda to tak:
<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];
$query = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName) { id } }';
$vars = ['myItemName' => 'Hello world!'];
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => json_encode(['query' => $query, 'variables' => $vars]),
]
]));
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
?>
Tak jak poprzednio, udana mutacja zwróci identyfikator utworzonego elementu.
Tworzenie nowego elementu z wypeł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 z parami 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 przygotować tablicę do tego przykładu, możesz użyć szablonu „Zacznij od zera” (Start from scratch).
<?php
$query = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName, column_values:$columnVals) { id } }';
$vars = ['myItemName' => 'Hello world!',
'columnVals' => json_encode([
'status' => ['label' => 'Done'],
'date4' => ['date' => '1993-08-27']
])];
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => json_encode(['query' => $query, 'variables' => $vars]),
]
]));
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
?>
Gratulacje! Ukończyłeś ten samouczek.
Zrób sobie przyjemność!
Zasługujesz na to. 🔮