Cet article vous guidera dans l'utilisation de l'API GraphQL de monday.com avec Python. Il commencera par des opérations de base avant de passer à des requêtes plus complexes. Vous pouvez le parcourir aussi rapidement ou lentement que vous le souhaitez. 

 

Qu'est-ce que l'API monday.com ?

L'API monday.com permet aux applications externes de récupérer et de modifier les données du système d'exploitation monday.com.

Par exemple, vous pouvez utiliser l'API pour synchroniser les données entre monday.com et une autre plateforme, afin que les actions de votre équipe sur monday.com soient synchronisées avec les autres outils que vous utilisez.

Notre API est construite sur GraphQL, ce qui est un peu différent des API REST auxquelles vous êtes peut-être habitué. Notre schéma GraphQL définit les objets et les champs qui peuvent être interrogés via notre API.

 

Sujets abordés

• Qu'est-ce que GraphQL et pourquoi est-il utile ?
• Comment structurer une requête vers l'API monday.com ?
• Comment écrire des requêtes simples
• Comment écrire des mutations pour modifier les données de monday.com ?

 

Conditions préalables

• Un environnement Python fonctionnel sur votre ordinateur
• Un compte monday.com actif (inscrivez-vous ici si vous n'en avez pas encore)
• Une compréhension de base des API web et des requêtes HTTP
• Une compréhension de base de Python

 

Structurer vos demandes d'API

Il y a quelques éléments à garder à l'esprit lorsque vous construisez votre premier appel d'API :

• Structure de la demande : toutes les demandes adressées à l'API doivent être des demandes POST. Les requêtes doivent être conformes à notre schéma GraphQL
• Authentification : toutes les demandes adressées à l'API doivent inclure un jeton d'authentification dans l'en-tête de la demande. Découvrez comment obtenir votre clé d'API ici. 
• Corps de la demande : toutes les demandes adressées à l'API doivent avoir un corps au format JSON. La seule exception concerne les téléchargements de fichiers, qui doivent être des demandes multipart.

 

Effectuer votre premier appel d'API

L'API de monday.com peut récupérer des objets et leurs champs associés à partir de Work OS.

Commençons par récupérer une liste de tableaux, avec leurs noms et leurs identifiants. Pour ce faire, nous allons spécifier l'objet « tableaux » dans notre requête, puis spécifier

Exécutez le code suivant dans votre environnement Python :

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

Vous devriez obtenir une réponse contenant une liste de tableaux, comme ceci :

Remarquez que les données renvoyées sont en JSON, vous pouvez donc les sérialiser dans un dictionnaire et en faire ce que vous voulez. Interrogez-les, construisez un arbre, faites-vous plaisir.

 

Récupérer toutes les données d'un tableau

Profitons à présent de la flexibilité du GraphQL pour renvoyer un ensemble plus complet de données pour un tableau donné. Plus précisément, nous allons renvoyer le nom, l'ID et la description du tableau, puis tous les éléments du tableau. Pour chaque élément, nous renverrons la valeur et le type de chaque colonne.

Voici notre requête :

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

 

En suivant l'exemple précédent, collez ceci dans votre environnement Python :

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 { name column_values{title id type text } } } }'
data = {'query' : query2}

r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())

Vous obtiendrez un ensemble de données beaucoup plus riche avec cette requête.

 

Création d'un nouvel élément

Dans cette section, nous allons écrire une mutation pour créer un nouvel élément sur votre tableau.

Les mutations sont des opérations qui ajoutent ou mettent à jour des données, et renvoient également des champs sur l'objet qui a été créé ou modifié. Les données que vous modifiez sont transmises comme arguments à la mutation.

Voici la requête que nous allons utiliser :

mutation {
  create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {
  id
} }

Et voici le code qui vous permettra d'effectuer cette requête. Notez que nous utilisons des guillemets pour l'argument "item_name", afin de différencier le segment interne de la requête elle-même. 

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

Lorsque la mutation est réussie, vous obtenez une réponse qui contient l'ID de l'élément que vous venez de créer.

 

Création d'un nouvel élément à l'aide de variables GraphQL

Jusqu'à présent, nous avons écrit des requêtes et des mutations avec des valeurs codées en dur. En d'autres termes, si je voulais changer le tableau sur lequel je crée un élément, je devais faire glisser et découper le segment de requête, ce qui peut être coûteux.

Cependant, nous pouvons alimenter dynamiquement les arguments de notre requête en utilisant des variables GraphQL. Nous passons les variables sous la forme d'un objet JSON, et GraphQL insère dynamiquement les variables dans notre requête !

Nous devons déclarer le type des variables dans notre requête, et passer les variables comme un objet JSON séparé dans notre requête API.

Voici à quoi cela ressemble en pratique :

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

Comme précédemment, une mutation réussie renverra l'ID de l'élément que vous avez créé.

 

Création d'un nouvel élément avec les valeurs des colonnes renseignées

Dans notre dernier exemple, nous allons créer un nouvel élément et définir les valeurs de chacune de ses colonnes.

Notre schéma GraphQL définit un ensemble de valeurs de colonnes sous forme de segment JSON (paires clé-valeur). Les clés de l'objet column_values doivent être les ID des colonnes, et les valeurs doivent être structurées en fonction du type de la colonne.

Cet exemple particulier met à jour une colonne d'état et de date. Vous pouvez configurer un tableau pour cet exemple en utilisant notre modèle « Commencer de zéro ».

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

Félicitations ! Vous avez terminé ce tutoriel.

 

Faites-vous plaisir !

Vous le méritez bien. 🔮​ 

 

 

Si vous avez la moindre question, n'hésitez pas à contacter notre équipe ici. Nous sommes disponibles 24h/​24, 7j/​7 et sommes toujours heureux de vous aider.