Pouvons-nous vous aider?

Tutoriel de démarrage rapide pour l'API - PHP

 

Cet article vous expliquera comment effectuer quelques opérations de base à l'aide de l'API GraphQL de monday.com, avant de passer à des requêtes plus complexes. Vous pouvez le parcourir aussi rapidement ou lentement que vous le souhaitez. Vous pouvez télécharger tous les exemples de code ici.

 

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 PHP fonctionnel
  • Un compte monday.com actif (inscrivez-vous sur monday.com si vous n'y êtes pas encore)
  • Une compréhension de base des API web et des requêtes HTTP
  • Une compréhension de base du PHP 

 

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 leur nom et leur identifiant. Pour ce faire, nous allons spécifier l'objet « tableaux » dans notre requête, puis exécuter le script suivant sur le serveur 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);
?>

Accédez à l'URL de votre serveur sur votre navigateur. Vous devriez obtenir une réponse contenant une liste de tableaux, comme ceci :

instal.png

Remarquez que les données renvoyées sont au format JSON. Vous pouvez donc les sérialiser dans un tableau et en faire ce que vous voulez. Effectuez des itérations, 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, exécutez ceci sur votre serveur PHP :

<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = '{boards(limit:1) { name id items { name column_values{id type 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);
?>

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.

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

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 :

mceclip0_1.png

 

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 :

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

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 ».

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

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.