7 minutos de lectura
Función
Este artículo te explicará cómo realizar algunas operaciones básicas con la API GraphQL de monday.com y, luego, cómo realizar consultas más complicadas. Tómate tu tiempo para revisarlo a tu modo. Puedes descargar todo el código de muestra aquí.
¿Qué es la API de monday.com?
Con la API de monday.com, las aplicaciones externas pueden recuperar y editar datos del sistema operativo de trabajo monday.com.
Por ejemplo, puedes usar la API para sincronizar datos entre monday.com y otra plataforma, para que las acciones del equipo en monday.com estén sincronizadas con las otras herramientas que usas.
Nuestra API se basa en GraphQL, que es un poco diferente de las API REST, que probablemente ya conozcas. Nuestro esquema GraphQL define objetos y campos que se pueden consultar a través de nuestra API.
Temas que trataremos
- Qué es GraphQL y por qué es útil
- Cómo estructurar una solicitud a la API de monday.com
- Cómo escribir consultas sencillas
- Cómo escribir mutaciones para cambiar los datos en monday.com
Requisitos previos
- Un entorno de PHP en funcionamiento
- Una cuenta activa de monday.com (regístrate en monday.com si aún no lo has hecho)
- Entendimiento básico de las API web y las solicitudes HTTP
- Entendimiento básico de PHP
Estructurar las solicitudes de API
Hay algunas cosas que debes tener en cuenta al crear tu primera solicitud de API:
- Estructura de la solicitud: todas las solicitudes a la API deben ser solicitudes POST. Las solicitudes deben ajustarse a nuestro esquema de GraphQL
- Autenticación: todas las solicitudes a la API deben incluir un token de autenticación en el encabezado de la solicitud. Aprende a cómo obtener tu clave de API aquí.
- Cuerpo de la solicitud: todas las solicitudes a la API deben tener un cuerpo con formato JSON. La única excepción son las cargas de archivos, que deben ser solicitudes multiparte.
Realiza tu primera solicitud a la API
La API de monday.com puede recibir objetos y sus campos asociados del sistema operativo de trabajo (Work OS).
Comencemos por obtener una lista de los tableros junto con sus nombres y los ID del tablero. Para ello, especificaremos el objeto "tableros" en nuestra búsqueda y luego ejecutaremos el siguiente script en tu servidor 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);
?>
Dirígete a la URL de tu servidor en tu navegador. Deberás ver una respuesta que contenga una lista de tableros, de esta forma:
Ten en cuenta que los datos recibidos son JSON, por lo que puedes serializarlos en una matriz y hacer lo que quieras con ellos. Itera a través del texto, construye un gráfico de árbol, ¡lo que se te ocurra!
Obtener datos de elementos específicos
Ahora aprovechemos la flexibilidad de GraphQL y devolvamos el nombre y las columnas del elemento, así como el tipo, título e ID de cada columna.
Esta es nuestra consulta:
{ items (ids: [1234567890, 9876543210, 1122334455]) {
name
column_values {
column {
title
id
type
}
}
}
}
Siguiendo el ejemplo anterior, ejecuta esto en tu servidor de PHP:
<?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);
?>
Recibirás un conjunto de datos mucho más completo con esta consulta.
Crear un elemento nuevo
En esta sección, escribiremos una mutación para crear un elemento nuevo en tu tablero.
Las mutaciones son operaciones que agregan o actualizan datos, y también devuelven campos en el objeto que se creó o cambió. Los datos que cambias se pasan como argumentos en la mutación.
Aquí puedes ver la consulta que usaremos:
mutation {
create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {
id
} }
Y aquí está el código para realizar esta solicitud. Observa que estamos usando comillas dobles para el argumento "item_name", para diferenciar la cadena interna de la consulta en sí.
<?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);
?>
Cuando la mutación es exitosa, recibirás una respuesta que contenga el Id. del elemento que acabas de crear:
Crear un nuevo elemento usando variables de GraphQL
Hasta ahora, hemos estado escribiendo consultas y mutaciones con valores codificados en ellas. Es decir, si quisiera cambiar el tablero en el que estoy creando un elemento, tendría que reestructurar y editar la cadena de consulta de nuevo, lo cual puede ser costoso.
Sin embargo, podemos rellenar de forma dinámica los argumentos de nuestra consulta utilizando variables de GraphQL. Pasamos las variables como un objeto JSON y ¡GraphQL insertará dinámicamente las variables en nuestra consulta!
Necesitamos declarar el tipo de variables en nuestra consulta y pasar las variables como un objeto JSON separado dentro de la solicitud API.
Así es como se ve en acción:
<?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);
?>
Igual que antes, una mutación exitosa devolverá el Id. del elemento que creaste.
Crear un elemento nuevo con valores de columna completados
En nuestro ejemplo final, crearemos un nuevo elemento y definiremos los valores para cada una de sus columnas.
Nuestro esquema de GraphQL define un conjunto de valores de columna como una cadena JSON (pares clave-valor). Las claves del objeto column_values deben ser Id. de columnas y los valores deben estar estructurados según el tipo de columna.
Este ejemplo en particular actualiza una columna Estado y Fecha. Puedes configurar un tablero para este ejemplo, usando nuestra plantilla para "Empezar desde cero".
<?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);
?>
¡Felicitaciones! Has completado este tutorial.
¡Tómate un descanso!
Te lo mereces. 🔮
Si tienes preguntas, comunícate con nuestro equipo aquí. Estamos disponibles las 24 horas, los 7 días de la semana, y será un gusto ayudarte.
Comentarios