GraphQL-eindpunten hosten in Data API Builder

Artikel
07/10/2024

Entiteiten die zijn geconfigureerd om beschikbaar te zijn via GraphQL, zijn beschikbaar op het standaardpad: https://{base_url}//graphql. Data API Builder genereert automatisch een GraphQL-schema met query- en mutatievelden voor alle geconfigureerde entiteiten. Het GraphQL-schema kan worden verkend met behulp van een moderne GraphQL-client met functies zoals automatisch aanvullen.

Als u de Aan de slag hebt gevolgd voorbeeld, waarin de books en de authors-entiteit zijn geconfigureerd voor GraphQL-toegang, kunt u zien hoe eenvoudig GraphQL kan worden gebruikt.

Indeling van resultatenset

Het geretourneerde resultaat is een JSON-object met deze indeling:

{
    "data": {}    
}

Notitie

Alleen de eerste 100 items worden standaard geretourneerd.

Ondersteunde hoofdtypen

Data API Builder ondersteunt de volgende GraphQL-hoofdtypen:

query's mutaties

Query 's

Elke entiteit heeft ondersteuning voor de volgende acties:

paginering
query uitvoeren op primaire sleutel
algemene query

Data API Builder gebruikt, tenzij anders opgegeven, de enkelvoudige naam van een entiteit wanneer de query naar verwachting één item retourneert. Omgekeerd gebruikt de data-API-opbouwfunctie de meervoud naam van een entiteit wanneer de query naar verwachting een lijst met items retourneert. De entiteit book heeft bijvoorbeeld:

book_by_pk(): om nul of één entiteit te retourneren
books(): een lijst met nul of meer entiteiten retourneren

Paginering

Alle querytypen die nul of meer items retourneren, ondersteunen paginering:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

het item-object toegang biedt tot entiteitsvelden
hasNextPage is ingesteld op waar als er meer items moeten worden geretourneerd
endCursor retourneert een ondoorzichtige cursortekenreeks die kan worden gebruikt met first en after queryparameters om de volgende set (of pagina) met items op te halen.

Query uitvoeren op primaire sleutel

Elke entiteit biedt ondersteuning voor het ophalen van een specifiek item via de primaire sleutel, met behulp van de volgende queryindeling:

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

Bijvoorbeeld:

{
  book_by_pk(id:1010) {
    title
  }
}

Algemene query

Elke entiteit ondersteunt ook een algemeen querypatroon, zodat u alleen naar de gewenste items kunt vragen, in de gewenste volgorde, met behulp van de volgende parameters:

filter: filtert de geretourneerde items
orderBy: definieert hoe de geretourneerde gegevens worden gesorteerd
first en after: retourneert alleen de bovenste n items

Bijvoorbeeld:

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

`filter`

De waarde van de parameter filter is predicaatexpressie (een expressie die een Booleaanse waarde retourneert) met behulp van de velden van de entiteit. Alleen items waarin de expressie 'Waar' oplevert, worden opgenomen in het antwoord. Bijvoorbeeld:

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

Deze query retourneert alle boeken met het woord Foundation in de titel.

De operators die worden ondersteund door de parameter filter zijn:

Bediener	Type	Beschrijving	Voorbeeld
`eq`	Vergelijking	Gelijk	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Vergelijking	Niet gelijk aan	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Vergelijking	Groter dan	`books(filter: { year: { gt: 1990 } })`
`gte`	Vergelijking	Groter dan of gelijk aan	`books(filter: { year: { gte: 1990 } })`
`lt`	Vergelijking	Kleiner dan	`books(filter: { year: { lt: 1990 } })`
`lte`	Vergelijking	Kleiner dan of gelijk aan	`books(filter: { year: { lte: 1990 } })`
`isNull`	Vergelijking	Is null	`books(filter: { year: { isNull: true} })`
`contains`	Snaar	Bevat	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Snaar	Bevat geen	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Snaar	Begint met	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Snaar	Eindigen met	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Logisch	Logisch en	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Logisch	Logisch of	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

De waarde van de orderby de volgorde instellen waarmee de items in de resultatenset worden geretourneerd. Bijvoorbeeld:

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

Met deze query worden boeken geretourneerd die zijn gesorteerd op title.

`first` en `after`

De parameter first beperkt het aantal geretourneerde items. Bijvoorbeeld:

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

Deze query retourneert de eerste vijf boeken. Wanneer er geen orderBy is opgegeven, worden items geordend op basis van de onderliggende primaire sleutel. De waarde die is opgegeven aan orderBy moet een positief geheel getal zijn.

Als er meer items in de book entiteit staan dan die entiteiten die zijn aangevraagd via first, resulteert het hasNextPage veld in trueen retourneert de endCursor een tekenreeks die kan worden gebruikt met de parameter after voor toegang tot de volgende items. Bijvoorbeeld:

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

Mutaties

Voor elke entiteit worden er automatisch mutaties gemaakt ter ondersteuning van het maken, bijwerken en verwijderen van bewerkingen. De mutatiebewerking wordt gemaakt met behulp van het volgende naampatroon: <operation><entity>. Voor de book entiteit zijn de mutaties bijvoorbeeld:

createbook: een nieuw boek maken
updatebook: een bestaand boek bijwerken
deletebook: het opgegeven boek verwijderen

Scheppen

Om een nieuw element van de gewenste entiteit te creëren, wordt de create<entity> mutatie verstrekt. De gemaakte mutatie vereist dat de parameter item, waarbij waarden voor verplichte velden van de entiteit moeten worden gebruikt bij het maken van het nieuwe item, worden opgegeven.

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

Bijvoorbeeld:

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

Update

Om een element van de gewenste entiteit bij te werken, wordt de update<entity> mutatie verstrekt. De updatemutatie vereist twee parameters:

<primary_key>, de sleutel-waardelijst met primaire-sleutelkolommen en gerelateerde waarden om het element te identificeren dat moet worden bijgewerkt
item: parameter, met de verplichte veldwaarden van de entiteit, die moet worden gebruikt bij het bijwerken van het opgegeven item

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

Bijvoorbeeld:

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

Verwijderen

Om een element van de gewenste entiteit te verwijderen, wordt de delete<entity> mutatie verstrekt. De primaire sleutel van het te verwijderen element is de vereiste parameter.

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

Bijvoorbeeld:

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

Databasetransacties voor een mutatie

Om een typische GraphQL-mutatieaanvraag te verwerken, bouwt Data API Builder twee databasequery's. Een van de databasequery's voert de update (of) insert (of) verwijderactie uit die is gekoppeld aan de mutatie. Met de andere databasequery worden de gegevens opgehaald die zijn aangevraagd in de selectieset.

Data API Builder voert beide databasequery's uit in een transactie. Transacties worden alleen gemaakt voor SQL-databasetypen.

De volgende tabel bevat de isolatieniveaus waarmee de transacties worden gemaakt voor elk databasetype.

Databasetype	Isolatieniveau	Meer informatie
Azure SQL (of) SQL Server	Vastgelegd lezen	Azure SQL-
MySQL	Herhaalbare leesbewerking	MySQL-
PostgreSQL	Vastgelegd lezen	PostgreSQL-

Delen via

GraphQL-eindpunten hosten in Data API Builder

Indeling van resultatenset

Ondersteunde hoofdtypen

Query 's

Query uitvoeren op primaire sleutel

Algemene query

`filter`

`orderBy`

`first` en `after`

Mutaties

Scheppen

Update

Verwijderen

Databasetransacties voor een mutatie

Feedback

Aanvullende resources

Delen via

GraphQL-eindpunten hosten in Data API Builder

Indeling van resultatenset

Ondersteunde hoofdtypen

Query 's

Paginering

Query uitvoeren op primaire sleutel

Algemene query

filter

orderBy

first en after

Mutaties

Scheppen

Update

Verwijderen

Databasetransacties voor een mutatie

Verwante inhoud

Feedback

Aanvullende resources

`filter`

`orderBy`

`first` en `after`