Este artigo orientará você sobre o uso da API do GraphQL da monday.com e do Python. Ele começará de forma simples e, em seguida, continuará com consultas mais complicadas. Leia este artigo de acordo com a sua necessidade. 

 

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 Python em funcionamento no seu computador
• Uma conta ativa da monday.com (registre-se aqui se ainda não o fez)
• Um entendimento básico de APIs da web e solicitações HTTP
• Um entendimento básico do Python

 

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, especificaremos.

Execute o seguinte código em seu ambiente 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())

Você deve receber 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 um dicionário e fazer o que quiser com ele. Divirta-se!

 

Obter 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, devolveremos o nome, a ID e a descrição do quadro e, em seguida, todos os elementos do quadro. Para cada elemento, retornaremos o valor e o tipo de cada coluna. Para cada elemento, 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-o em seu ambiente 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_page { items { name column_values{id type text } } } } }'
data = {'query' : query2}

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

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 adicionando aspas duplas para o argumento "item_name", para diferenciar a cadeia de caracteres interna da própria consulta. 

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

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:

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

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").

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

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!