Hosten von GraphQL-Endpunkten im Daten-API-Generator

Artikel
07/10/2024

Entitäten, die über GraphQL verfügbar sind, sind unter dem Standardpfad verfügbar: https://{base_url}//graphql. Der Daten-API-Generator generiert automatisch ein GraphQL-Schema mit Abfrage- und Mutationsfeldern für alle konfigurierten Entitäten. Das GraphQL-Schema kann mithilfe eines modernen GraphQL-Clients untersucht werden, der Features wie AutoVervollständigen enthält.

Wenn Sie den Erste Schritte Beispiel befolgt haben, in dem die books und die authors Entität für den GraphQL-Zugriff konfiguriert sind, können Sie sehen, wie einfach GraphQL zu verwenden ist.

Resultsetformat

Das zurückgegebene Ergebnis ist ein JSON-Objekt mit diesem Format:

{
    "data": {}    
}

Anmerkung

Standardmäßig werden nur die ersten 100 Elemente zurückgegeben.

Unterstützte Stammtypen

Der Daten-API-Generator unterstützt die folgenden GraphQL-Stammtypen:

Abfragen Mutationen

Fragen

Jede Entität unterstützt die folgenden Aktionen:

Paginierungs-
Abfrage nach Primärschlüssel
generische Abfrage-

Der Daten-API-Generator verwendet, sofern nicht anders angegeben, die Singular Namen einer Entität, wenn die Abfrage erwartet wird, ein einzelnes Element zurückzugeben. Umgekehrt verwendet der Daten-API-Generator den Plural Namen einer Entität, wenn erwartet wird, dass eine Liste von Elementen zurückgegeben wird. Beispielsweise hat die book Entität Folgendes:

book_by_pk(): Gibt null oder eine Entität zurück
books(): Zurückgeben einer Liste mit null oder mehr Entitäten

Paginierung

Alle Abfragetypen, die null oder mehr Elemente zurückgeben, unterstützen die Paginierung:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

das item-Objekt ermöglicht den Zugriff auf Entitätsfelder
hasNextPage auf "true" festgelegt ist, wenn weitere Elemente zurückgegeben werden sollen
endCursor gibt eine undurchsichtige Cursorzeichenfolge zurück, die mit first und after Abfrageparametern verwendet werden kann, um den nächsten Satz (oder die Seite) von Elementen abzurufen.

Abfrage nach Primärschlüssel

Jede Entität unterstützt den Abruf eines bestimmten Elements über den Primärschlüssel mithilfe des folgenden Abfrageformats:

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

Zum Beispiel:

{
  book_by_pk(id:1010) {
    title
  }
}

Generische Abfrage

Jede Entität unterstützt auch ein generisches Abfragemuster, sodass Sie nur die gewünschten Elemente in der gewünschten Reihenfolge mit den folgenden Parametern anfordern können:

filter: Filtert die zurückgegebenen Elemente.
orderBy: definiert, wie die zurückgegebenen Daten sortiert werden
first und after: Gibt nur die obersten n Elemente zurück.

Zum Beispiel:

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

`filter`

Der Wert des filter-Parameters ist ein Prädikatausdruck (ein Ausdruck, der einen booleschen Wert zurückgibt) mithilfe der Felder der Entität. Nur Elemente, bei denen der Ausdruck als "True" ausgewertet wird, sind in der Antwort enthalten. Zum Beispiel:

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

Diese Abfrage gibt alle Bücher mit dem Wort Foundation im Titel zurück.

Die vom parameter filter unterstützten Operatoren sind:

Operator	Art	Beschreibung	Beispiel
`eq`	Vergleich	Gleich	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Vergleich	Ungleich	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Vergleich	Größer als	`books(filter: { year: { gt: 1990 } })`
`gte`	Vergleich	Größer oder gleich	`books(filter: { year: { gte: 1990 } })`
`lt`	Vergleich	Weniger als	`books(filter: { year: { lt: 1990 } })`
`lte`	Vergleich	Kleiner oder gleich	`books(filter: { year: { lte: 1990 } })`
`isNull`	Vergleich	Ist null	`books(filter: { year: { isNull: true} })`
`contains`	Schnur	Enthält	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Schnur	Enthält nicht	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Schnur	Beginnt mit	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Schnur	End with	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Logisch	Logisch und	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Logisch	Logisch oder	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

Der Wert der orderby die Reihenfolge festlegen, mit der die Elemente im Resultset zurückgegeben werden. Zum Beispiel:

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

Diese Abfrage gibt Bücher zurück, die nach titlesortiert sind.

`first` und `after`

Der Parameter first beschränkt die Anzahl der zurückgegebenen Elemente. Zum Beispiel:

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

Diese Abfrage gibt die ersten fünf Bücher zurück. Wenn keine orderBy angegeben wird, werden Elemente basierend auf dem zugrunde liegenden Primärschlüssel sortiert. Der für orderBy bereitgestellte Wert muss eine positive ganze Zahl sein.

Wenn in der book Entität mehr Elemente vorhanden sind als die über firstangeforderten Entitäten, wird das feld hasNextPage zu trueausgewertet, und die endCursor gibt eine Zeichenfolge zurück, die mit dem parameter after verwendet werden kann, um auf die nächsten Elemente zuzugreifen. Zum Beispiel:

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

Mutationen

Für jede Entität werden Mutationen zur Unterstützung von Erstellungs-, Aktualisierungs- und Löschvorgängen automatisch erstellt. Der Mutationsvorgang wird mit dem folgenden Namensmuster erstellt: <operation><entity>. Für die book Entität wären die Mutationen beispielsweise:

createbook: Erstellen eines neuen Buchs
updatebook: Aktualisieren eines vorhandenen Buchs
deletebook: Löschen des angegebenen Buchs

Schaffen

Um ein neues Element der gewünschten Entität zu erstellen, wird die create<entity> Mutation bereitgestellt. Die erstellte Mutation erfordert den item-Parameter, bei dem Werte für obligatorische Felder der Entität beim Erstellen des neuen Elements verwendet werden sollen.

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

Zum Beispiel:

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

Aktualisieren

Um ein Element der gewünschten Entität zu aktualisieren, wird die update<entity> Mutation bereitgestellt. Die Updatemutation erfordert zwei Parameter:

<primary_key>, die Schlüsselwertliste der Primärschlüsselspalten und verwandter Werte, um das zu aktualisierende Element zu identifizieren
item: Parameter mit den Pflichtfeldern der Entität, die beim Aktualisieren des angegebenen Elements verwendet werden sollen

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

Zum Beispiel:

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

Löschen

Um ein Element der gewünschten Entität zu löschen, wird die delete<entity> Mutation bereitgestellt. Der Primärschlüssel des zu löschenden Elements ist der erforderliche Parameter.

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

Zum Beispiel:

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

Datenbanktransaktionen für eine Mutation

Um eine typische GraphQL-Mutationsanforderung zu verarbeiten, erstellt der Daten-API-Generator zwei Datenbankabfragen. Eine der Datenbankabfragen führt die Aktualisierungsaktion (oder) das Einfügen (oder) Löschen durch, die der Mutation zugeordnet ist. Die andere Datenbankabfrage ruft die im Auswahlsatz angeforderten Daten ab.

Der Daten-API-Generator führt beide Datenbankabfragen in einer Transaktion aus. Transaktionen werden nur für SQL-Datenbanktypen erstellt.

In der folgenden Tabelle sind die Isolationsebenen aufgeführt, mit denen die Transaktionen für jeden Datenbanktyp erstellt werden.

Datenbanktyp	Isolationsstufe	Weitere Informationen
Azure SQL (oder) SQL Server	Zugesichert lesen	Azure SQL-
MySQL	Wiederholbares Lesen	MySQL
PostgreSQL	Zugesichert lesen	PostgreSQL

Freigeben über

Hosten von GraphQL-Endpunkten im Daten-API-Generator

Resultsetformat

Unterstützte Stammtypen

Fragen

Abfrage nach Primärschlüssel

Generische Abfrage

`filter`

`orderBy`

`first` und `after`

Mutationen

Schaffen

Aktualisieren

Löschen

Datenbanktransaktionen für eine Mutation

Feedback

Zusätzliche Ressourcen

Freigeben über

Hosten von GraphQL-Endpunkten im Daten-API-Generator

Resultsetformat

Unterstützte Stammtypen

Fragen

Paginierung

Abfrage nach Primärschlüssel

Generische Abfrage

filter

orderBy

first und after

Mutationen

Schaffen

Aktualisieren

Löschen

Datenbanktransaktionen für eine Mutation

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen

`filter`

`orderBy`

`first` und `after`