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 Javascript-Umgebung auf deinem Computer
• 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 Javascript

 

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 mit dem Abrufen einer Liste von Boards, einschließlich ihrer Namen und Board-IDs. Dazu geben wir in unserer Abfrage das Objekt „Boards“ an und legen dann die Anzahl der Ergebnisse fest, die wir zusammen mit dem Namen und der Board-ID ausgeben möchten.

Füge den folgenden Code in deine Javascript-Umgebung ein:

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

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

Beachte, dass die zurückgegebenen Daten JSON sind, sodass du sie in einem Javascript-Objekt serialisieren und damit tun kannst, 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 Javascript-Umgebung ein:

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

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 einen \ (Escape character) vor jedes Fragezeichen im "item_name" Argument einfügen, damit wir den inneren String von der Anfrage differenzieren.

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

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 hartcodierten Werten geschrieben.Das heißt, wenn ich das Board ändern wollte, auf dem ich ein Element erstelle, müsste ich die Abfragezeichenfolge verschieben, was kostspielig sein kann.

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:

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

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.

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

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!