Héberger des points de terminaison GraphQL dans le générateur d’API de données

Article
07/10/2024

Les entités configurées pour être disponibles via GraphQL sont disponibles sur le chemin d’accès par défaut : https://{base_url}//graphql. Le générateur d’API de données génère automatiquement un schéma GraphQL avec des champs de requête et de mutation pour toutes les entités configurées. Le schéma GraphQL peut être exploré à l’aide d’un client GraphQL moderne qui inclut des fonctionnalités telles que la saisie semi-automatique.

Si vous avez suivi l’exemple prise en main, où il existe les books et l’entité authors configurée pour l’accès GraphQL, vous pouvez voir comment utiliser GraphQL facilement.

Format du jeu de résultats

Le résultat retourné est un objet JSON au format suivant :

{
    "data": {}    
}

Note

Seuls les 100 premiers éléments sont retournés par défaut.

Types racine pris en charge

Le générateur d’API de données prend en charge les types racine GraphQL suivants :

requêtes mutations

Requêtes

Chaque entité prend en charge les actions suivantes :

de pagination
requête par clé primaire
de requête générique

Le générateur d’API de données, sauf indication contraire, utilise la singular nom d’une entité chaque fois que la requête est censée retourner un seul élément. À l’inverse, le générateur d’API de données utilise le plural nom d’une entité chaque fois que la requête est censée retourner une liste d’éléments. Par exemple, l’entité book a :

book_by_pk(): pour retourner zéro ou une entité
books(): pour renvoyer une liste de zéro ou plusieurs entités

Pagination

Tous les types de requêtes retournant zéro ou plusieurs éléments prennent en charge la pagination :

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

l’objet item autorise l’accès aux champs d’entité
hasNextPage a la valeur true s’il y a plus d’éléments à renvoyer
endCursor retourne une chaîne de curseur opaque qui peut être utilisée avec first et after paramètres de requête pour obtenir le jeu (ou la page) suivant des éléments.

Interroger par clé primaire

Chaque entité prend en charge la récupération d’un élément spécifique via sa clé primaire, à l’aide du format de requête suivant :

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

Par exemple:

{
  book_by_pk(id:1010) {
    title
  }
}

Requête générique

Chaque entité prend également en charge un modèle de requête générique afin que vous puissiez demander uniquement les éléments souhaités, dans l’ordre souhaité, à l’aide des paramètres suivants :

filter: filtre les éléments retournés
orderBy: définit la façon dont les données retournées sont triées
first et after: retourne uniquement les éléments n principaux

Par exemple:

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

`filter`

La valeur du paramètre filter est l’expression de prédicat (expression qui retourne une valeur booléenne) à l’aide des champs de l’entité. Seuls les éléments où l’expression prend la valeur « True » sont inclus dans la réponse. Par exemple:

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

Cette requête retourne tous les livres avec le mot Foundation dans le titre.

Les opérateurs pris en charge par le paramètre filter sont les suivants :

Opérateur	Type	Description	Exemple
`eq`	Comparaison	Égal	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Comparaison	Non égal	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Comparaison	Plus grand que	`books(filter: { year: { gt: 1990 } })`
`gte`	Comparaison	Supérieur ou égal à	`books(filter: { year: { gte: 1990 } })`
`lt`	Comparaison	Moins de	`books(filter: { year: { lt: 1990 } })`
`lte`	Comparaison	Inférieur ou égal à	`books(filter: { year: { lte: 1990 } })`
`isNull`	Comparaison	Est null	`books(filter: { year: { isNull: true} })`
`contains`	Corde	Contient	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Corde	Ne contient pas	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Corde	Commence par	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Corde	Fin avec	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Logique	Logique et	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Logique	Logique ou	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

Valeur du orderby définir l’ordre avec lequel les éléments du jeu de résultats sont retournés. Par exemple:

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

Cette requête retourne des livres triés par title.

`first` et `after`

Le paramètre first limite le nombre d’éléments retournés. Par exemple:

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

Cette requête retourne les cinq premiers livres. Lorsqu’aucun orderBy n’est spécifié, les éléments sont classés en fonction de la clé primaire sous-jacente. La valeur fournie à orderBy doit être un entier positif.

S’il existe plus d’éléments dans l’entité book que ces entités demandées via first, le champ hasNextPage est évalué à trueet le endCursor retourne une chaîne qui peut être utilisée avec le paramètre after pour accéder aux éléments suivants. Par exemple:

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

Mutations

Pour chaque entité, les mutations permettant de prendre en charge les opérations de création, de mise à jour et de suppression sont créées automatiquement. L’opération de mutation est créée à l’aide du modèle de nom suivant : <operation><entity>. Par exemple, pour l’entité book, les mutations sont les suivantes :

createbook: créer un livre
updatebook: mettre à jour un livre existant
deletebook: supprimer le livre spécifié

Créer

Pour créer un élément de l’entité souhaitée, la mutation create<entity> est fournie. La mutation créée nécessite le paramètre item, où les valeurs des champs obligatoires de l’entité doivent être utilisées lors de la création de l’élément, sont spécifiées.

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

Par exemple:

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

Mettre à jour

Pour mettre à jour un élément de l’entité souhaitée, la mutation update<entity> est fournie. La mutation de mise à jour nécessite deux paramètres :

<primary_key>, la liste clé-valeur des colonnes clés primaires et les valeurs associées pour identifier l’élément à mettre à jour
item: paramètre, avec les valeurs de champs obligatoires de l’entité, à utiliser lors de la mise à jour de l’élément spécifié

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

Par exemple:

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

Supprimer

Pour supprimer un élément de l’entité souhaitée, la mutation delete<entity> est fournie. La clé primaire de l’élément à supprimer est le paramètre requis.

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

Par exemple:

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

Transactions de base de données pour une mutation

Pour traiter une demande de mutation GraphQL classique, le générateur d’API de données construit deux requêtes de base de données. L’une des requêtes de base de données effectue l’action d’insertion (ou) d’insertion (ou) de suppression associée à la mutation. L’autre requête de base de données récupère les données demandées dans le jeu de sélection.

Le générateur d’API de données exécute les deux requêtes de base de données dans une transaction. Les transactions sont créées uniquement pour les types de base de données SQL.

Le tableau suivant répertorie les niveaux d’isolation avec lesquels les transactions sont créées pour chaque type de base de données.

Type de base de données	Niveau d’isolation	Plus d’informations
Azure SQL (ou) SQL Server	Lecture validée	azure SQL
MySQL	Lecture reproductible	MySQL
PostgreSQL	Lecture validée	PostgreSQL

référence de configuration GraphQL
OpenAPI

Partager via

Héberger des points de terminaison GraphQL dans le générateur d’API de données

Format du jeu de résultats

Types racine pris en charge

Requêtes

Interroger par clé primaire

Requête générique

`filter`

`orderBy`

`first` et `after`

Mutations

Créer

Mettre à jour

Supprimer

Transactions de base de données pour une mutation

Commentaires

Ressources supplémentaires

Partager via

Héberger des points de terminaison GraphQL dans le générateur d’API de données

Format du jeu de résultats

Types racine pris en charge

Requêtes

Pagination

Interroger par clé primaire

Requête générique

filter

orderBy

first et after

Mutations

Créer

Mettre à jour

Supprimer

Transactions de base de données pour une mutation

Contenu connexe

Commentaires

Ressources supplémentaires

`filter`

`orderBy`

`first` et `after`