Como chamar pontos de extremidade do GraphQL

Os pontos de extremidade graphQL no DAB (Construtor de API de Dados) permitem consultar e modificar dados com precisão. Cada consulta declara exatamente quais campos você precisa e dá suporte a argumentos para filtragem, ordenação e resultados de paginação.

Por padrão, o DAB hospeda seu ponto de extremidade do GraphQL em:

https://{base_url}/graphql

As entidades expostas por meio da configuração são incluídas automaticamente no esquema GraphQL. Por exemplo, se você tiver books e authors entidades, ambos aparecerão como campos raiz no esquema.

Observação

Use qualquer cliente ou IDE moderno do GraphQL (como Apollo, Insomnia ou VS Code GraphQL) para explorar os campos de esquema e preenchimento automático.

Palavras-chave com suporte no construtor de API de Dados

Conceito	GraphQL	Propósito
Projection	items	Escolher quais campos retornar
Filtragem	filtro	Restringir linhas por condição
Classificação	orderBy	Definir a ordem de classificação
Tamanho da página	first	Limitar os itens por página
Continuação	depois	Continuar da última página

Estrutura básica

Cada consulta GraphQL começa com um campo raiz que representa uma entidade.

{
  books {
    items {
      id
      title
      price
    }
  }
}

O resultado é um objeto JSON com a mesma forma que o conjunto de seleção:

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "price": 20 },
        { "id": 2, "title": "Foundation", "price": 18 }
      ]
    }
  }
}

Observação

Por padrão, o DAB retorna até 100 itens por consulta, a menos que configurado de outra forma (runtime.pagination.default-page-size).

Tipos de consulta

Cada entidade dá suporte a duas consultas raiz padrão:

Query	Descrição
entity_by_pk	Retorna um registro por sua chave primária
entities	Retorna uma lista de registros que correspondem a filtros

Exemplo de retorno de um registro:

{
  book_by_pk(id: 1010) {
    title
    year
  }
}

Exemplo retornando muitos:

{
  books {
    items {
      id
      title
    }
  }
}

Filtrando resultados

Use o filter argumento para restringir quais registros são retornados.

{
  books(filter: { title: { contains: "Foundation" } }) {
    items { id title }
  }
}

Esta consulta retorna todos os livros cujo título contém "Foundation".

Os filtros podem combinar comparações com operadores lógicos:

{
  authors(filter: {
    or: [
      { first_name: { eq: "Isaac" } }
      { last_name: { eq: "Asimov" } }
    ]
  }) {
    items { first_name last_name }
  }
}

Consulte a referência de argumento de filtro para operadores com suporte, como eq, neq, lt, ltee isNull.

Classificando resultados

O orderBy argumento define como os registros são classificados.

{
  books(orderBy: { year: DESC, title: ASC }) {
    items { id title year }
  }
}

Isso retorna livros ordenados por year decrescente, então por title.

Consulte a referência de argumento orderBy para obter mais detalhes.

Limitando resultados

O first argumento limita quantos registros são retornados em uma única solicitação.

{
  books(first: 5) {
    items { id title }
  }
}

Isso retorna os cinco primeiros livros, ordenados por chave primária por padrão. Você também pode usar first: -1 para solicitar o tamanho máximo de página configurado.

Saiba mais na primeira referência de argumento.

Resultados contínuos

Para buscar a próxima página, use o after argumento com o cursor da consulta anterior.

{
  books(first: 5, after: "eyJpZCI6NX0=") {
    items { id title }
  }
}

O after token marca onde a página anterior terminou. Consulte a referência do argumento posterior para obter mais detalhes.

Seleção de campo (projeção)

No GraphQL, você escolhe exatamente quais campos aparecem na resposta. Não há curinga como SELECT *. Solicite apenas o que você precisa.

{
  books {
    items { id title price }
  }
}

Você também pode usar aliases para renomear campos na resposta:

{
  books {
    items {
      bookTitle: title
      cost: price
    }
  }
}

Consulte a referência de projeção de campo para obter detalhes.