Este artigo irá guiá-lo no uso da API GraphQL da monday.com e Python. Começará de forma simples e, em seguida, avançará para consultas mais complicadas. Sinta-se à vontade para percorrê-lo tão rapidamente ou lentamente quanto desejar.
O que é a API da monday.com?
A API da monday.com permite que aplicativos externos recuperem e editem dados do sistema operacional de trabalho da monday.com.
Por exemplo, você pode usar a API para sincronizar dados entre a monday.com e outra plataforma, de modo que as ações da sua equipe na monday.com sejam sincronizadas com as outras ferramentas que você utiliza.
A API da monday.com é construída sobre GraphQL, que é um pouco diferente das APIs REST que você pode estar acostumado. O esquema GraphQL define objetos e campos que podem ser consultados através da nossa API.
Tópicos abordados
- O que é GraphQL e por que é útil
- Como estruturar uma solicitação para a API da monday.com
- Como escrever consultas simples
- Como escrever mutações para alterar dados na monday.com
Pré-requisitos
- Um ambiente Python funcional no seu computador
- Uma conta ativa na monday.com (inscreva-se aqui se ainda não tiver)
- Uma compreensão básica de APIs web e requisições HTTP
- Uma compreensão básica de Python
Estruturando suas requisições de API
Há algumas coisas a ter em mente ao construir sua primeira chamada de API:
- Estrutura da Requisição: todas as requisições para a API devem ser requisições POST. As consultas devem estar em conformidade com nosso esquema GraphQL.
- Autenticação: todas as requisições para a API devem incluir um token de autenticação no cabeçalho da requisição. Aprenda como obter sua chave de API aqui.
- Corpo da Requisição: todas as requisições para a API devem ter um corpo formatado em JSON. A única exceção são os uploads de arquivos, que devem ser requisições multipart.
Fazendo sua primeira chamada de API
A API da monday.com pode recuperar objetos e seus campos associados do Work OS.
Vamos começar recuperando uma lista de quadros, junto com seus nomes e IDs. Para fazer isso, especificaremos o objeto “boards” em nossa consulta, e então especificaremos
Execute o seguinte código em seu ambiente Python:
import requests
import json
apiKey = "SUA_CHAVE_API_AQUI"
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) # fazer requisição
print(r.json())
Você deve receber uma resposta que contém uma lista de quadros, assim:
Note que os dados retornados estão em JSON, então você pode serializá-los em um dicionário e fazer o que quiser com eles. Percorra-os; construa uma árvore; divirta-se.
Obtendo todos os dados de um quadro
Agora vamos aproveitar a flexibilidade do GraphQL e retornar um conjunto mais completo de dados para um determinado quadro. Especificamente, retornaremos o nome, ID e descrição do quadro e, em seguida, todos os itens no quadro. Para cada item, retornaremos o valor e o tipo de cada coluna.
Aqui está nossa consulta:
{
boards (limit:1) {
name
id
description
items_page {
items {
name
column_values {
id
type
text
} } } } }
Seguindo o exemplo anterior, cole isso em seu ambiente Python:
import requests
import json
apiKey = "SUA_CHAVE_API_AQUI"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query2 = '{boards(limit:1) { name id description items_page { items { name column_values{id type text } } } } }'
data = {'query' : query2}
r = requests.post(url=apiUrl, json=data, headers=headers) # fazer requisição
print(r.json())
Você receberá um conjunto de dados muito mais rico com esta consulta.
Criando um novo item
Nesta seção, escreveremos uma mutação para criar um novo item em seu quadro.
Mutações são operações que adicionam ou atualizam dados e também retornam campos do 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: SEU_ID_DE_QUADRO_AQUI, item_name: "OLÁ MEUS AMIGOS!") {
id
} }
E aqui está o código para fazer essa requisição. Note que estamos usando aspas duplas para o argumento “item_name”, para diferenciar a string interna da própria consulta.
import requests
import json
apiKey = "SUA_CHAVE_API_AQUI"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query3 = 'mutation{ create_item (board_id:SEU_ID_DE_QUADRO, item_name:"OLÁ MEUS AMIGOS!") { id } }'
data = {'query' : query3}
r = requests.post(url=apiUrl, json=data, headers=headers) # fazer requisição
print(r.json())
Quando a mutação for bem-sucedida, você receberá uma resposta que contém o ID do item que acabou de criar.
Criando um novo item usando variáveis GraphQL
Até agora, temos escrito consultas e mutações com valores codificados. Ou seja, se eu quisesse mudar o quadro no qual estou criando um item, teria que modificar a string da consulta, o que pode ser custoso.
No entanto, podemos preencher dinamicamente argumentos em nossa consulta usando variáveis GraphQL. Passamos as variáveis como um objeto JSON, e o GraphQL irá 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 requisição API.
Veja como isso funciona na prática:
import requests
import json
apiKey = "SUA_CHAVE_API_AQUI"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query4 = 'mutation ($myItemName: String!) { create_item (board_id:SEU_ID_DE_QUADRO, item_name:$myItemName) { id } }'
vars = {'myItemName' : 'Olá a todos!'}
data = {'query' : query4, 'variables' : vars}
r = requests.post(url=apiUrl, json=data, headers=headers) # fazer requisição
print(r.json())
Como antes, uma mutação bem-sucedida retornará o ID do item que você criou.
Criando um novo item com valores de coluna preenchidos
No nosso exemplo final, criaremos um novo item e definiremos os valores para cada uma de suas colunas.
Nosso esquema GraphQL define um conjunto de valores de coluna como uma string 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 uma coluna de data. Você pode configurar um quadro para este exemplo usando nosso modelo “Começar do zero”.
import requests
import json
apiKey = "SUA_CHAVE_API_AQUI"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}
query5 = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:SEU_ID_DE_QUADRO, item_name:$myItemName, column_values:$columnVals) { id } }'
vars = {
'myItemName' : 'Olá a todos!',
'columnVals' : json.dumps({
'status' : {'label' : 'Concluído'},
'date4' : {'date' : '1993-08-27'}
})
}
data = {'query' : query5, 'variables' : vars}
r = requests.post(url=apiUrl, json=data, headers=headers) # fazer requisição
print(r.json())
Parabéns! Você completou este tutorial.
Dê-se um presente!
Você merece. 🔮
Ainda precisa de assistência? Acesse o suporte da monday.com.
Sabia que a Audatia é parceira oficial da monday.com no Brasil? Ajudamos times a extrair o máximo da ferramenta com consultoria especializada e treinamentos focados na sua operação. Conheça nossos serviços →
