Como invocar endpoints GraphQL

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

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

https://{base_url}/graphql

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

Observação

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

Palavras-chave suportadas no construtor de API de dados

Concept	GraphQL	Propósito
Projection	items	Escolha quais campos retornar
Filtering	filtrar	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	após	Continuar a partir 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 do 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 suporta duas consultas raiz padrão:

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

Exemplo de retorno de um registro:

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

Exemplo de retorno de múltiplos resultados

{
  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 "Fundação".

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 suportados como eq, neq, lt, ltee isNull.

Ordenar 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 descendentes, depois por title.

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

Limitar os 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 }
  }
}

after marca onde a página anterior terminou. Consulte após a referência de argumento 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 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.