Värd för GraphQL-slutpunkter i Data API Builder

Entiteter som har konfigurerats för att vara tillgängliga via GraphQL är tillgängliga på standardsökvägen: https://{base_url}//graphql. Data API Builder genererar automatiskt ett GraphQL-schema med fråge- och mutationsfält för alla konfigurerade entiteter. GraphQL-schemat kan utforskas med hjälp av en modern GraphQL-klient som innehåller funktioner som automatisk komplettering.

Om du har följt komma igång exempel, där det finns books och den authors entitet som konfigurerats för GraphQL-åtkomst, kan du se hur enkelt det är att använda GraphQL.

Format för resultatuppsättning

Det returnerade resultatet är ett JSON-objekt med det här formatet:

{
    "data": {}    
}

Not

Endast de första 100 objekten returneras som standard.

Rottyper som stöds

Data API Builder stöder följande GraphQL-rottyper:

frågormutationer

Frågor

Varje entitet har stöd för följande åtgärder:

• sidnumrering
• Fråga efter primärnyckel
• allmän fråga

Data-API-byggare använder, om inget annat anges, singular namn på en entitet när frågan förväntas returnera ett enda objekt. Omvänt använder data-API-byggaren plural- namn på en entitet när frågan förväntas returnera en lista med objekt. Till exempel har den book entiteten:

• book_by_pk(): för att returnera noll eller en entitet
• books(): för att returnera en lista med noll eller flera entiteter

Paginering

Alla frågetyper som returnerar noll eller flera objekt stöder sidnumrering:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

• objektet item ger åtkomst till entitetsfält
• hasNextPage är inställt på sant om det finns fler objekt som ska returneras
• endCursor returnerar en ogenomskinlig markörsträng som kan användas med first och after frågeparametrar för att hämta nästa uppsättning (eller sida) av objekt.

Fråga efter primärnyckel

Varje entitet stöder hämtning av ett specifikt objekt via dess primärnyckel med följande frågeformat:

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

Till exempel:

{
  book_by_pk(id:1010) {
    title
  }
}

Allmän fråga

Varje entitet har också stöd för ett allmänt frågemönster så att du bara kan be om de objekt som du vill ha, i den ordning du vill, med hjälp av följande parametrar:

• filter: filtrerar de returnerade objekten
• orderBy: definierar hur returnerade data sorteras
• first och after: returnerar endast de översta n objekten

Till exempel:

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

filter

Värdet för parametern filter är predikatuttryck (ett uttryck som returnerar ett booleskt värde) med hjälp av entitetens fält. Endast objekt där uttrycket utvärderas till "True" ingår i svaret. Till exempel:

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

Den här frågan returnerar alla böcker med ordet Foundation i rubriken.

Operatorerna som stöds av parametern filter är:

Operatör	Typ	Beskrivning	Exempel
eq	Jämförelse	Lika	books(filter: { title: { eq: "Foundation" } })
neq	Jämförelse	Inte lika med	books(filter: { title: { neq: "Foundation" } })
gt	Jämförelse	Större än	books(filter: { year: { gt: 1990 } })
gte	Jämförelse	Större än eller lika med	books(filter: { year: { gte: 1990 } })
lt	Jämförelse	Mindre än	books(filter: { year: { lt: 1990 } })
lte	Jämförelse	Mindre än eller lika med	books(filter: { year: { lte: 1990 } })
isNull	Jämförelse	Är null	books(filter: { year: { isNull: true} })
contains	Sträng	Innehåller	books(filter: { title: { contains: "Foundation" } })
notContains	Sträng	Innehåller inte	books(filter: { title: { notContains: "Foundation" } })
startsWith	Sträng	Börjar med	books(filter: { title: { startsWith: "Foundation" } })
endsWith	Sträng	Avsluta med	books(filter: { title: { endsWith: "Empire" } })
and	Logisk	Logiskt och	authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })
or	Logisk	Logiskt eller	authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })

orderBy

Värdet för orderby ange i vilken ordning objekten i resultatuppsättningen returneras. Till exempel:

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

Den här frågan returnerar böcker ordnade efter title.

first och after

Parametern first begränsar antalet returnerade objekt. Till exempel:

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

Den här frågan returnerar de fem första böckerna. När inga orderBy anges sorteras objekten baserat på den underliggande primärnyckeln. Värdet som anges för orderBy måste vara ett positivt heltal.

Om det finns fler objekt i den book entiteten än de entiteter som begärs via firstutvärderas fältet hasNextPage till trueoch endCursor returnerar en sträng som kan användas med parametern after för att komma åt nästa objekt. Till exempel:

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

Mutationer

För varje entitet skapas mutationer som stöder åtgärder för att skapa, uppdatera och ta bort automatiskt. Mutationsåtgärden skapas med hjälp av följande namnmönster: <operation><entity>. För den book entiteten skulle mutationerna till exempel vara:

• createbook: skapa en ny bok
• updatebook: uppdatera en befintlig bok
• deletebook: ta bort den angivna boken

Skapa

För att skapa ett nytt element i den önskade entiteten tillhandahålls den create<entity> mutationen. Den skapade mutationen kräver att parametern item, där värden för entitetens obligatoriska fält, ska användas när det nya objektet skapas.

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

Till exempel:

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

Uppdatera

För att uppdatera ett element i den önskade entiteten tillhandahålls den update<entity> mutationen. Uppdateringsmutationen kräver två parametrar:

• <primary_key>, nyckel/värde-listan med primärnyckelkolumner och relaterade värden för att identifiera elementet som ska uppdateras
• item: parameter, med entitetens obligatoriska fältvärden, som ska användas vid uppdatering av det angivna objektet

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

Till exempel:

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

Ta bort

Om du vill ta bort ett element i den önskade entiteten tillhandahålls den delete<entity> mutationen. Den primära nyckeln för det element som ska tas bort är den obligatoriska parametern.

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

Till exempel:

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

Databastransaktioner för en mutation

För att bearbeta en typisk GraphQL-mutationsbegäran skapar Data API Builder två databasfrågor. En av databasfrågorna utför åtgärden för att infoga (eller) ta bort uppdateringen (eller) som är associerad med mutationen. Den andra databasfrågan hämtar de data som begärdes i urvalsuppsättningen.

Data API Builder kör båda databasfrågorna i en transaktion. Transaktioner skapas endast för SQL-databastyper.

I följande tabell visas de isoleringsnivåer som transaktionerna skapas med för varje databastyp.

Databastyp	Isoleringsnivå	Mer information
Azure SQL (eller) SQL Server	Läs bekräftad	Azure SQL
MySQL	Repeterbar läsning	MySQL
PostgreSQL	Läs bekräftad	PostgreSQL

Relaterat innehåll

• GraphQL-konfigurationsreferens
• OpenAPI-