Strukturierung eines GraphQL-Schemas Erstellen von Schemata Hinzufügen von Typen zu Schemas Optionale Überlegungen — Verwendung von Enumerationen als Status Optionale Überlegungen — Abonnements Optionale Überlegungen — Beziehungen und Seitennummerierung

Entwerfen Sie Ihr GraphQL-Schema

Das GraphQL-Schema ist die Grundlage jeder GraphQL-Serverimplementierung. Jede GraphQL-API wird durch ein einzelnes Schema definiert, das Typen und Felder enthält, die beschreiben, wie die Daten aus Anfragen gefüllt werden. Die Daten, die durch Ihre API fließen, und die ausgeführten Operationen müssen anhand des Schemas validiert werden.

Im Allgemeinen beschreibt das GraphQL-Typsystem die Funktionen eines GraphQL-Servers und wird verwendet, um festzustellen, ob eine Abfrage gültig ist. Das Typsystem eines Servers wird oft als das Schema dieses Servers bezeichnet und kann aus verschiedenen Objekttypen, Skalartypen, Eingabetypen und mehr bestehen. GraphQL ist sowohl deklarativ als auch stark typisiert, was bedeutet, dass die Typen zur Laufzeit klar definiert sind und nur das zurückgeben, was angegeben wurde.

AWS AppSync ermöglicht es Ihnen, GraphQL-Schemas zu definieren und zu konfigurieren. Der folgende Abschnitt beschreibt, wie Sie GraphQL-Schemas mithilfe der Dienste von Grund auf neu erstellen. AWS AppSync

Strukturierung eines GraphQL-Schemas

Tipp

Wir empfehlen, den Abschnitt „Schemas“ zu lesen, bevor Sie fortfahren.

GraphQL ist ein leistungsstarkes Tool zur Implementierung von API-Diensten. Laut der Website von GraphQL ist GraphQL das Folgende:

„GraphQL ist eine Abfragesprache für APIs und eine Laufzeit zum Erfüllen dieser Abfragen mit Ihren vorhandenen Daten. GraphQL bietet eine vollständige und verständliche Beschreibung der Daten in Ihrer API, gibt Kunden die Möglichkeit, genau das zu verlangen, was sie benötigen und nichts weiter, erleichtert die Weiterentwicklung von APIs im Laufe der Zeit und ermöglicht leistungsstarke Entwicklertools. “

Dieser Abschnitt behandelt den allerersten Teil Ihrer GraphQL-Implementierung, das Schema. Um das obige Zitat zu verwenden, spielt ein Schema die Rolle, „eine vollständige und verständliche Beschreibung der Daten in Ihrer API bereitzustellen“. Mit anderen Worten, ein GraphQL-Schema ist eine textuelle Darstellung der Daten, Operationen und der Beziehungen zwischen ihnen. Das Schema wird als Haupteinstiegspunkt für Ihre GraphQL-Serviceimplementierung betrachtet. Es überrascht nicht, dass es oft eines der ersten Dinge ist, die Sie in Ihrem Projekt vornehmen. Wir empfehlen, den Abschnitt Schemas zu lesen, bevor Sie fortfahren.

Um den Abschnitt Schemas zu zitieren: GraphQL-Schemas sind in der Schema Definition Language (SDL) geschrieben. SDL besteht aus Typen und Feldern mit einer etablierten Struktur:

Typen: Mit Typen definiert GraphQL die Form und das Verhalten der Daten. GraphQL unterstützt eine Vielzahl von Typen, die später in diesem Abschnitt erklärt werden. Jeder Typ, der in Ihrem Schema definiert ist, hat seinen eigenen Gültigkeitsbereich. Innerhalb des Bereichs befinden sich ein oder mehrere Felder, die einen Wert oder eine Logik enthalten können, die in Ihrem GraphQL-Dienst verwendet wird. Typen erfüllen viele verschiedene Rollen, wobei Objekte oder Skalare (primitive Werttypen) am häufigsten vorkommen.
Felder: Felder existieren innerhalb des Gültigkeitsbereichs eines Typs und enthalten den Wert, der vom GraphQL-Dienst angefordert wird. Diese sind Variablen in anderen Programmiersprachen sehr ähnlich. Die Form der Daten, die Sie in Ihren Feldern definieren, bestimmt, wie die Daten in einer request/response Operation strukturiert sind. Auf diese Weise können Entwickler vorhersagen, was zurückgegeben wird, ohne zu wissen, wie das Backend des Dienstes implementiert ist.

Die einfachsten Schemas werden drei verschiedene Datenkategorien enthalten:

Schemawurzeln: Wurzeln definieren die Einstiegspunkte Ihres Schemas. Es zeigt auf die Felder, die bestimmte Operationen an den Daten ausführen, z. B. etwas hinzufügen, löschen oder ändern.
Typen: Dies sind Basistypen, die verwendet werden, um die Form der Daten darzustellen. Sie können sich diese fast als Objekte oder abstrakte Repräsentationen von etwas mit definierten Eigenschaften vorstellen. Sie könnten beispielsweise ein Person Objekt erstellen, das eine Person in einer Datenbank darstellt. Die Merkmale jeder Person werden in den Feldern Person als definiert. Sie können alles wie Name, Alter, Beruf, Adresse usw. der Person sein.
Spezielle Objekttypen: Dies sind die Typen, die das Verhalten der Operationen in Ihrem Schema definieren. Jeder spezielle Objekttyp wird einmal pro Schema definiert. Sie werden zuerst im Schemastamm platziert und dann im Schematext definiert. Jedes Feld in einem speziellen Objekttyp definiert eine einzelne Operation, die von Ihrem Resolver implementiert werden soll.

Um dies ins rechte Licht zu rücken, stellen Sie sich vor, Sie erstellen einen Dienst, der Autoren und die von ihnen geschriebenen Bücher speichert. Jeder Autor hat einen Namen und eine Reihe von Büchern, die er verfasst hat. Jedes Buch hat einen Namen und eine Liste der zugehörigen Autoren. Wir möchten auch die Möglichkeit haben, Bücher und Autoren hinzuzufügen oder abzurufen. Eine einfache UML-Darstellung dieser Beziehung könnte wie folgt aussehen:

UML-Diagramm, das die Klassen Author und Book mit bidirektionaler Viele-zu-Viele-Beziehung zeigt.

In GraphQL Book stehen die Entitäten 1 Author und 2 für zwei verschiedene Objekttypen in Ihrem Schema:


type Author {
}

type Book {
}

Authorenthält authorName undBooks, während es bookName und Book Authors enthält. Diese können als Felder innerhalb des Bereichs Ihrer Typen dargestellt werden:


type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

Wie Sie sehen können, sind die Typdarstellungen dem Diagramm sehr ähnlich. Bei den Methoden wird es jedoch etwas schwieriger. Diese werden in einem von wenigen speziellen Objekttypen als Feld platziert. Ihre spezielle Objektkategorisierung hängt von ihrem Verhalten ab. GraphQL enthält drei grundlegende spezielle Objekttypen: Abfragen, Mutationen und Abonnements. Weitere Informationen finden Sie unter Spezielle Objekte.

Da getAuthor beide Daten anfordern, werden sie einem Query speziellen Objekttyp zugeordnet: getBook


type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Die Operationen sind mit der Abfrage verknüpft, die selbst mit dem Schema verknüpft ist. Wenn Sie einen Schemastamm hinzufügen, wird der spezielle Objekttyp (Queryin diesem Fall) als einer Ihrer Einstiegspunkte definiert. Dies kann mit dem schema Schlüsselwort erfolgen:


schema {
  query: Query
}

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Wenn Sie sich die letzten beiden Methoden ansehen addAuthor und addBook Daten zu Ihrer Datenbank hinzufügen, werden sie in einem Mutation speziellen Objekttyp definiert. Auf der Seite „Typen“ wissen wir jedoch auch, dass Eingaben, die direkt auf Objekte verweisen, nicht zulässig sind, da es sich ausschließlich um Ausgabetypen handelt. In diesem Fall können wir Author or nicht verwendenBook, also müssen wir einen Eingabetyp mit denselben Feldern erstellen. In diesem Beispiel haben wir AuthorInput und hinzugefügtBookInput, die beide die gleichen Felder ihres jeweiligen Typs akzeptieren. Dann erstellen wir unsere Mutation mit den Eingaben als Parameter:


schema {
  query: Query
  mutation: Mutation
}

type Author {
  authorName: String
  Books: [Book]
}

input AuthorInput {
  authorName: String
  Books: [BookInput]
}

type Book {
  bookName: String
  Authors: [Author]
}

input BookInput {
  bookName: String
  Authors: [AuthorInput]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

type Mutation {
  addAuthor(input: [BookInput]): Author
  addBook(input: [AuthorInput]): Book
}

Schauen wir uns an, was wir gerade getan haben:

Wir haben ein Schema mit den Author Typen Book und erstellt, um unsere Entitäten darzustellen.
Wir haben die Felder hinzugefügt, die die Merkmale unserer Entitäten enthalten.
Wir haben eine Abfrage hinzugefügt, um diese Informationen aus der Datenbank abzurufen.
Wir haben eine Mutation hinzugefügt, um Daten in der Datenbank zu manipulieren.
Wir haben Eingabetypen hinzugefügt, um unsere Objektparameter in der Mutation zu ersetzen, um den Regeln von GraphQL zu entsprechen.
Wir haben die Abfrage und die Mutation zu unserem Stammschema hinzugefügt, damit die GraphQL-Implementierung den Speicherort des Stammtyps versteht.

Wie Sie sehen können, werden beim Erstellen eines Schemas viele Konzepte aus der Datenmodellierung (insbesondere der Datenbankmodellierung) im Allgemeinen übernommen. Sie können sich das Schema so vorstellen, dass es der Form der Daten aus der Quelle entspricht. Es dient auch als Modell, das der Resolver implementieren wird. In den folgenden Abschnitten erfahren Sie, wie Sie mithilfe verschiedener AWS unterstützter Tools und Dienste ein Schema erstellen.

Anmerkung

Die Beispiele in den folgenden Abschnitten sind nicht für die Ausführung in einer echten Anwendung gedacht. Sie sind nur dazu da, die Befehle zu veranschaulichen, damit Sie Ihre eigenen Anwendungen erstellen können.

Erstellen von Schemata

Ihr Schema befindet sich in einer Datei mit dem Namenschema.graphql. AWS AppSync ermöglicht Benutzern, mit verschiedenen Methoden neue Schemas für ihre GraphQL-APIs zu erstellen. In diesem Beispiel erstellen wir eine leere API zusammen mit einem leeren Schema.

Console

Melden Sie sich bei der an AWS-Managementkonsole und öffnen Sie die AppSync Konsole.
1. Wählen Sie im Dashboard Create API (API erstellen) aus.
2. Wählen Sie unter API-Optionen GraphQL-APIs, Von Grund auf neu entwerfen und dann Weiter aus.
  1. Ändern Sie für den API-Namen den vorab ausgefüllten Namen in den Namen, den Ihre Anwendung benötigt.
  2. Für Kontaktinformationen können Sie eine Kontaktstelle eingeben, um einen Manager für die API zu identifizieren. Dies ist ein optionales Feld.
  3. Unter der privaten API-Konfiguration können Sie private API-Funktionen aktivieren. Auf eine private API kann nur von einem konfigurierten VPC-Endpunkt (VPCE) aus zugegriffen werden. Weitere Informationen finden Sie unter Private APIs.
    
    Wir empfehlen nicht, diese Funktion für dieses Beispiel zu aktivieren. Wählen Sie Weiter, nachdem Sie Ihre Eingaben überprüft haben.
3. Unter GraphQL-Typ erstellen können Sie wählen, ob Sie eine DynamoDB-Tabelle erstellen möchten, die Sie als Datenquelle verwenden möchten, oder ob Sie dies überspringen und später ausführen möchten.
  
  Wählen Sie für dieses Beispiel die Option GraphQL-Ressourcen später erstellen aus. Wir werden eine Ressource in einem separaten Abschnitt erstellen.
4. Überprüfe deine Eingaben und wähle dann Create API.
Sie befinden sich im Dashboard Ihrer spezifischen API. Das können Sie daran erkennen, dass der Name der API oben im Dashboard angezeigt wird. Ist dies nicht der Fall, können Sie in der Seitenleiste APIs und dann Ihre API im API-Dashboard auswählen.
1. Wählen Sie in der Seitenleiste unter dem Namen Ihrer API Schema aus.
Im Schema-Editor können Sie Ihre schema.graphql Datei konfigurieren. Sie kann leer sein oder mit Typen gefüllt sein, die aus einem Modell generiert wurden. Auf der rechten Seite befindet sich der Abschnitt Resolvers zum Anhängen von Resolvern an Ihre Schemafelder. Wir werden uns in diesem Abschnitt nicht mit Resolvern befassen.

CLI

Anmerkung

Stellen Sie bei der Verwendung der CLI sicher, dass Sie über die richtigen Berechtigungen für den Zugriff auf und die Erstellung von Ressourcen im Service verfügen. Möglicherweise möchten Sie Richtlinien mit den geringsten Rechten für Benutzer ohne Administratorrechte festlegen, die auf den Dienst zugreifen müssen. Weitere Informationen zu AWS AppSync Richtlinien finden Sie unter Identitäts- und Zugriffsverwaltung für. AWS AppSync

Darüber hinaus empfehlen wir, zuerst die Konsolenversion zu lesen, falls Sie dies noch nicht getan haben.

Falls Sie dies noch nicht getan haben, installieren Sie die AWS CLI und fügen Sie dann Ihre Konfiguration hinzu.

Erstellen Sie ein GraphQL-API-Objekt, indem Sie den create-graphql-api Befehl ausführen.

Für diesen speziellen Befehl müssen Sie zwei Parameter eingeben:

Die name Ihrer API.
Die oder die Art der Anmeldeinformationenauthentication-type, die für den Zugriff auf die API verwendet werden (IAM, OIDC usw.).

Anmerkung

Andere Parameter, z. B. Region müssen konfiguriert werden, verwenden aber normalerweise standardmäßig Ihre CLI-Konfigurationswerte.

Ein Beispielbefehl könnte so aussehen:


aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:


{
    "graphqlApi": {
        "xrayEnabled": false,
        "name": "testAPI123",
        "authenticationType": "API_KEY",
        "tags": {},
        "apiId": "abcdefghijklmnopqrstuvwxyz",
        "uris": {
            "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
            "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
        },
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
    }
}

Anmerkung
Dies ist ein optionaler Befehl, der ein vorhandenes Schema verwendet und es mithilfe eines Base-64-Blobs in den AWS AppSync Dienst hochlädt. Wir werden diesen Befehl nicht für dieses Beispiel verwenden.

Führen Sie den Befehl start-schema-creation aus.

Für diesen speziellen Befehl müssen Sie zwei Parameter eingeben:
1. Ihr api-id aus dem vorherigen Schritt.
2. Das Schema definition ist ein Base-64-kodierter binärer Blob.
Ein Beispielbefehl könnte so aussehen:
```
 aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"
```
Eine Ausgabe wird zurückgegeben:
```
{
    "status": "PROCESSING"
}
```
Dieser Befehl gibt nach der Verarbeitung nicht die endgültige Ausgabe zurück. Sie müssen einen separaten Befehl verwenden get-schema-creation-status, um das Ergebnis zu sehen. Beachten Sie, dass diese beiden Befehle asynchron sind, sodass Sie den Ausgabestatus überprüfen können, auch wenn das Schema noch erstellt wird.

CDK

Tipp

Bevor Sie das CDK verwenden, empfehlen wir Ihnen, die offizielle Dokumentation des CDK zusammen mit AWS AppSync der CDK-Referenz zu lesen. https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html

Die unten aufgeführten Schritte zeigen nur ein allgemeines Beispiel für das Snippet, das zum Hinzufügen einer bestimmten Ressource verwendet wird. Dies soll keine funktionierende Lösung in Ihrem Produktionscode sein. Wir gehen auch davon aus, dass Sie bereits eine funktionierende App haben.

Der Ausgangspunkt für das CDK ist ein bisschen anders. Idealerweise sollte Ihre schema.graphql Datei bereits erstellt sein. Sie müssen nur eine neue Datei mit der .graphql Dateierweiterung erstellen. Dies kann eine leere Datei sein.
Im Allgemeinen müssen Sie möglicherweise die Import-Direktive zu dem Dienst hinzufügen, den Sie verwenden. Sie kann beispielsweise den folgenden Formularen folgen:
```
import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'
```
Um eine GraphQL-API hinzuzufügen, muss Ihre Stack-Datei den AWS AppSync Dienst importieren:
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
```
Anmerkung
Das bedeutet, dass wir den gesamten Service unter dem appsync Schlüsselwort importieren. Um dies in Ihrer App zu verwenden, verwenden Ihre AWS AppSync Konstrukte das Formatappsync.construct_name. Wenn wir zum Beispiel eine GraphQL-API erstellen wollten, würden wir sagen. new appsync.GraphqlApi(args_go_here) Der folgende Schritt zeigt dies.
Die grundlegendste GraphQL-API wird eine name für die API und den schema Pfad enthalten.
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
  name: 'name_of_API_in_console',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema_name.graphql')),
});
```
Anmerkung
Schauen wir uns an, was dieses Snippet bewirkt. Im Rahmen von erstellen wir eine neue GraphQL-APIapi, indem wir aufrufen. appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps) Der Gültigkeitsbereich istthis, der sich auf das aktuelle Objekt bezieht. Die ID lautetAPI_ID, das ist der Ressourcenname Ihrer GraphQL-API, CloudFormation wenn sie erstellt wird. Das GraphqlApiProps enthält das name Ihrer GraphQL-API und das. schema Das schema generiert ein Schema (SchemaFile.fromAsset), indem es den absoluten Pfad (__dirname) nach der .graphql Datei (schema_name.graphql) durchsucht. In einem realen Szenario befindet sich Ihre Schemadatei wahrscheinlich in der CDK-App.
Um die an Ihrer GraphQL-API vorgenommenen Änderungen zu verwenden, müssen Sie die App erneut bereitstellen.

Hinzufügen von Typen zu Schemas

Nachdem Sie Ihr Schema hinzugefügt haben, können Sie damit beginnen, sowohl Ihre Eingabe- als auch Ihre Ausgabetypen hinzuzufügen. Beachten Sie, dass die Typen hier nicht in echtem Code verwendet werden sollten. Sie sind nur Beispiele, die Ihnen helfen, den Prozess zu verstehen.

Zuerst erstellen wir einen Objekttyp. In echtem Code müssen Sie nicht mit diesen Typen beginnen. Sie können jederzeit jeden gewünschten Typ erstellen, solange Sie die Regeln und die Syntax von GraphQL befolgen.

Anmerkung

In den nächsten Abschnitten wird der Schema-Editor verwendet, lassen Sie ihn also offen.

Console

Sie können einen Objekttyp erstellen, indem Sie das type Schlüsselwort zusammen mit dem Namen des Typs verwenden:
```
type Type_Name_Goes_Here {}
```
Innerhalb des Gültigkeitsbereichs des Typs können Sie Felder hinzufügen, die die Eigenschaften des Objekts repräsentieren:
```
type Type_Name_Goes_Here {
  # Add fields here
}
```
Hier ein Beispiel:
```
type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
Anmerkung
In diesem Schritt haben wir einen generischen Objekttyp mit einem als gespeicherten id PflichtfeldID, einem als gespeicherten title Feld und einem als gespeicherten date Feld hinzugefügtAWSDateTime. String Eine Liste der Typen und Felder und ihrer Funktionen finden Sie unter Schemas. Eine Liste der Skalare und ihrer Funktionen finden Sie in der Typreferenz.

CLI

Anmerkung

Wir empfehlen, zuerst die Konsolenversion zu lesen, falls Sie dies noch nicht getan haben.

Sie können einen Objekttyp erstellen, indem Sie den create-type Befehl ausführen.

Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:
1. Die api-id Ihrer API.
2. Derdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das:
```
type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
3. Der format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.
Ein Beispielbefehl könnte so aussehen:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL
```
Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:
```
{
    "type": {
        "definition": "type Obj_Type_1{id: ID! title: String date: AWSDateTime}",
        "name": "Obj_Type_1",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Obj_Type_1",
        "format": "SDL"
    }
}
```
Anmerkung
In diesem Schritt haben wir einen generischen Objekttyp mit einem erforderlichen id Feld hinzugefügt, das als gespeichert istID, einem title Feld, das als gespeichert istString, und einem date Feld, das als gespeichert istAWSDateTime. Eine Liste der Typen und Felder und ihrer Funktionen finden Sie unter Schemas. Eine Liste der Skalare und ihrer Funktionen finden Sie unter Typreferenz.
Außerdem haben Sie vielleicht bemerkt, dass die direkte Eingabe der Definition für kleinere Typen funktioniert, für das Hinzufügen größerer oder mehrerer Typen jedoch nicht durchführbar ist. Sie können sich dafür entscheiden, alles in eine .graphql Datei einzufügen und es dann als Eingabe zu übergeben.

CDK

Tipp

Bevor Sie das CDK verwenden, empfehlen wir Ihnen, die offizielle Dokumentation des CDK zusammen mit der CDK-Referenz zu AWS AppSync lesen.

Um einen Typ hinzuzufügen, müssen Sie ihn zu Ihrer .graphql Datei hinzufügen. Das Konsolenbeispiel lautete zum Beispiel:


type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Sie können Ihre Typen wie jede andere Datei direkt zum Schema hinzufügen.

Anmerkung

Um die an Ihrer GraphQL-API vorgenommenen Änderungen zu verwenden, müssen Sie die App erneut bereitstellen.

Der Objekttyp hat Felder, bei denen es sich um skalare Typen wie Zeichenketten und Ganzzahlen handelt. AWS AppSync ermöglicht es Ihnen auch, erweiterte Skalartypen zu verwenden, z. B. AWSDateTime zusätzlich zu den GraphQL-Basisskalaren. Außerdem ist jedes Feld erforderlich, das mit einem Ausrufezeichen endet.

Insbesondere der ID Skalartyp ist ein eindeutiger Bezeichner, der entweder oder sein kann. String Int Sie können diese in Ihrem Resolvercode für die automatische Zuweisung steuern.

Es gibt Ähnlichkeiten zwischen speziellen Objekttypen wie Query und „normalen“ Objekttypen wie dem obigen Beispiel darin, dass beide das type Schlüsselwort verwenden und als Objekte betrachtet werden. Bei den speziellen Objekttypen (QueryMutation, undSubscription) unterscheidet sich ihr Verhalten jedoch erheblich, da sie als Einstiegspunkte für Ihre API bereitgestellt werden. Bei ihnen geht es auch mehr um die Gestaltung von Vorgängen als um Daten. Weitere Informationen finden Sie unter Die Abfrage- und Mutationstypen.

Apropos spezielle Objekttypen. Der nächste Schritt könnte darin bestehen, einen oder mehrere von ihnen hinzuzufügen, um Operationen an den geformten Daten durchzuführen. In einem realen Szenario muss jedes GraphQL-Schema mindestens einen Root-Abfragetyp zum Anfordern von Daten haben. Sie können sich die Abfrage als einen der Einstiegspunkte (oder Endpunkte) für Ihren GraphQL-Server vorstellen. Lassen Sie uns eine Abfrage als Beispiel hinzufügen.

Console

Um eine Abfrage zu erstellen, können Sie sie einfach wie jeden anderen Typ zur Schemadatei hinzufügen. Eine Abfrage würde einen Query Typ und einen Eintrag im Stammverzeichnis wie folgt erfordern:
```
schema {
  query: Name_of_Query
}

type Name_of_Query {
  # Add field operation here
}
```
Beachten Sie, dass Name_of_Query in einer Produktionsumgebung Query in den meisten Fällen einfach aufgerufen wird. Wir empfehlen, diesen Wert beizubehalten. Innerhalb des Abfragetyps können Sie Felder hinzufügen. Jedes Feld führt eine Operation in der Anfrage aus. Daher werden die meisten, wenn nicht alle dieser Felder an einen Resolver angehängt. In diesem Abschnitt befassen wir uns jedoch nicht damit. In Bezug auf das Format der Feldoperation könnte es so aussehen:
```
Name_of_Query(params): Return_Type # version with params
Name_of_Query: Return_Type # version without params
```
Hier ein Beispiel:
```
schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
Anmerkung
In diesem Schritt haben wir einen Query Typ hinzugefügt und ihn in unserem schema Stammverzeichnis definiert. Unser Query Typ hat ein getObj Feld definiert, das eine Liste von Obj_Type_1 Objekten zurückgibt. Beachten Sie, Obj_Type_1 dass dies das Objekt des vorherigen Schritts ist. Im Produktionscode arbeiten Ihre Feldoperationen normalerweise mit Daten, die durch Objekte wie geformt sindObj_Type_1. Darüber hinaus verfügen Felder wie getObj in der Regel über einen Resolver, der die Geschäftslogik ausführt. Das wird in einem anderen Abschnitt behandelt.
Als zusätzlicher Hinweis: Fügt bei Exporten AWS AppSync automatisch einen Schemastamm hinzu, sodass Sie ihn technisch gesehen nicht direkt zum Schema hinzufügen müssen. Unser Service verarbeitet automatisch doppelte Schemas. Wir fügen es hier als bewährte Methode hinzu.

CLI

Anmerkung

Wir empfehlen, zuerst die Konsolenversion zu lesen, falls Sie dies noch nicht getan haben.

Erstellen Sie ein schema Stammverzeichnis mit einer query Definition, indem create-type Sie den Befehl ausführen.

Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:
1. Die api-id Ihrer API.
2. Derdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das:
```
schema {
  query: Query
}
```
3. Der format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.
Ein Beispielbefehl könnte so aussehen:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL
```
Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:
```
{
    "type": {
        "definition": "schema {query: Query}",
        "name": "schema",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}
```
Anmerkung
Beachten Sie, dass Sie Ihren Schemastamm (oder einen beliebigen Typ im Schema) aktualisieren können, wenn Sie etwas nicht korrekt in den create-type Befehl eingegeben haben, indem Sie den update-type Befehl ausführen. In diesem Beispiel ändern wir vorübergehend den Schemastamm, sodass er eine subscription Definition enthält.
Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:
1. Die api-id Ihrer API.
2. Die type-name Ihres Typs. Im Konsolenbeispiel war dasschema.
3. Dasdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das:
  
  schema { query: Query }
  
  Das Schema nach dem Hinzufügen eines subscription wird wie folgt aussehen:
  
  schema { query: Query subscription: Subscription }
4. Die format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.
Ein Beispielbefehl könnte so aussehen:
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL
```
Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:
```
{
    "type": {
        "definition": "schema {query: Query subscription: Subscription}",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}
```
Das Hinzufügen vorformatierter Dateien funktioniert in diesem Beispiel weiterhin.
Erstellen Sie einen Query Typ, indem Sie den create-type Befehl ausführen.

Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:
1. Die api-id Ihrer API.
2. Derdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das:
```
type Query {
  getObj: [Obj_Type_1]
}
```
3. Der format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.
Ein Beispielbefehl könnte so aussehen:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL
```
Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:
```
{
    "type": {
        "definition": "Query {getObj: [Obj_Type_1]}",
        "name": "Query",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
        "format": "SDL"
    }
}
```
Anmerkung
In diesem Schritt haben wir einen Query Typ hinzugefügt und ihn in Ihrem schema Stammverzeichnis definiert. Unser Query Typ hat ein getObj Feld definiert, das eine Liste von Obj_Type_1 Objekten zurückgegeben hat.
Im schema Stammcode gibt der query: Teil anquery: Query, dass eine Abfrage in Ihrem Schema definiert wurde, während der Query Teil den tatsächlichen Namen eines speziellen Objekts angibt.

CDK

Tipp

Bevor Sie das CDK verwenden, empfehlen wir Ihnen, die offizielle Dokumentation des CDK zusammen mit der CDK-Referenz zu AWS AppSync lesen.

Sie müssen Ihre Abfrage und den Schemastamm zur .graphql Datei hinzufügen. Unser Beispiel sah aus wie das folgende Beispiel, aber Sie sollten es durch Ihren tatsächlichen Schema-Code ersetzen:


schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Sie können Ihre Typen wie jede andere Datei direkt zum Schema hinzufügen.

Anmerkung

Das Aktualisieren des Schemastammes ist optional. Wir haben es diesem Beispiel als bewährte Methode hinzugefügt.

Um die an Ihrer GraphQL-API vorgenommenen Änderungen zu verwenden, müssen Sie die App erneut bereitstellen.

Sie haben jetzt ein Beispiel für die Erstellung von Objekten und speziellen Objekten (Abfragen) gesehen. Sie haben auch gesehen, wie diese miteinander verknüpft werden können, um Daten und Operationen zu beschreiben. Sie können Schemas verwenden, die nur die Datenbeschreibung und eine oder mehrere Abfragen enthalten. Wir möchten jedoch eine weitere Operation hinzufügen, um der Datenquelle Daten hinzuzufügen. Wir fügen einen weiteren speziellen Objekttyp hinzuMutation, der Daten modifiziert.

Console

Eine Mutation wird aufgerufenMutation. Zum Query Beispiel beschreiben die darin Mutation enthaltenen Feldoperationen eine Operation und werden an einen Resolver angehängt. Beachten Sie auch, dass wir es im schema Stammverzeichnis definieren müssen, da es sich um einen speziellen Objekttyp handelt. Hier ist ein Beispiel für eine Mutation:
```
schema {
  mutation: Name_of_Mutation
}

type Name_of_Mutation {
  # Add field operation here
}
```
Eine typische Mutation wird wie eine Abfrage in der Wurzel aufgeführt. Die Mutation wird mithilfe des type Schlüsselworts zusammen mit dem Namen definiert. Name_of_Mutationwird normalerweise genanntMutation, daher empfehlen wir, es so zu belassen. Jedes Feld führt auch eine Operation aus. In Bezug auf das Format der Feldoperation könnte es so aussehen:
```
Name_of_Mutation(params): Return_Type # version with params
Name_of_Mutation: Return_Type # version without params
```
Hier ein Beispiel:
```
schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
Anmerkung
In diesem Schritt haben wir einen Mutation Typ mit einem addObj Feld hinzugefügt. Lassen Sie uns zusammenfassen, was dieses Feld bewirkt:
```
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
```
addObjverwendet das Obj_Type_1 Objekt, um eine Operation auszuführen. Dies ist aufgrund der Felder offensichtlich, aber die Syntax beweist dies im : Obj_Type_1 Rückgabetyp. addObjIm Inneren akzeptiert es die date Felder idtitle, und aus dem Obj_Type_1 Objekt als Parameter. Wie Sie vielleicht sehen, sieht es einer Methodendeklaration sehr ähnlich. Wir haben das Verhalten unserer Methode jedoch noch nicht beschrieben. Wie bereits erwähnt, dient das Schema nur dazu, zu definieren, wie die Daten und Operationen aussehen werden und nicht, wie sie funktionieren. Die Implementierung der eigentlichen Geschäftslogik erfolgt später, wenn wir unsere ersten Resolver erstellen.
Sobald Sie mit Ihrem Schema fertig sind, besteht die Möglichkeit, es als schema.graphql Datei zu exportieren. Im Schema-Editor können Sie Schema exportieren wählen, um die Datei in einem unterstützten Format herunterzuladen.
Als zusätzlicher Hinweis: Fügt bei Exporten AWS AppSync automatisch einen Schemastamm hinzu, sodass Sie ihn technisch gesehen nicht direkt zum Schema hinzufügen müssen. Unser Service verarbeitet automatisch doppelte Schemas. Wir fügen es hier als bewährte Methode hinzu.

CLI

Anmerkung

Wir empfehlen, zuerst die Konsolenversion zu lesen, falls Sie dies noch nicht getan haben.

Aktualisieren Sie Ihr Stammschema, indem Sie den update-type Befehl ausführen.

Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:
1. Die api-id Ihrer API.
2. Die type-name Ihres Typs. Im Konsolenbeispiel war dasschema.
3. Dasdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das:
```
schema {
  query: Query
  mutation: Mutation
}
```
4. Der format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.
Ein Beispielbefehl könnte so aussehen:
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL
```
Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:
```
{
    "type": {
        "definition": "schema {query: Query mutation: Mutation}",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}
```

Erstellen Sie einen Mutation Typ, indem Sie den create-type Befehl ausführen.

Für diesen speziellen Befehl müssen Sie einige Parameter eingeben:

Die api-id Ihrer API.

Derdefinition, oder der Inhalt Ihres Typs. Im Konsolenbeispiel war das


type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

Der format Ihrer Eingabe. In diesem Beispiel verwenden wirSDL.

Ein Beispielbefehl könnte so aussehen:


aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL

Eine Ausgabe wird in der CLI zurückgegeben. Hier ein Beispiel:


{
    "type": {
        "definition": "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}",
        "name": "Mutation",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
        "format": "SDL"
    }
}

CDK

Tipp

Bevor Sie das CDK verwenden, empfehlen wir Ihnen, die offizielle Dokumentation des CDK zusammen mit der CDK-Referenz zu AWS AppSync lesen.

Sie müssen Ihre Abfrage und den Schemastamm zur .graphql Datei hinzufügen. Unser Beispiel sah aus wie das folgende Beispiel, aber Sie sollten es durch Ihren tatsächlichen Schema-Code ersetzen:


schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

Anmerkung

Das Aktualisieren des Schemastammes ist optional. Wir haben es diesem Beispiel als bewährte Methode hinzugefügt.

Um die an Ihrer GraphQL-API vorgenommenen Änderungen zu verwenden, müssen Sie die App erneut bereitstellen.

Optionale Überlegungen — Verwendung von Enumerationen als Status

An diesem Punkt wissen Sie, wie Sie ein Basisschema erstellen. Es gibt jedoch viele Dinge, die Sie hinzufügen könnten, um die Funktionalität des Schemas zu erweitern. Eine häufige Sache in Anwendungen ist die Verwendung von Aufzählungen als Status. Sie können eine Enumeration verwenden, um zu erzwingen, dass ein bestimmter Wert aus einer Reihe von Werten ausgewählt wird, wenn sie aufgerufen wird. Das ist gut für Dinge, von denen Sie wissen, dass sie sich über lange Zeiträume nicht drastisch ändern werden. Hypothetisch gesprochen könnten wir eine Aufzählung hinzufügen, die den Statuscode oder die Zeichenfolge in der Antwort zurückgibt.

Nehmen wir als Beispiel an, wir erstellen eine Social-Media-App, die die Postdaten eines Benutzers im Backend speichert. Unser Schema enthält einen Post Typ, der die Daten eines einzelnen Beitrags darstellt:


type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

Unser Post wird einen eindeutigen id Beitrag für einen Beitrag title und eine Aufzählung mit dem Namen enthaltenPostStatus, die den Status des Beitrags während der Verarbeitung durch die App darstellt. date Für unsere Operationen werden wir eine Abfrage haben, die alle Postdaten zurückgibt:


type Query {
  getPosts: [Post]
}

Wir werden auch eine Mutation haben, die Beiträge zur Datenquelle hinzufügt:


type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

Wenn wir uns unser Schema ansehen, könnte die PostStatus Enumeration mehrere Status haben. Wir möchten vielleicht, dass die drei Grundzustände success (Post erfolgreich verarbeitet), pending (Beitrag wird bearbeitet) und error (Beitrag kann nicht verarbeitet werden) heißen. Um die Aufzählung hinzuzufügen, könnten wir Folgendes tun:


enum PostStatus {
  success
  pending
  error
}

Das vollständige Schema könnte so aussehen:


schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts: [Post]
}

enum PostStatus {  
  success
  pending
  error
}

Wenn ein Benutzer Post in der Anwendung eine hinzufügt, wird der addPost Vorgang aufgerufen, um diese Daten zu verarbeiten. Während der an ihn angehängte Resolver die Daten addPost verarbeitet, aktualisiert er sie kontinuierlich poststatus mit dem Status des Vorgangs. Bei einer Abfrage Post wird der endgültige Status der Daten angezeigt. Denken Sie daran, dass wir nur beschreiben, wie die Daten im Schema funktionieren sollen. Wir gehen bei der Implementierung unserer Resolver, die die eigentliche Geschäftslogik für die Verarbeitung der Daten zur Erfüllung der Anfrage implementieren, von vielen Annahmen aus.

Optionale Überlegungen — Abonnements

Abonnements in AWS AppSync werden als Reaktion auf eine Mutation aufgerufen. Diese werden mit einem Subscription-Typ und einer @aws_subscribe()-Anweisung im Schema konfiguriert, um anzugeben, welche Mutationen ein oder mehrere Abonnements aufrufen. Weitere Informationen zur Konfiguration von Abonnements finden Sie unter Real-time Daten.

Optionale Überlegungen — Beziehungen und Seitennummerierung

Angenommen, Sie haben eine Million in einer DynamoDB-Tabelle Posts gespeichert und möchten einen Teil dieser Daten zurückgeben. Die oben angegebene Beispielabfrage gibt jedoch nur alle Beiträge zurück. Sie möchten diese nicht jedes Mal abrufen, wenn Sie eine Anfrage stellen. Stattdessen möchten Sie sie durchblättern. Nehmen Sie dazu die folgenden Änderungen an Ihrem Schema vor:

Fügen Sie in dem getPosts Feld zwei Eingabeargumente hinzu: nextToken (Iterator) und limit (Iterationslimit).
Fügen Sie einen neuen PostIterator Typ hinzu, der die Posts Felder (ruft die Liste der Post Objekte ab) und nextToken (Iterator) enthält.
Ändern Sie ihn getPosts so, dass er zurückkehrt PostIterator und keine Liste von Post Objekten.


schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts(limit: Int, nextToken: String): PostIterator
}

enum PostStatus {
  success
  pending
  error
}

type PostIterator {
  posts: [Post]
  nextToken: String
}

Der PostIterator Typ ermöglicht es Ihnen, einen Teil der Post Objektliste zurückzugeben und a, nextToken um den nächsten Teil abzurufen. Darin befindet PostIterator sich eine Liste von Post Elementen ([Post]), die mit einem Paginierungstoken (nextToken) zurückgegeben werden. In AWS AppSync würde dies über einen Resolver mit Amazon DynamoDB verbunden und automatisch als verschlüsseltes Token generiert. Dadurch wird der Wert des Arguments limit in den Parameter maxResults und des Arguments nextToken in den Parameter exclusiveStartKey konvertiert. Beispiele und die integrierten Vorlagenbeispiele in der AWS AppSync Konsole finden Sie unter Resolver-Referenz (). JavaScript

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Strukturierung einer GraphQL-API (leer oder importiert APIs)

Eine Datenquelle anhängen