Hospedar pontos de extremidade do GraphQL no construtor de API de Dados

Artigo
07/10/2024

As entidades configuradas para estarem disponíveis por meio do 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 exemplo de introdução, em que há o books e a entidade authors configurada para acesso ao GraphQL, você poderá ver como é fácil usar o GraphQL.

Formato do conjunto de resultados

O resultado retornado é um objeto JSON com este formato:

{
    "data": {}    
}

Nota

Somente os primeiros 100 itens são retornados por padrão.

Tipos raiz com suporte

O construtor de API de Dados dá suporte aos seguintes tipos raiz do GraphQL:

de Mutaçõesde Consultas

Consultas

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

paginação
consulta por chave primária
de Consulta Genérica

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

book_by_pk(): para retornar 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 dão suporte à paginação:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

o objeto item permite acesso a campos de entidade
hasNextPage será definido como true se houver mais itens a serem retornados
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 dá suporte à 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 dá suporte a um padrão de consulta genérico para que você possa solicitar apenas os itens desejados, na ordem desejada, usando os seguintes parâmetros:

filter: filtra os itens retornados
orderBy: define como os dados retornados são classificados
first e after: retorna apenas os principais itens de 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 é a expressão de predicado (uma expressão que retorna um valor booliano) usando os campos da entidade. Somente os itens em que a expressão é avaliada como 'True' são incluídos na resposta. Por exemplo:

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

Essa consulta retorna todos os livros com a palavra Foundation no título.

Os operadores compatíveis com o parâmetro filter são:

Operador	Tipo	Descrição	Exemplo
`eq`	Comparação	Igual	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Comparação	Não é igual a	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Comparação	Maior que	`books(filter: { year: { gt: 1990 } })`
`gte`	Comparação	Maior ou igual a	`books(filter: { year: { gte: 1990 } })`
`lt`	Comparação	Menor que	`books(filter: { year: { lt: 1990 } })`
`lte`	Comparação	Menor ou igual a	`books(filter: { year: { lte: 1990 } })`
`isNull`	Comparação	É nulo	`books(filter: { year: { isNull: true} })`
`contains`	Corda	Contém	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Corda	Não contém	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Corda	Começa com	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Corda	Terminar com	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Lógico	Lógico e	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Lógico	Lógico ou	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`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 retorna 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
  }
}

Essa consulta retorna os cinco primeiros livros. Quando nenhum orderBy é especificado, os itens são ordenados com base na chave primária subjacente. O valor fornecido para orderBy deve ser um inteiro positivo.

Se houver mais itens na entidade book do que as entidades solicitadas por meio de first, o campo hasNextPage será avaliado como 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, mutações para dar suporte a 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, em que 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
  }  
}

Atualização

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

Excluir

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 exclusão de atualização (ou) que está 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 somente 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.

Tipo de banco de dados	Nível de isolamento	Mais informações
SQL do Azure (ou) SQL Server	Leitura confirmada	do SQL do Azure
MySQL	Leitura repetível	MySQL
PostgreSQL	Leitura confirmada	postgreSQL

referência de configuração do GraphQL
OpenAPI

Compartilhar via

Hospedar pontos de extremidade do GraphQL no construtor de API de Dados

Formato do conjunto de resultados

Tipos raiz com suporte

Consultas

Consulta por chave primária

Consulta genérica

`filter`

`orderBy`

`first` e `after`

Mutações

Criar

Atualização

Excluir

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

Comentários

Recursos adicionais

Compartilhar via

Hospedar pontos de extremidade do GraphQL no construtor de API de Dados

Formato do conjunto de resultados

Tipos raiz com suporte

Consultas

Paginação

Consulta por chave primária

Consulta genérica

filter

orderBy

first e after

Mutações

Criar

Atualização

Excluir

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

Conteúdo relacionado

Comentários

Recursos adicionais

`filter`

`orderBy`

`first` e `after`