Leitura de 7 minutos

Recurso

Este artigo orientará você a realizar algumas operações básicas usando a API GraphQL da monday.com e, em seguida, apresentará consultas mais complicadas. Leia este artigo de acordo com a sua necessidade. Você pode baixar todo o código de amostra aqui.

Qual é a API da monday.com?

A API da monday.com permite que aplicativos externos recuperem e editem dados da Work OS da monday.com.

Por exemplo, você pode usar a API para sincronizar dados entre a monday.com e outra plataforma, para que as ações da sua equipe na monday.com sejam sincronizadas com as outras ferramentas que você usa.

Nossa API é baseada no GraphQL, que é um pouco diferente das APIs REST mais comuns. Nosso esquema GraphQL define objetos e campos que podem ser consultados por meio de nossa API.

Tópicos abordados

O que é o GraphQL e por que ele é útil
Como estruturar uma solicitação para a API monday.com
Como escrever consultas simples
Como escrever mutações para alterar dados na monday.com

Pré-requisitos

Um ambiente PHP funcionando
Uma conta ativa da monday.com (registre-se na monday.com se ainda não o fez)
Um entendimento básico de APIs da web e solicitações HTTP
Conhecimento básico de PHP

Estruturando suas solicitações de API

Há algumas coisas a ter em mente quando você está construindo sua primeira chamada de API:

Estrutura de solicitações: todas as solicitações para a API devem ser solicitações POST. As consultas devem estar de acordo com nosso esquema GraphQL
Autenticação: todas as solicitações para a API devem incluir um token de autenticação no cabeçalho da solicitação. Saiba como obter sua chave de API aqui.
Corpo da solicitação: todas as solicitações para a API devem ter um corpo formatado em JSON. A única exceção são os uploads de arquivos, que devem ser solicitações de várias partes.

Fazer a primeira chamada de API

A API monday.com pode recuperar objetos e seus campos associados ao Work OS (sistema operacional de trabalho).

Vamos começar recuperando uma lista de quadros, junto com seus nomes e IDs de quadro. Para isso, especificaremos o objeto "boards" na nossa consulta e, em seguida, executaremos o script a seguir em nosso 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);
?>

Navegue até o URL do seu servidor no navegador. Você deve ver uma resposta que contém uma lista de quadros, conforme abaixo:

Observe que os dados retornados são JSON, então você pode serializá-los em uma matriz e fazer o que quiser com ele. Iterar através dele, construir uma árvore, qualquer coisa.

Obtendo dados de elementos específicos

Agora vamos aproveitar a flexibilidade do GraphQL e voltar o nome dos elementos e colunas, assim como o tipo, título e ID de cada coluna.

Aqui está nossa consulta:

{ items (ids: [1234567890, 9876543210, 1122334455]) {
    name
    column_values {
      column {
        title
        id
        type
      } 
    } 
  } 
}

Seguindo o exemplo anterior, execute isso no seu servidor 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);
?>

Você receberá um conjunto de dados muito mais rico com essa consulta.

Criar um novo elemento.

Nesta seção, escreveremos uma mutação para criar um novo elemento no seu quadro.

Mutações são operações que adicionam ou atualizam dados e também retornam campos no objeto que foi criado ou alterado. Os dados que você está alterando são passados como argumentos para a mutação.

Aqui está a consulta que usaremos:

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

E aqui está o código para fazer essa solicitação. Observe que estamos usando aspas duplas para o argumento "item_name" para diferenciar a cadeia de caracteres interna da própria consulta.

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

Quando a mutação for bem-sucedida, você receberá uma resposta que contém a ID do elemento que acabou de criar:

Criando um novo elemento usando variáveis do GraphQL

Até agora, escrevemos consultas e mutações com valores codificados nelas. Ou seja, se eu quisesse mudar o quadro em que estou criando um elemento, teria que deslizar e dividir a cadeia de caracteres de consulta, o que pode ser caro.

No entanto, podemos preencher argumentos dinamicamente em nossa consulta usando variáveis do GraphQL. Passamos as variáveis como um objeto JSON, e o GraphQL inserirá dinamicamente as variáveis em nossa consulta!

Precisamos declarar o tipo das variáveis em nossa consulta e passar as variáveis como um objeto JSON separado dentro de nossa solicitação de API.

É assim que se parece em ação:

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

Como antes, uma mutação bem-sucedida retornará a ID do elemento que você criou.

Criando um novo elemento com valores de coluna preenchidos

Em nosso exemplo final, criaremos um novo elemento e definiremos os valores para cada uma das suas colunas.

Nosso esquema GraphQL define um conjunto de valores de coluna como uma cadeia de caracteres JSON (pares chave-valor). As chaves do objeto column_values devem ser IDs de coluna e os valores devem ser estruturados dependendo do tipo da coluna.

Este exemplo específico atualiza uma coluna de status e de data. Você pode configurar um quadro para este exemplo usando nosso template "Start from scratch" ("Começando do zero").

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

Parabéns! Você concluiu este tutorial.

Comemore!

Você merece. 🔮

Se você tiver alguma dúvida, entre em contato com nossa equipe por aqui. Estamos disponíveis 24 horas e prontos para ajudar!

Tutorial de início rápido da API - PHP