Hospedaje de puntos de conexión de GraphQL en data API Builder

Artículo
07/10/2024

Las entidades configuradas para que estén disponibles a través de GraphQL están disponibles en la ruta de acceso predeterminada: https://{base_url}//graphql. Data API Builder genera automáticamente un esquema GraphQL con campos de consulta y mutación para todas las entidades configuradas. El esquema de GraphQL se puede explorar mediante un cliente de GraphQL moderno que incluye características como autocompletar.

Si ha seguido el ejemplo Introducción, donde hay el books y la entidad authors configurada para el acceso a GraphQL, puede ver lo fácil que es usar GraphQL.

Formato del conjunto de resultados

El resultado devuelto es un objeto JSON con este formato:

{
    "data": {}    
}

Nota

De forma predeterminada, solo se devuelven los primeros 100 elementos.

Tipos raíz admitidos

Data API Builder admite los siguientes tipos raíz de GraphQL:

de mutaciones de consultas

Consultas

Cada entidad admite las siguientes acciones:

paginación de
consulta por clave principal
de consulta genérica

El generador de API de datos, a menos que se especifique lo contrario, usa el singular nombre de una entidad siempre que se espera que la consulta devuelva un solo elemento. Por el contrario, data API builder usa el plural nombre de una entidad siempre que se espera que la consulta devuelva una lista de elementos. Por ejemplo, la entidad book tiene:

book_by_pk(): para devolver cero o una entidad
books(): para devolver una lista de cero o más entidades

Paginación

Todos los tipos de consulta que devuelven cero o más elementos admiten la paginación:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

el objeto item permite el acceso a campos de entidad
hasNextPage se establece en true si hay más elementos que se van a devolver.
endCursor devuelve una cadena de cursor opaca que se puede usar con first y after parámetros de consulta para obtener el siguiente conjunto (o página) de elementos.

Consulta por clave principal

Cada entidad admite la recuperación de un elemento específico a través de su clave principal mediante el siguiente formato de consulta:

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

Por ejemplo:

{
  book_by_pk(id:1010) {
    title
  }
}

Consulta genérica

Cada entidad también admite un patrón de consulta genérico para que pueda solicitar solo los elementos que desee, en el orden que desee, con los parámetros siguientes:

filter: filtra los elementos devueltos
orderBy: define cómo se ordenan los datos devueltos
first y after: devuelve solo los elementos de n principales.

Por ejemplo:

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

`filter`

El valor del parámetro filter es la expresión de predicado (una expresión que devuelve un valor booleano) mediante los campos de la entidad. Solo los elementos en los que la expresión se evalúa como "True" se incluyen en la respuesta. Por ejemplo:

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

Esta consulta devuelve todos los libros con la palabra Foundation en el título.

Los operadores admitidos por el parámetro filter son:

Operador	Tipo	Descripción	Ejemplo
`eq`	Comparación	Igual	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Comparación	No es igual	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Comparación	Mayor que	`books(filter: { year: { gt: 1990 } })`
`gte`	Comparación	Mayor o igual que	`books(filter: { year: { gte: 1990 } })`
`lt`	Comparación	Menos que	`books(filter: { year: { lt: 1990 } })`
`lte`	Comparación	Menor o igual que	`books(filter: { year: { lte: 1990 } })`
`isNull`	Comparación	Es null	`books(filter: { year: { isNull: true} })`
`contains`	Cuerda	Contiene	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Cuerda	No contiene	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Cuerda	Comienza con	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Cuerda	Terminar con	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Lógico	Lógico y	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Lógico	Lógico o	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

El valor del orderby establecer el orden con el que se devuelven los elementos del conjunto de resultados. Por ejemplo:

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

Esta consulta devuelve libros ordenados por title.

`first` y `after`

El parámetro first limita el número de elementos devueltos. Por ejemplo:

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

Esta consulta devuelve los cinco primeros libros. Cuando no se especifica ningún orderBy, los elementos se ordenan en función de la clave principal subyacente. El valor proporcionado para orderBy debe ser un entero positivo.

Si hay más elementos en la entidad book que esas entidades solicitadas a través de first, el campo hasNextPage se evaluará como truey el endCursor devolverá una cadena que se puede usar con el parámetro after para acceder a los siguientes elementos. Por ejemplo:

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

Mutaciones

Para cada entidad, las mutaciones para admitir operaciones de creación, actualización y eliminación se crean automáticamente. La operación de mutación se crea con el siguiente patrón de nombre: <operation><entity>. Por ejemplo, para la entidad book, las mutaciones serían:

createbook: crear un nuevo libro
updatebook: actualizar un libro existente
deletebook: eliminar el libro especificado

Crear

Para crear un nuevo elemento de la entidad deseada, se proporciona la create<entity> mutación. La mutación creada requiere el parámetro item, donde se especifican los valores de los campos obligatorios de la entidad al crear el nuevo elemento.

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

Por ejemplo:

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

Actualizar

Para actualizar un elemento de la entidad deseada, se proporciona la mutación update<entity>. La mutación de actualización requiere dos parámetros:

<primary_key>, la lista clave-valor de las columnas de clave principal y los valores relacionados para identificar el elemento que se va a actualizar.
item: parámetro, con los valores obligatorios de campos de la entidad, que se usarán al actualizar el elemento especificado.

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

Por ejemplo:

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

Borrar

Para eliminar un elemento de la entidad deseada, se proporciona la mutación delete<entity>. La clave principal del elemento que se va a eliminar es el parámetro necesario.

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

Por ejemplo:

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

Transacciones de base de datos para una mutación

Para procesar una solicitud de mutación típica de GraphQL, el generador de Data API crea dos consultas de base de datos. Una de las consultas de base de datos realiza la acción de eliminación de inserción (o) de actualización (o) asociada a la mutación. La otra consulta de base de datos captura los datos solicitados en el conjunto de selección.

Data API Builder ejecuta ambas consultas de base de datos en una transacción. Las transacciones solo se crean para los tipos de base de datos SQL.

En la tabla siguiente se enumeran los niveles de aislamiento con los que se crean las transacciones para cada tipo de base de datos.

Tipo de base de datos	Nivel de aislamiento	Más información
Azure SQL (o) SQL Server	Lectura confirmada	azure SQL
MySQL	Lectura repetible	mySQL
PostgreSQL	Lectura confirmada	postgreSQL

Compartir a través de

Hospedaje de puntos de conexión de GraphQL en data API Builder

Formato del conjunto de resultados

Tipos raíz admitidos

Consultas

Consulta por clave principal

Consulta genérica

`filter`

`orderBy`

`first` y `after`

Mutaciones

Crear

Actualizar

Borrar

Transacciones de base de datos para una mutación

Comentarios

Recursos adicionales

Compartir a través de

Hospedaje de puntos de conexión de GraphQL en data API Builder

Formato del conjunto de resultados

Tipos raíz admitidos

Consultas

Paginación

Consulta por clave principal

Consulta genérica

filter

orderBy

first y after

Mutaciones

Crear

Actualizar

Borrar

Transacciones de base de datos para una mutación

Contenido relacionado

Comentarios

Recursos adicionales

`filter`

`orderBy`

`first` y `after`