Dieser Artikel führt dich durch die einige grundlegende Anwendungsfälle von GraphQL-API und Python mit monday.com und dann zu komplizierteren Abfragen. Gehe diese so schnell oder langsam durch, wie du möchtest. 

 

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 Python-Umgebung auf deinem Computer
• Ein aktives Konto auf monday.com (melde dich hier an, falls du dies noch nicht getan hast)
• Ein grundlegendes Verständnis von Web-APIs und HTTP-Anfragen
• Ein grundlegendes Verständnis von Python

 

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.

Beginnen wir damit, eine Liste von Boards zusammen mit ihren Namen und Board-IDs abzurufen. Dazu geben wir das „Boards“-Objekt in unserer Abfrage an und spezifizieren dann

Führe den folgenden Code in deiner Python-Umgebung aus:

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())

Du solltest eine Antwort bekommen, die eine Liste mit Boards hat:

 Beachte, dass die zurückgekehrten Daten JSON sind. Deshalb kannst du es in einem Glossar serialisieren und damit machen, was du willst. Viel Spaß damit :)

 

Alle Daten von einem Board abrufen

Lass uns nun von der Flexibilität von GraphQL profitieren und einem bestimmten Board einen umfassenderen Datensatz zurückgeben. Wir geben gezielt den Namen des Boards, die ID und die Beschreibung zurück, dann sämtliche Elemente auf dem Board. Für jedes Element geben wir den Wert und die Art jeder Spalte zurück.

Hier unsere Anfrage:

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

 

Wie im Beispiel zuvor, füge dies in deine Python-Umgebung ein:

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())

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 doppelte Quotes für das "item_name" Argument verwenden, um den inneren String von der eigentlichen Anfrage zu differenzieren.

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())

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:

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())

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.

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())

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!