Pontos de extremidade do Host GraphQL no construtor de API de dados

As entidades configuradas para estarem disponíveis via GraphQL estão disponíveis no caminho padrão: https://{base_url}//graphql. O construtor de API de dados gera automaticamente um esquema GraphQL com campos de consulta e mutação para todas as entidades configuradas. O esquema GraphQL pode ser explorado usando um cliente GraphQL moderno que inclui recursos como preenchimento automático.

Se você seguiu o Introdução exemplo, onde há o books e a entidade authors configurada para acesso ao GraphQL, você pode ver como é fácil usar o GraphQL.

Formato do conjunto de resultados

O resultado retornado é um objeto JSON com este formato:

{
    "data": {}    
}

Tipos de raiz suportados

O construtor de API de dados suporta os seguintes tipos de raiz GraphQL:

ConsultasMutações

Consultas

Cada entidade tem apoio para as seguintes ações:

• Paginação
• Consulta por chave primária
• Consulta Genérica

O construtor de API de dados, a menos que especificado de outra forma, usa o singular nome de uma entidade sempre que se espera que a consulta retorne um único item. Por outro lado, o construtor de API de dados usa o plural nome de uma entidade sempre que se espera que a consulta retorne uma lista de itens. Por exemplo, a entidade book tem:

• book_by_pk(): para devolver zero ou uma entidade
• books(): para retornar uma lista de zero ou mais entidades

Paginação

Todos os tipos de consulta que retornam zero ou mais itens suportam paginação:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

• O objeto item permite o acesso aos campos da entidade
• hasNextPage é definido como true se houver mais itens a serem devolvidos
• endCursor retorna uma cadeia de caracteres de cursor opaca que pode ser usada com parâmetros de consulta first e after para obter o próximo conjunto (ou página) de itens.

Consulta por chave primária

Cada entidade suporta a recuperação de um item específico por meio de sua Chave Primária, usando o seguinte formato de consulta:

<entity>_by_pk(<pk_colum>:<pk_value>)
{
    <fields>
}

Por exemplo:

{
  book_by_pk(id:1010) {
    title
  }
}

Consulta genérica

Cada entidade também suporta um padrão de consulta genérico para que você possa pedir apenas os itens desejados, na ordem desejada, usando os seguintes parâmetros:

• filter: filtra os itens devolvidos
• orderBy: define como os dados retornados são classificados
• first e after: Devolve apenas os principais itens n

Por exemplo:

{
  authors(
    filter: {
        or: [
          { first_name: { eq: "Isaac" } }
          { last_name: { eq: "Asimov" } }
        ]
    }
  ) {
    items {
      first_name
      last_name
      books(orderBy: { year: ASC }) {
        items {
          title
          year
        }
      }
    }
  }
}

filter

O valor do parâmetro filter é expressão de predicado (uma expressão que retorna um valor booleano) usando campos de entidade. Apenas os itens em que a expressão é avaliada como 'Verdadeiro' são incluídos na resposta. Por exemplo:

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

Esta consulta devolve todos os livros com a palavra Foundation no título.

Os operadores suportados pelo parâmetro filter são:

orderBy

O valor do orderby definir a ordem com a qual os itens no conjunto de resultados são retornados. Por exemplo:

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

Esta consulta devolve livros ordenados por title.

first e after

O parâmetro first limita o número de itens retornados. Por exemplo:

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

Esta consulta retorna os cinco primeiros livros. Quando nenhuma orderBy é especificada, os itens são ordenados com base na chave primária subjacente. O valor fornecido a orderBy deve ser um número inteiro positivo.

Se houver mais itens na entidade book do que as entidades solicitadas via first, o campo hasNextPage será avaliado para truee o endCursor retornará uma cadeia de caracteres que pode ser usada com o parâmetro after para acessar os próximos itens. Por exemplo:

query {
  books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

Mutações

Para cada entidade, as mutações para suportar operações de criação, atualização e exclusão são criadas automaticamente. A operação de mutação é criada usando o seguinte padrão de nome: <operation><entity>. Por exemplo, para a entidade book, as mutações seriam:

• createbook: Criar um novo livro
• updatebook: atualizar um livro existente
• deletebook: Excluir o livro especificado

Criar

Para criar um novo elemento da entidade desejada, a mutação create<entity> é fornecida. A mutação criada requer o parâmetro item, onde os valores para os campos obrigatórios da entidade, a serem usados ao criar o novo item, são especificados.

create<entity>(item: <entity_fields>)
{
    <fields>
}

Por exemplo:

mutation {
  createbook(item: {
    id: 2000,
    title: "Leviathan Wakes"    
  }) {
    id
    title
  }  
}

Atualizar

Para atualizar um elemento da entidade desejada, a mutação update<entity> é fornecida. A mutação de atualização requer dois parâmetros:

• <primary_key>, a lista chave-valor de colunas de chave primária e valores relacionados para identificar o elemento a ser atualizado
• item: parâmetro, com valores de campos obrigatórios da entidade, a ser usado ao atualizar o item especificado

update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

Por exemplo:

mutation {
  updatebook(id: 2000, item: {
    year: 2011,
    pages: 577    
  }) {
    id
    title
    year
    pages
  }
}

Suprimir

Para excluir um elemento da entidade desejada, a mutação delete<entity> é fornecida. A chave primária do elemento a ser excluído é o parâmetro necessário.

delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
    <fields>
}

Por exemplo:

mutation {
  deletebook(id: 1234)
  {
    id
    title
  }  
}

Transações de banco de dados para uma mutação

Para processar uma solicitação de mutação típica do GraphQL, o construtor de API de dados constrói duas consultas de banco de dados. Uma das consultas de banco de dados executa a ação de atualização (ou) inserção (ou) exclusão associada à mutação. A outra consulta de banco de dados busca os dados solicitados no conjunto de seleção.

O construtor de API de dados executa ambas as consultas de banco de dados em uma transação. As transações são criadas apenas para tipos de banco de dados SQL.

A tabela a seguir lista os níveis de isolamento com os quais as transações são criadas para cada tipo de banco de dados.

Conteúdo relacionado

• de referência de configuração do GraphQL
• OpenAPI