7 Min. Lesezeit
Funktion
Dieser Artikel führt dich durch einige grundlegende Operationen mit der GraphQL-API von monday.com und führt dich dann zu komplizierteren Abfragen. Gehe diese so schnell oder langsam durch, wie du möchtest. Du kannst den gesamten Beispielcode hier herunterladen.
Was ist die monday.com-API?
Die monday.com-API ermöglicht es externen Anwendungen, Daten vom monday.com-Arbeitsbetriebssystem abzurufen und zu bearbeiten.
Du kannst beispielsweise die API verwenden, um Daten zwischen monday.com und einer anderen Plattform zu synchronisieren, sodass die Aktionen deines Teams in monday.com mit den anderen von dir verwendeten Tools synchronisiert werden.
Unsere API basiert auf GraphQL, was sich ein wenig von den REST-APIs unterscheidet, an die du möglicherweise gewöhnt bist.Unser GraphQL-Schema definiert Objekte und Felder, die über unsere API abgefragt werden können.
Behandelten Themen
- Was ist GraphQL und warum ist es nützlich?
- So strukturierst du eine Anfrage an die monday.com-API
- So schreibst du einfache Abfragen
- So schreibst du Mutationen, um Daten in monday.com zu ändern
Voraussetzungen
- Eine funktionierende PHP-Umgebung
- Ein aktives monday.com-Konto ( melde dich bei monday.com an, falls du dies noch nicht getan hast)
- Ein grundlegendes Verständnis von Web-APIs und HTTP-Anfragen
- Ein grundlegendes Verständnis von PHP
Strukturieren deiner API-Anfragen
Beim Erstellen deines ersten API-Aufrufs sind einige Dinge zu beachten:
- Anfragestruktur: Alle Anfragen an die API müssen POST-Anfragen sein.Abfragen müssen unserem GraphQL-Schema entsprechen
- Authentifizierung: Alle Anfragen an die API sollten ein Authentifizierungstoken im Anfrageheader enthalten.Erfahre, wie du hier deinen API - Schlüssel bekommst.
- Anfragen Body: Alle Anfragen an die API sollten einen JSON-formatierten Body haben.Die einzige Ausnahme sind Datei-Uploads, bei denen es sich um mehrteilige Anfragen handeln sollte.
Tätigen deines ersten API-Aufrufs
Die monday.com-API kann Objekte und ihre zugehörigen Felder aus dem Arbeitsbetriebssystem abrufen.
Wir beginnen damit, eine Liste der Boards mit ihren Namen und Board-IDs abzurufen. Dazu geben wir das Objekt „Boards“ in unserer Abfrage an und führen dann das folgende Skript auf deinem PHP-Server aus:
<?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);
?>
Navigiere in deinem Browser zur URL deines Servers.Du solltest eine Antwort sehen, die eine Liste von Boards enthält, etwa so:
Beachte, dass die zurückgegebenen Daten JSON sind, sodass du sie in ein Array serialisieren und damit tun kannst, was du willst.Iterate through it; construct a tree; go nuts.
Daten aus bestimmten Elementen abrufen
Nutzen wir nun die Flexibilität von GraphQL und geben wir den Namen und die Spalten des Elements sowie den Typ, den Titel und die ID jeder Spalte zurück.
Hier unsere Anfrage:
{ items (ids: [1234567890, 9876543210, 1122334455]) {
name
column_values {
column {
title
id
type
}
}
}
}
Folge dem vorherigen Beispiel und führe dies auf deinem PHP-Server aus:
<?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);
?>
Du bekommst mit dieser Abfrage einen viel umfangreicheren Datensatz.
Erstellen eines neuen Elements
In diesem Abschnitt werden wir eine Mutation schreiben, um ein neues Element auf deinem Board zu erstellen.
Mutationen sind Operationen, die Daten hinzufügen oder aktualisieren und auch Felder des erstellten oder geänderten Objekts zurückgeben.Die Daten, die du änderst, werden als Argumente an die Mutation übergeben.
Hier ist die Abfrage, die wir verwenden werden:
mutation {
create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {
id
} }
Und hier ist der Code für diese Anfrage.Beachte, dass wir für das Argument "item_name" doppelte Anführungszeichen verwenden, um die innere Zeichenfolge von der Abfrage selbst zu unterscheiden.
<?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);
?>
Wenn die Mutation erfolgreich ist, bekommst du eine Antwort, die die ID des gerade erstellten Elements enthält:
Erstellen eines neuen Elements mithilfe von GraphQL-Variablen
Bisher haben wir Abfragen und Mutationen mit hartkodierten Werten geschrieben. Das bedeutet, wenn ich das Board ändern wollte, auf dem ich ein Element erstelle, müsste ich die Abfragezeichenfolge zurechtschneiden, was kostspielig sein könnte.
Wir können jedoch Argumente in unserer Abfrage mithilfe von GraphQL-Variablen dynamisch auffüllen.Wir übergeben die Variablen als JSON-Objekt und GraphQL fügt die Variablen dynamisch in unsere Abfrage ein!
Wir müssen den Typ der Variablen in unserer Abfrage deklarieren und die Variablen als separates JSON-Objekt in unserer API-Anfrage übergeben.
So sieht das in Aktion aus:
<?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);
?>
Wie zuvor gibt eine erfolgreiche Mutation die ID des von dir erstellten Elements zurück.
Erstellen eines neuen Elements mit ausgefüllten Spaltenwerten
In unserem letzten Beispiel erstellen wir ein neues Element und definieren die Werte für jede seiner Spalten.
Unser GraphQL-Schema definiert einen Satz von Spaltenwerten als JSON-String (Schlüssel-Wert-Paare).Die Schlüssel des column_values-Objekts müssen Spalten-IDs sein und die Werte müssen je nach Spaltentyp strukturiert sein.
Dieses spezielle Beispiel aktualisiert eine Status- und Datumsspalte.Du kannst ein Board für dieses Beispiel einrichten, indem du unsere Vorlage „Von Grund auf neu“ verwendest.
<?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);
?>
Herzlichen Glückwunsch!Du hast dieses Tutorial abgeschlossen.
Gönn dir etwas.
Du verdienst es.
Wenn du Fragen hast, wende dich einfach hier an unser Team. Wir sind rund um die Uhr erreichbar und helfen gerne!
Kommentare