--- name: azion-gere-queries-graphql-com-o-mcp-server description: >- Peça a um agente de código conectado ao MCP server de observe da Azion uma query GraphQL que responda a um objetivo de dados e execute-a com a GraphQL API. --- # Gere queries GraphQL com o MCP server Você pode pedir a um agente de código conectado ao servidor de observe dos [MCP servers da Azion](/pt-br/documentacao/devtools/mcp/) uma query da [GraphQL API](/pt-br/documentacao/devtools/graphql/) que responda a um objetivo, como o tráfego dos seus workloads por localização ou o status de cache das suas imagens. Em seguida, você executa a query com a GraphQL API e lê as linhas que ela retorna. Para escrever e executar uma query sem um agente, consulte [Primeiros passos com a GraphQL API](/pt-br/documentacao/devtools/graphql/primeiros-passos/). --- ## Pré-requisitos - Um agente de código conectado ao servidor de observe, `https://observe-mcp.azion.com/mcp`. Para conectar um, consulte [Primeiros passos com o MCP server](/pt-br/documentacao/devtools/mcp/primeiros-passos/). - Um personal token, para executar a query com a GraphQL API. Para criar um, consulte [Gerencie personal tokens](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). --- ## Gere uma query com o seu agente O servidor de observe escreve queries com a ferramenta `create_graphql_query`. A ferramenta recebe duas entradas: `query`, o objetivo em palavras simples, e `dataSource`, os dados que a query lê. Um modelo de linguagem escreve a query, e a ferramenta a executa na GraphQL API da sua conta, com o seu token, para validá-la. Essas queries de validação apenas leem dados. Para gerar uma query: 1. **Peça uma query ao seu agente** Descreva os dados que você quer, a janela de tempo e como agrupar as linhas. Informe a fonte de dados que o objetivo lê: `real-time-metrics`, `real-time-events`, `accounting` ou `consumption`. O agente ajusta os intervalos de datas e os filtros aos seus requisitos. 2. **Revise a resposta da ferramenta** A ferramenta retorna uma query que executa na sua conta, ou este texto quando nenhuma tentativa produz uma: ```text It was not possible to retrieve the requested information with GraphQL. ``` Em seguida, o texto aponta para a documentação da GraphQL API. Um modelo de linguagem escreve cada query, então duas chamadas com o mesmo objetivo podem retornar queries diferentes. Quando a ferramenta retornar esse texto, consulte [Solucionar problemas do MCP server](/pt-br/documentacao/devtools/mcp/solucao-de-problemas/). 3. **Execute a query** Envie a query ao endpoint da GraphQL API do dataset dela com o seu personal token, ou cole-a no GraphiQL. Para os dois caminhos, consulte [Primeiros passos com a GraphQL API](/pt-br/documentacao/devtools/graphql/primeiros-passos/) e [GraphiQL Playground](/pt-br/documentacao/devtools/graphql/playground-graphql/). 4. **Leia a resposta** A chave `data` da resposta contém um array por dataset, com um objeto por linha. Para o que cada campo traz, consulte [Campos do Real-Time Metrics](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-metrics/) e [Campos do Real-Time Events](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-events/). A resposta traz as linhas que respondem ao seu objetivo. As duas seções a seguir trazem, cada uma, um objetivo, o pedido ao agente e uma query que o responde, para que você confira uma proposta ou execute a query quando a ferramenta não retornar nenhuma. --- ## Consulte o tráfego dos seus workloads por localização Este objetivo pede as requisições dos últimos sete dias, agrupadas pela localização da Azion que as recebeu. Peça ao seu agente: ```text Crie uma query GraphQL para mostrar o tráfego da minha aplicação dos últimos 7 dias, agrupado por localização da Azion. ``` Uma query que responde a este objetivo lê `workloadMetrics`, um dataset de métricas, então ela executa no endpoint de métricas, `https://api.azion.com/v4/metrics/graphql`. Ela soma `requests` por `sourceLocPop`, a localização do servidor da Azion que recebeu a requisição, e retorna até 10 localizações, primeiro as que têm mais requisições. Antes de executá-la, substitua as duas datas de `tsRange` pelos últimos sete dias: ```graphql query TrafficByLocation { workloadMetrics( limit: 10 filter: { tsRange: {begin: "2026-09-28T00:00:00", end: "2026-10-05T00:00:00"} } aggregate: { sum: requests } groupBy: [sourceLocPop] orderBy: [sum_DESC] ) { sourceLocPop sum } } ``` O endpoint retorna HTTP `200` e uma linha por localização, com o total de requisições em `sum`. A resposta abaixo está cortada após a terceira linha: ```json { "data": { "workloadMetrics": [ { "sourceLocPop": "sdu-eqn", "sum": 2778 }, { "sourceLocPop": "cgh-eqn", "sum": 2184 }, { "sourceLocPop": "cgh-act", "sum": 1039 }, … ] } } ``` --- ## Consulte o status de cache das suas imagens Este objetivo pergunta como o cache respondeu às requisições de arquivos de imagem. Peça ao seu agente: ```text Gere uma query para analisar taxas de cache hit para minhas imagens. ``` Uma query que responde a este objetivo lê `workloadEvents`, um dataset de eventos, então ela executa no endpoint de eventos, `https://api.azion.com/v4/events/graphql`. Ela mantém as requisições cuja URI corresponde a `%.jpg`, `%.png` ou `%.webp` em `requestUriLike` e as conta por `upstreamCacheStatus`. Datasets de eventos guardam registros por cerca de sete dias, então substitua as datas de `tsRange` por uma janela dentro da última semana: ```graphql query CachePerformance { workloadEvents( limit: 10 filter: { tsRange: {begin: "2026-09-28T00:00:00", end: "2026-10-05T00:00:00"} or: [ { requestUriLike: "%.jpg" } { requestUriLike: "%.png" } { requestUriLike: "%.webp" } ] } aggregate: { count: rows } groupBy: [upstreamCacheStatus] orderBy: [count_DESC] ) { upstreamCacheStatus count } } ``` O endpoint retorna HTTP `200` e uma linha por status de cache, com a contagem de requisições em `count`. A resposta contém: ```json { "data": { "workloadEvents": [ { "upstreamCacheStatus": "MISS", "count": 19 }, { "upstreamCacheStatus": "REVALIDATED", "count": 19 } ] } } ``` Compare a contagem de cada status com o total de todas as linhas. Para cada valor de status de `upstreamCacheStatus`, como `HIT` e `MISS`, consulte [Campos do Real-Time Events](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-events/). --- ## Próximos passos - [Primeiros passos com a GraphQL API](/pt-br/documentacao/devtools/graphql/primeiros-passos.md): Crie um personal token, execute uma primeira query e leia a resposta. - [Campos do Real-Time Metrics](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-metrics.md): Todos os campos dos datasets de métricas, para agrupar e filtrar as linhas de uma query. - [Campos do Real-Time Events](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-events.md): Todos os campos dos datasets de eventos, como o status de cache de cada requisição. - [Ferramentas e recursos](/pt-br/documentacao/devtools/mcp/ferramentas.md): As entradas e a resposta de cada ferramenta que o MCP server expõe.