Host GraphQL endpoints in Data API Builder (Host GraphQL endpoints in Data API Builder)

Articolo
07/10/2024

Le entità configurate per essere disponibili tramite GraphQL sono disponibili nel percorso predefinito: https://{base_url}//graphql. Il generatore di API dati genera automaticamente uno schema GraphQL con campi di query e mutazione per tutte le entità configurate. Lo schema GraphQL può essere esaminato usando un client GraphQL moderno che include funzionalità come il completamento automatico.

Se è stato seguito il esempio introduttivo, in cui sono presenti le books e l'entità authors configurata per l'accesso a GraphQL, è possibile vedere quanto sia facile usare GraphQL.

Formato set di risultati

Il risultato restituito è un oggetto JSON con questo formato:

{
    "data": {}    
}

Nota

Per impostazione predefinita, vengono restituiti solo i primi 100 elementi.

Tipi radice supportati

Il generatore di API dati supporta i tipi radice GraphQL seguenti:

query mutazioni

Query

Ogni entità dispone del supporto per le azioni seguenti:

paginazione
query per chiave primaria
query generica

Il generatore di API dati, se non diversamente specificato, usa il nome singolare di un'entità ogni volta che si prevede che la query restituisca un singolo elemento. Viceversa, il generatore di API dati usa il plurale nome di un'entità ogni volta che la query deve restituire un elenco di elementi. Ad esempio, l'entità book ha:

book_by_pk(): per restituire zero o un'entità
books(): per restituire un elenco di zero o più entità

Impaginazione

Tutti i tipi di query che restituiscono zero o più elementi supportano l'impaginazione:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

l'oggetto item consente l'accesso ai campi dell'entità
hasNextPage è impostato su true se sono presenti più elementi da restituire
endCursor restituisce una stringa di cursore opaca che può essere usata con first e after parametri di query per ottenere il set successivo (o la pagina) degli elementi.

Query per chiave primaria

Ogni entità supporta il recupero di un elemento specifico tramite la relativa chiave primaria, usando il formato di query seguente:

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

Per esempio:

{
  book_by_pk(id:1010) {
    title
  }
}

Query generica

Ogni entità supporta anche un modello di query generico in modo che sia possibile richiedere solo gli elementi desiderati, nell'ordine desiderato, usando i parametri seguenti:

filter: filtra gli elementi restituiti
orderBy: definisce la modalità di ordinamento dei dati restituiti
first e after: restituisce solo gli elementi n principali

Per esempio:

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

`filter`

Il valore del parametro filter è l'espressione predicato (un'espressione che restituisce un valore booleano) usando i campi dell'entità. Nella risposta vengono inclusi solo gli elementi in cui l'espressione restituisce "True". Per esempio:

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

Questa query restituisce tutti i libri con la parola Foundation nel titolo.

Gli operatori supportati dal parametro filter sono:

Operatore	Digitare	Descrizione	Esempio
`eq`	Paragone	Uguale	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Paragone	Diverso da	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Paragone	Maggiore	`books(filter: { year: { gt: 1990 } })`
`gte`	Paragone	Maggiore o uguale a	`books(filter: { year: { gte: 1990 } })`
`lt`	Paragone	Meno di	`books(filter: { year: { lt: 1990 } })`
`lte`	Paragone	Minore o uguale a	`books(filter: { year: { lte: 1990 } })`
`isNull`	Paragone	Valore Null	`books(filter: { year: { isNull: true} })`
`contains`	Corda	Contiene	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Corda	Non contiene	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Corda	Inizia con	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Corda	Termina con	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Logico	Logico e	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Logico	Logico o	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

Valore del orderby impostare l'ordine con cui vengono restituiti gli elementi nel set di risultati. Per esempio:

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

Questa query restituisce i libri ordinati in base title.

`first` e `after`

Il parametro first limita il numero di elementi restituiti. Per esempio:

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

Questa query restituisce i primi cinque libri. Quando non viene specificato alcun orderBy, gli elementi vengono ordinati in base alla chiave primaria sottostante. Il valore specificato per orderBy deve essere un numero intero positivo.

Se sono presenti più elementi nell'entità book rispetto a quelle richieste tramite first, il campo hasNextPage restituirà truee il endCursor restituirà una stringa che può essere usata con il parametro after per accedere agli elementi successivi. Per esempio:

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

Mutazioni

Per ogni entità, le mutazioni per supportare le operazioni di creazione, aggiornamento ed eliminazione vengono create automaticamente. L'operazione di mutazione viene creata usando il modello di nome seguente: <operation><entity>. Ad esempio, per l'entità book, le mutazioni saranno:

createbook: creare un nuovo libro
updatebook: aggiornare un libro esistente
deletebook: eliminare il libro specificato

Creare

Per creare un nuovo elemento dell'entità desiderata, viene fornita la mutazione create<entity>. La mutazione creata richiede che venga specificato il parametro item, in cui vengono specificati i valori per i campi obbligatori dell'entità.

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

Per esempio:

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

Aggiornare

Per aggiornare un elemento dell'entità desiderata, viene fornita la mutazione update<entity>. La mutazione dell'aggiornamento richiede due parametri:

<primary_key>, l'elenco chiave-valore delle colonne chiave primaria e i valori correlati per identificare l'elemento da aggiornare
item: parametro, con i valori dei campi obbligatori dell'entità, da usare durante l'aggiornamento dell'elemento specificato

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

Per esempio:

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

Cancellare

Per eliminare un elemento dell'entità desiderata, viene fornita la mutazione delete<entity>. La chiave primaria dell'elemento da eliminare è il parametro obbligatorio.

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

Per esempio:

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

Transazioni di database per una mutazione

Per elaborare una tipica richiesta di mutazione graphQL, il generatore di API dati costruisce due query di database. Una delle query di database esegue l'azione di aggiornamento (o) di inserimento (o) di eliminazione associata alla mutazione. L'altra query del database recupera i dati richiesti nel set di selezione.

Il generatore di API dati esegue entrambe le query di database in una transazione. Le transazioni vengono create solo per i tipi di database SQL.

Nella tabella seguente sono elencati i livelli di isolamento con cui vengono create le transazioni per ogni tipo di database.

Tipo di database	Livello di isolamento	Altre informazioni
SQL di Azure (o) SQL Server	Read Committed	SQL di Azure
MySQL	Lettura ripetibile	mySQL
PostgreSQL	Read Committed	PostgreSQL

riferimento alla configurazione graphQL
OpenAPI

Condividi tramite

Host GraphQL endpoints in Data API Builder (Host GraphQL endpoints in Data API Builder)

Formato set di risultati

Tipi radice supportati

Query

Query per chiave primaria

Query generica

`filter`

`orderBy`

`first` e `after`

Mutazioni

Creare

Aggiornare

Cancellare

Transazioni di database per una mutazione

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Host GraphQL endpoints in Data API Builder (Host GraphQL endpoints in Data API Builder)

Formato set di risultati

Tipi radice supportati

Query

Impaginazione

Query per chiave primaria

Query generica

filter

orderBy

first e after

Mutazioni

Creare

Aggiornare

Cancellare

Transazioni di database per una mutazione

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive

`filter`

`orderBy`

`first` e `after`