# Primeiros passos com a GraphQL API Este guia orienta você na sua primeira query à GraphQL API. - Crie um personal token no Azion Console. - Consulte o total de requisições dos seus workloads com o dataset `workloadMetrics`. - Leia a resposta e o formato de um erro. - Consulte registros brutos de requisições com o dataset `workloadEvents`. Três elementos fazem uma query retornar dados, e cada um depende do anterior: 1. O **personal token** autentica a requisição no header `Authorization`. 2. O **endpoint** atende uma família de dados. `https://api.azion.com/v4/metrics/graphql` atende métricas agregadas, e `https://api.azion.com/v4/events/graphql` atende eventos brutos. 3. O **dataset** nomeado na query, como `workloadMetrics`, é a tabela de onde vêm as linhas. O endpoint precisa atender esse dataset. A GraphQL API apenas lê dados: ela não tem mutations. Para mais informações, consulte [Como a GraphQL API funciona](/pt-br/documentacao/devtools/graphql/visao-geral/). --- Selecione a interface que você vai usar. Os pré-requisitos e cada etapa abaixo seguem essa escolha. ## Pré-requisitos - Uma conta Azion. Para criar uma, consulte [Criar uma conta](/pt-br/documentacao/fundamentos/criar-uma-conta/). - Tráfego em pelo menos um workload nos últimos sete dias. Uma janela de tempo sem tráfego retorna um array vazio. **GraphiQL** - Um navegador com login no Azion Console. Para fazer login, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). **API** - `curl` ou outro cliente HTTP. Para enviar as queries pelo Postman, consulte [Execute queries GraphQL no Postman](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-graphql-postman/). --- ## Crie um personal token A GraphQL API autentica cada requisição com um personal token. Um personal token é adequado para uso com APIs porque pode ter uma expiração longa. Para criar um personal token no Azion Console: 1. **Abra a página Personal Tokens** Acesse [Azion Console](https://console.azion.com/) > **Account** > **Personal Token**. 2. **Selecione + Personal Token** 3. **Dê um nome ao token** Em **Name**, digite um nome. Por exemplo: `graphql-quickstart`. 4. **Defina a expiração** Em **Expires within**, selecione *90 days* ou *1 year*. Uma expiração mais longa é adequada para uso com APIs. Guarde o token como você guarda uma senha. 5. **Selecione Save** 6. **Copie o token** Na caixa de diálogo **Personal Token has been created**, selecione **Copy**. A caixa de diálogo mostra o token apenas uma vez. 7. **Selecione Confirm** O token aparece na página **Personal Tokens** com a sua **Expiration Date**. Para mais informações, consulte [Como criar um personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). --- ## Execute sua primeira query Esta query soma as requisições que os seus workloads receberam de `2026-09-26T14:00:00` a `2026-10-03T14:00:00`. Ela agrupa os totais por tempo, do mais recente ao mais antigo, e retorna cinco linhas. Antes de executá-la, substitua as duas datas de `tsRange` por uma janela dentro dos últimos sete dias: ```graphql query { workloadMetrics( limit: 5 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } aggregate: { sum: requests } groupBy: [ts] orderBy: [ts_DESC] ) { ts sum } } ``` `workloadMetrics` é um dataset de métricas, então a query vai para o endpoint de métricas, `https://api.azion.com/v4/metrics/graphql`. **GraphiQL** A URL do endpoint também serve o GraphiQL, um editor no navegador que escreve, valida e executa queries GraphQL. Para executar a query no GraphiQL: 1. **Faça login no Azion Console** Acesse [Azion Console](https://console.azion.com/) e faça login na sua conta. 2. **Abra o endpoint de métricas** No mesmo navegador, acesse `https://api.azion.com/v4/metrics/graphql`. 3. **Cole a query** Cole a query no editor. O GraphiQL valida cada campo enquanto você digita. 4. **Execute a query** Sem uma sessão com login, o endpoint retorna `401` com `Authentication credentials were not provided.` em vez do GraphiQL. **API** Para executar a query com `curl`, envie uma requisição `POST` ao endpoint de métricas. Substitua `[TOKEN VALUE]` pelo seu personal token: ```bash curl -X POST https://api.azion.com/v4/metrics/graphql \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -d '{"query": "query { workloadMetrics(limit: 5, filter: { tsRange: {begin: \"2026-09-26T14:00:00\", end: \"2026-10-03T14:00:00\"} }, aggregate: { sum: requests }, groupBy: [ts], orderBy: [ts_DESC]) { ts sum } }"}' ``` O corpo é um objeto JSON cuja chave `query` contém a query como string. O header usa o esquema `Token`: um header `Bearer` retorna `401` com `Authentication credentials were not provided.`, o mesmo resultado de um header ausente. O endpoint retorna HTTP `200` e as linhas. A resposta abaixo está cortada após a terceira das suas cinco linhas: ```json { "data": { "workloadMetrics": [ { "ts": "2026-10-03T13:00:00Z", "sum": 2 }, { "ts": "2026-10-03T12:00:00Z", "sum": 2 }, { "ts": "2026-10-03T03:00:00Z", "sum": 2 }, … ] } } ``` Cada linha é uma hora da janela que recebeu requisições, com o total de requisições em `sum`. --- ## Leia a resposta Uma resposta da GraphQL API é um objeto JSON. A chave `data` contém um array por dataset da query, com o nome do dataset: `data.workloadMetrics` para a query de Execute sua primeira query. O array contém um objeto por linha, e cada objeto traz apenas os campos que a query selecionou. A resposta de `workloadMetrics` se lê assim: - `ts` é o bucket de tempo em UTC. Uma janela de sete dias retorna buckets de uma hora. - `sum` é o total de `requests` nesse bucket, com o nome da função de agregação em `aggregate: { sum: requests }`. - As linhas seguem `orderBy`, aqui `ts_DESC`, da mais recente à mais antiga. - `limit` limita o número de linhas. O padrão é `10`, e o argumento aceita até `10000`. Uma janela sem dados retorna um array vazio com HTTP `200`, não um erro. Uma query que a API recusa retorna um status HTTP de erro e uma chave `detail` no lugar de `data`. Datasets de métricas e de eventos exigem uma janela de tempo, então esta query, que não tem `filter`, é recusada: ```graphql query { workloadMetrics(limit: 3, aggregate: { sum: requests }, groupBy: [ts]) { ts sum } } ``` A API retorna HTTP `400`: ```json { "detail": "To execute queries it is mandatory to provide the desired time interval." } ``` Todo erro da GraphQL API tem este formato `detail`, não um array `errors` do GraphQL. Para cada mensagem e a sua causa, consulte [Mensagens de erro](/pt-br/documentacao/devtools/graphql/mensagens-erro/). --- ## Consulte eventos brutos Eventos brutos são os registros de requisições individuais, uma linha por requisição, sem agregação. O dataset `workloadEvents` contém esses registros, e o endpoint de eventos, `https://api.azion.com/v4/events/graphql`, atende esse dataset. O endpoint de métricas recusa datasets de eventos com `400` e `Cannot query field "workloadEvents" on type "Query".` Esta query retorna o horário, o host, o código de status e a URI das cinco requisições mais recentes. 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 { workloadEvents( limit: 5 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } orderBy: [ts_DESC] ) { ts host status requestUri } } ``` **GraphiQL** Para executar a query no GraphiQL: 1. **Abra o endpoint de eventos** Em um navegador com login no Azion Console, acesse `https://api.azion.com/v4/events/graphql`. 2. **Cole a query** 3. **Execute a query** **API** Para executar a query com `curl`, envie uma requisição `POST` ao endpoint de eventos. Substitua `[TOKEN VALUE]` pelo seu personal token: ```bash curl -X POST https://api.azion.com/v4/events/graphql \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -d '{"query": "query { workloadEvents(limit: 5, filter: { tsRange: {begin: \"2026-09-26T14:00:00\", end: \"2026-10-03T14:00:00\"} }, orderBy: [ts_DESC]) { ts host status requestUri } }"}' ``` O endpoint retorna HTTP `200` e um objeto por requisição. A resposta abaixo está cortada após a terceira das suas cinco linhas: ```json { "data": { "workloadEvents": [ { "ts": "2026-10-03T13:34:44Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T13:16:33Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T12:53:40Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, … ] } } ``` Cada linha é uma requisição, sem `groupBy` e sem agregação. Os dados de faturamento, contabilidade e consumo têm os seus próprios endpoints, que recebem a mesma requisição `POST` e o mesmo header `Authorization`: `https://api.azion.com/v4/billing/graphql`, `https://api.azion.com/v4/accounting/graphql` e `https://api.azion.com/v4/consumption/graphql`. Os datasets e os filtros de tempo desses endpoints estão em [Queries](/pt-br/documentacao/devtools/graphql/queries/). No GraphiQL, a URL da página é atualizada com um parâmetro codificado após a execução de uma query. Copie essa URL para compartilhar a query com outro usuário. --- ## Próximos passos - [Como a GraphQL API funciona](/pt-br/documentacao/devtools/graphql/visao-geral.md): Os endpoints, os datasets que cada um atende e a diferença entre dados agregados e brutos. - [Queries](/pt-br/documentacao/devtools/graphql/queries.md): Formatos de query para dados brutos, agregados, financeiros e de uso, com uma resposta para cada um. - [GraphiQL Playground](/pt-br/documentacao/devtools/graphql/playground-graphql.md): Queries de exemplo para executar e adaptar no editor do navegador. - [Guias da GraphQL API](/pt-br/documentacao/devtools/graphql/guias.md): Queries para top URIs, top ataques, top IPs atacantes, usuários conectados e metadados.