Ir para conteúdo principal

Acesso a Queries por API GraphQL

Saiba como utilizar este recurso para criar consultas personalizadas - integração externa.

Intercom avatar
Escrito por Intercom
Atualizado há mais de 3 semanas

O que significa acesso a queries por API GraphQL?

O GraphQL é uma linguagem de consulta poderosa que permite buscar dados de forma flexível e eficiente, direto do seu sistema Keepfy. Com esse recurso, você pode criar consultas personalizadas para extrair dados específicos de consultas que o sistema já utiliza, como ordens de serviço, e utilizá-las em ferramentas externas.

Imagine gerar dashboards dinâmicos ou relatórios customizados em outros sistemas que permitem esse tipo de consulta, como é o caso do Microsoft Power Bi. Isso significa mais controle e autonomia para transformar os dados do Keepfy em insights valiosos para o seu negócio.

Qual o objetivo deste artigo?

Nosso objetivo aqui é apresentar uma pequena introdução das possibilidades da API GraphQL do Keepfy e como ela pode agregar valor ao seu dia a dia. No entanto, vale destacar que, para trabalhar com essa API, é necessário um certo nível de conhecimento em programação e familiaridade com a lógica do GraphQL. Este artigo serve como ponto de partida, mas pressupomos que o cliente ou desenvolvedor que for utilizá-la já tenha noções básicas de como construir consultas e integrar APIs em suas ferramentas.

É importante destacar que não oferecemos suporte para construção ou manutenção dos modelos específicos que foram construídos, mas podemos oferecer parceiros que o fazem.

Por onde começar?

O caminho ideal é começar consultando a nossa documentação oficial aqui. Lá você encontra detalhes sobre as queries disponíveis e exemplos para começar a usar.

Por quê eu não vejo a seção Integrações Externas em Minha Conta?

Se você não está vendo a opção de Integrações Externas no Keepfy, é porque esse acesso precisa ser liberado internamente para sua organização. Para ativar, entre em contato conosco pelo chat de atendimento e faça a requisição. Nosso time de produto vai liberar este recurso para você.

Como eu posso utilizar?

A API GraphQL do Keepfy abre portas para diversas possibilidades, e uma das formas mais práticas de gerar valor é integrá-la ao Microsoft Power BI para buscar dados e criar relatórios personalizados. Abaixo, mostramos os passos principais para começar com um exemplo de busca por dados de ordens de serviço.

Importante: Embora apresentemos os exemplos de consulta abaixo e de poder auxiliar no entendimento de algumas consultas, não oferecemos suporte direto ao Microsoft Power BI nem podemos auxiliar na construção dos seus modelos DAX nesta ferramenta — os exemplos abaixo são apenas um ponto de partida.

Como gerar o token de acesso via função no Microsoft Power Bi?

Após gerar seu accessKey e accessSecret pelo Keepfy é possível a partir da funcionalidade 'Criar consulta em branco' no editor avançado do Power Query criar uma função que irá auxiliar na geração do token. É este token que permite o acesso acesso para futuras consultas na busca pelos dados subjacentes.

Para criar a consulta que retorna o token, utilize os passos abaixo:

  1. Clique em 'Obter Dados' > 'Consulta em Branco' (ou Consulta Nula);

  2. Após abrir o editor de Power Query, clique em 'Editor Avançado';

  3. Insira o script de exemplo abaixo e adicione o acessKey e acessSecret nos locais indicados;

  4. Após revisar, clique em 'Concluído';

  5. Agora, renomeie a consulta para GetAccessToken - o nome geralmente está presente no painel de propriedades à direita;

  6. Se nenhum erro for apresentado, ela está pronta para ser utilizada posteriormente;

  7. Permaneça no editor Power Query para a próxima consulta.

Esse é um exemplo que irá retornar o token a partir da execução da mutation denominada createAccessToken:

// Função para obter o token de autenticação via mutation GraphQL
() =>
let
// URL do endpoint GraphQL
url = "https://app.keepfy.com/graphql",

// Mutation GraphQL para criar o token usando accessKey e accessSecret
// Substitua "insira_aqui_seu_accessKey" e "insira_aqui_seu_accessSecret" pelos valores reais, mantendo as respectivas contras-barras.
body = "{
""query"": ""mutation{createAccessToken(fields:{accessKey:\""insira_aqui_seu_accessKey\"",accessSecret:\""insira_aqui_seu_accessSecret\""}){token}}""
}",

// Faz a requisição HTTP POST para a API
Source = Web.Contents(url, [
Headers = [#"Content-Type" = "application/json"],
Content = Text.ToBinary(body) // Envia o corpo JSON
]),

// Converte a resposta JSON em uma estrutura de dados
JsonResponse = Json.Document(Source),

// Extrai o token da resposta
Token = JsonResponse[data][createAccessToken][token]
in
Token // Retorna o token de autenticação

Como criar uma consulta para obter dados de ordens de serviço via função no Microsoft Power Bi?

Agora que possuímos a função para gerar o token, podemos explorar a criação de uma função que irá realizar a busca de dados de ordens de serviço.

No exemplo abaixo, estamos buscando por ordens de serviço abertas, especificando a busca para trazer algumas colunas dessa entidade, determinada pelo "items" da query ServiceOrders.

É importante notar que essa consulta requer um trabalho de paginação, pois espera-se um grande volume de dados, portanto, o exemplo abaixo está preparado para iterar até que todas as ordens sejam carregadas ao modelo. É importante considerar isso em seus trabalhos futuros.

Para criar a consulta que retorna estes dados, utilize os passos abaixo:

  1. Ainda no editor Power Query, acesse 'Nova Fonte' > 'Consulta Nula';

  2. Clique em 'Editor Avançado';

  3. Insira o script de exemplo abaixo. Após revisar, clique em 'Concluído';

  4. Como a consulta já está preparada para iterar e trazer todas as OSs em aberto da organização, é provável que seja observado um tempo de processamento.

  5. A consulta também está preparada para converter a visualização da lista de objetos para tabela.

// Função para buscar ordens de serviço da API GraphQL
let
FetchPage = (skip as number) =>
let
// Obtém o token de autenticação
token = GetAccessToken(),

// URL do endpoint GraphQL
url = "https://app.keepfy.com/graphql",

// Query GraphQL para buscar ordens de serviço
QueryText = "query ServiceOrders($pagination: Pagination, $query: ServiceOrderQueryInput!) { serviceOrders(pagination: $pagination, query: $query) { items { id code branchId equipment { tag } service observation situation createdAt foreseenCost doneCost } hasMore } }",

// Constrói o corpo da requisição com a query e variáveis
body = Json.FromValue([
query = QueryText,
variables = [
pagination = [skip = skip, limit = 250], // Busca 250 registros por página
query = [filter = [situations = {"Opened", "Closed"}]] // Filtra por situation = "Opened"
]
]),

// Faz a requisição HTTP POST para a API
Source = Web.Contents(url, [
Headers = [#"access-token" = token, #"Content-Type" = "application/json"],
Content = body // Envia o corpo JSON
]),

// Converte a resposta JSON em uma estrutura de dados
JsonData = Json.Document(Source),

// Acessa os dados da resposta (data -> serviceOrders)
Data = JsonData[data][serviceOrders],

// Extrai a lista de ordens de serviço e o indicador de mais páginas
Items = Data[items],
HasMore = Data[hasMore]
in
[Items = Items, HasMore = HasMore], // Retorna itens e hasMore

// Itera sobre todas as páginas, começando com skip = 0
AllItems = List.Generate(
() => [Skip = 0, Result = FetchPage(0), Items = Result[Items], HasMore = Result[HasMore]], // Inicia com a primeira página
each [HasMore] = true, // Continua enquanto houver mais páginas
each [Skip = [Skip] + 250, Result = FetchPage([Skip]), Items = [Items] & Result[Items], HasMore = Result[HasMore]], // Incrementa skip e acumula itens
each [Items] // Seleciona apenas os itens para combinar
),

// Combina todas as listas de itens em uma única lista
CombinedItems = List.Combine(AllItems),

// Converte a lista de registros em uma tabela
TableResult = Table.FromRecords(CombinedItems),

// Expande a coluna equipment para incluir o campo tag como uma nova coluna
ExpandedTable = Table.ExpandRecordColumn(TableResult, "equipment", {"tag"}, {"equipment.tag"})
in
ExpandedTable // Retorna todas as ordens de serviço


Se tudo der certo com a consulta, teremos ao final uma tabela carregada semelhante a está:

A partir de agora é possível utilizar as tabelas carregadas para gerar dashboards e indicadores personalizados.

Restrições de Uso

Para garantir a estabilidade do sistema e evitar sobrecarga, temos algumas recomendações e limites:

  • Frequência de consultas: Recomendamos que você configure suas buscas para rodar apenas uma vez por dia. Após construir seus modelos semânticos (como dashboards ou relatórios), planeje a execução diária para manter tudo funcionando sem problemas.

  • Bloqueio por excessos: Se identificarmos um volume excessivo de requisições diárias por meio deste canal, elas serão bloqueadas para proteger a performance do sistema. Planeje bem o uso para evitar interrupções.

Isto respondeu à sua pergunta?