Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Progettazione dello schema GraphQL

Lo schema GraphQL è il fondamento di qualsiasi implementazione del server GraphQL. Ogni API GraphQL è definita da un singolo schema che contiene tipi e campi che descrivono come verranno popolati i dati delle richieste. I dati che fluiscono attraverso l'API e le operazioni eseguite devono essere convalidati rispetto allo schema.

In generale, il sistema di tipo GraphQL descrive le funzionalità di un server GraphQL e viene utilizzato per determinare se una query è valida. Il sistema di tipi di un server viene spesso definito schema di quel server e può essere costituito da diversi tipi di oggetti, tipi scalari, tipi di input e altro ancora. GraphQL è sia dichiarativo che fortemente tipizzato, il che significa che i tipi saranno ben definiti in fase di esecuzione e restituiranno solo ciò che è stato specificato.

AWS AppSync consente di definire e configurare schemi GraphQL. La sezione seguente descrive come creare schemi GraphQL da zero utilizzando i servizi. AWS AppSync

Strutturare uno schema GraphQL

GraphQL è un potente strumento per l'implementazione di servizi API. Secondo il sito Web di GraphQL, GraphQL è il seguente:

«GraphQL è un linguaggio di query per le API e un runtime per soddisfare tali query con i dati esistenti. GraphQL fornisce una descrizione completa e comprensibile dei dati nella tua API, offre ai clienti il potere di chiedere esattamente ciò di cui hanno bisogno e nient'altro, semplifica l'evoluzione delle API nel tempo e abilita potenti strumenti di sviluppo. »

Questa sezione copre la primissima parte dell'implementazione di GraphQL, lo schema. Utilizzando la citazione precedente, uno schema svolge il ruolo di «fornire una descrizione completa e comprensibile dei dati nell'API». In altre parole, uno schema GraphQL è una rappresentazione testuale dei dati, delle operazioni e delle relazioni tra di essi del servizio. Lo schema è considerato il punto di ingresso principale per l'implementazione del servizio GraphQL. Non sorprende che sia spesso una delle prime cose che fai nel tuo progetto. Ti consigliamo di consultare la sezione Schemi prima di continuare.

Per citare la sezione Schemas, gli schemi GraphQL sono scritti nello Schema Definition Language (SDL). SDL è composto da tipi e campi con una struttura consolidata:

Gli schemi più semplici conterranno tre diverse categorie di dati:

Per mettere questo in prospettiva, immagina di creare un servizio che memorizza gli autori e i libri che hanno scritto. Ogni autore ha un nome e una serie di libri di cui è autore. Ogni libro ha un nome e un elenco di autori associati. Vogliamo anche la possibilità di aggiungere o recuperare libri e autori. Una semplice rappresentazione UML di questa relazione può essere simile alla seguente:

In GraphQL, le entità Author Book rappresentano due diversi tipi di oggetti nello schema:

type Author {
}

type Book {
}

Authorcontiene authorName eBooks, mentre Book contiene bookName eAuthors. Questi possono essere rappresentati come campi nell'ambito dei tipi:

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

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

Come puoi vedere, le rappresentazioni dei tipi sono molto simili al diagramma. Tuttavia, i metodi sono dove la cosa diventa un po' più complicata. Questi verranno inseriti in uno dei pochi tipi di oggetti speciali come campo. La loro classificazione speciale degli oggetti dipende dal loro comportamento. GraphQL contiene tre tipi fondamentali di oggetti speciali: query, mutazioni e sottoscrizioni. Per ulteriori informazioni, vedere Oggetti speciali. https://docs.aws.amazon.com/appsync/latest/devguide/graphql-types.html#special-object-components

Poiché getAuthor getBook entrambi richiedono dati, verranno inseriti in un tipo di oggetto Query speciale:

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

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

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

Le operazioni sono collegate all'interrogazione, che a sua volta è collegata allo schema. L'aggiunta di una radice dello schema definirà il tipo di oggetto speciale (Queryin questo caso) come uno dei punti di ingresso. Questo può essere fatto usando la schema parola chiave:

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
}

Stiamo esaminando gli ultimi due metodi addAuthor e addBook stiamo aggiungendo dati al database, quindi verranno definiti in un tipo di oggetto Mutation speciale. Tuttavia, dalla pagina Tipi, sappiamo anche che gli input che fanno riferimento direttamente agli oggetti non sono consentiti perché sono strettamente tipi di output. In questo caso, non possiamo usare Author orBook, quindi dobbiamo creare un tipo di input con gli stessi campi. In questo esempio, abbiamo aggiunto AuthorInput eBookInput, entrambi accettano gli stessi campi dei rispettivi tipi. Quindi, creiamo la nostra mutazione utilizzando gli input come parametri:

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
}

Rivediamo cosa abbiamo appena fatto:

Come puoi vedere, il processo di creazione di uno schema richiede molti concetti dalla modellazione dei dati (in particolare dalla modellazione di database) in generale. Puoi pensare che lo schema si adatti alla forma dei dati di origine. Serve anche come modello che il resolver implementerà. Nelle sezioni seguenti, imparerai come creare uno schema utilizzando vari strumenti e AWS servizi supportati.

Creazione di schemi

Il tuo schema sarà contenuto in un file chiamatoschema.graphql. AWS AppSync consente agli utenti di creare nuovi schemi per le proprie API GraphQL utilizzando vari metodi. In questo esempio, creeremo un'API vuota insieme a uno schema vuoto.

Console

1. Accedi Console di gestione AWS e apri la AppSync console.

   1. Nel pannello di controllo, scegliere Create API (Crea API).

   2. In Opzioni API, scegli API GraphQL, Design from scratch, quindi Next.

      1. Per il nome dell'API, modifica il nome precompilato in base alle esigenze dell'applicazione.

      2. Per i dettagli di contatto, puoi inserire un punto di contatto per identificare un responsabile dell'API. Questo campo è opzionale.

      3. In Configurazione API privata, puoi abilitare le funzionalità API private. È possibile accedere a un'API privata solo da un endpoint VPC (VPCE) configurato. Per ulteriori informazioni, consulta API private. https://docs.aws.amazon.com/appsync/latest/devguide/using-private-apis.html

         Non è consigliabile abilitare questa funzionalità per questo esempio. Scegli Avanti dopo aver esaminato i tuoi input.

   3. In Crea un tipo GraphQL, puoi scegliere di creare una tabella DynamoDB da utilizzare come origine dati o saltarla e farlo in un secondo momento.

      Per questo esempio, scegli Crea risorse GraphQL in un secondo momento. Creeremo una risorsa in una sezione separata.

   4. Rivedi i tuoi input, quindi scegli Crea API.

2. Verrai visualizzato il pannello di controllo della tua API specifica. Puoi capirlo perché il nome dell'API sarà nella parte superiore della dashboard. In caso contrario, puoi selezionare le API nella barra laterale, quindi scegliere la tua API nella dashboard delle API.

   1. Nella barra laterale sotto il nome dell'API, scegli Schema.

3. Nell'editor dello schema, puoi configurare il tuo file. schema.graphql Può essere vuoto o pieno di tipi generati da un modello. Sulla destra, c'è la sezione Resolvers per allegare i resolver ai campi dello schema. Non esamineremo i resolver in questa sezione.

CLI

Nota

Quando utilizzi la CLI, assicurati di disporre delle autorizzazioni corrette per accedere e creare risorse nel servizio. Potresti voler impostare criteri con privilegi minimi per gli utenti non amministratori che devono accedere al servizio. Per ulteriori informazioni sulle AWS AppSync politiche, consulta Gestione delle identità e degli accessi per. AWS AppSync

Inoltre, ti consigliamo di leggere prima la versione per console se non l'hai già fatto.

1. Se non l'hai già fatto, installa la AWS CLI, quindi aggiungi la tua configurazione.

2. Crea un oggetto API GraphQL eseguendo il create-graphql-api comando.

   Dovrai digitare due parametri per questo particolare comando:

   1. La name tua API.

   2. Ilauthentication-type, o il tipo di credenziali utilizzate per accedere all'API (IAM, OIDC, ecc.).

   Nota

   Altri parametri, ad esempio, Region devono essere configurati, ma di solito sono predefiniti i valori di configurazione della CLI.

   Un comando di esempio può essere simile al seguente:

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

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "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"
       }
   }

3. Nota

   Questo è un comando opzionale che prende uno schema esistente e lo carica nel AWS AppSync servizio utilizzando un blob base-64. Non useremo questo comando per questo esempio.

   Esegui il comando start-schema-creation.

   Dovrai digitare due parametri per questo particolare comando:

   1. Proviene api-id dal passaggio precedente.

   2. Lo schema definition è un blob binario codificato in base 64.

   Un comando di esempio può essere simile a questo:

    aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"

   Verrà restituito un output:

   {
       "status": "PROCESSING"
   }

   Questo comando non restituirà l'output finale dopo l'elaborazione. È necessario utilizzare un comando separato per visualizzare il risultato. get-schema-creation-status Nota che questi due comandi sono asincroni, quindi puoi controllare lo stato dell'output anche mentre lo schema è ancora in fase di creazione.

CDK

Suggerimento

Prima di utilizzare il CDK, ti consigliamo di consultare la documentazione ufficiale del CDK insieme ai riferimenti al CDK. AWS AppSynchttps://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html

I passaggi elencati di seguito mostreranno solo un esempio generale dello snippet utilizzato per aggiungere una particolare risorsa. Questa non è pensata per essere una soluzione funzionante nel codice di produzione. Supponiamo inoltre che tu abbia già un'app funzionante.

1. Il punto di partenza del CDK è leggermente diverso. Idealmente, il schema.graphql file dovrebbe essere già stato creato. Devi solo creare un nuovo file con l'estensione del .graphql file. Può essere un file vuoto.

2. In generale, potrebbe essere necessario aggiungere la direttiva di importazione al servizio che si sta utilizzando. Ad esempio, può seguire i seguenti moduli:

   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'

   Per aggiungere un'API GraphQL, il file stack deve importare il AWS AppSync servizio:

   import * as appsync from 'aws-cdk-lib/aws-appsync';

   Nota

   Ciò significa che stiamo importando l'intero servizio con la appsync parola chiave. Per utilizzarlo nella tua app, i tuoi AWS AppSync costrutti utilizzeranno il formato. appsync.construct_name Ad esempio, se volessimo creare un'API GraphQL, diremmo. new appsync.GraphqlApi(args_go_here) Il passaggio seguente lo illustra.

3. L'API GraphQL più semplice includerà una name per l'API e il schema percorso.

   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')),
   });

   Nota

   Esaminiamo cosa fa questo frammento. Nell'ambito diapi, stiamo creando una nuova API GraphQL chiamando. appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps) L'ambito èthis, che si riferisce all'oggetto corrente. L'id èAPI_ID, che sarà il nome della risorsa dell'API GraphQL al CloudFormation momento della creazione. GraphqlApiPropsContiene la name tua API GraphQL e il. schema schemaGenererà uno schema (SchemaFile.fromAsset) cercando il percorso assoluto (__dirname) per il .graphql file (schema_name.graphql). In uno scenario reale, il tuo file di schema sarà probabilmente all'interno dell'app CDK.

   Per utilizzare le modifiche apportate all'API GraphQL, dovrai ridistribuire l'app.

Aggiungere tipi agli schemi

Ora che hai aggiunto il tuo schema, puoi iniziare ad aggiungere sia i tipi di input che quelli di output. Nota che i tipi qui riportati non devono essere utilizzati nel codice reale; sono solo esempi per aiutarti a comprendere il processo.

Innanzitutto, creeremo un tipo di oggetto. Nel codice reale, non è necessario iniziare con questi tipi. Puoi creare qualsiasi tipo tu voglia in qualsiasi momento purché segua le regole e la sintassi di GraphQL.

Console

• Puoi creare un tipo di oggetto usando la type parola chiave insieme al nome del tipo:

  type Type_Name_Goes_Here {}

  All'interno dell'ambito del tipo, puoi aggiungere campi che rappresentano le caratteristiche dell'oggetto:

  type Type_Name_Goes_Here {
    # Add fields here
  }

  Ecco un esempio:

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

  Nota

  In questo passaggio, abbiamo aggiunto un tipo di oggetto generico con un id campo obbligatorio memorizzato comeID, un title campo archiviato come e un date campo archiviato comeAWSDateTime. String Per visualizzare un elenco di tipi e campi e a cosa servono, vedi Schemi. Per visualizzare un elenco di scalari e le relative funzioni, consulta il riferimento Type.

CLI

Nota

Ti consigliamo di leggere prima la versione per console se non l'hai già fatto.

• È possibile creare un tipo di oggetto eseguendo il create-type comando.

  Dovrai inserire alcuni parametri per questo particolare comando:

  1. La api-id tua API.

  2. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era:

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

  3. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

  Un comando di esempio può essere simile a questo:

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

  Verrà restituito un output nella CLI. Ecco un esempio:

  {
      "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"
      }
  }

  Nota

  In questo passaggio, abbiamo aggiunto un tipo di oggetto generico con un id campo obbligatorio memorizzato comeID, un title campo memorizzato come e un date campo memorizzato come. String AWSDateTime Per visualizzare un elenco di tipi e campi e a cosa servono, vedi Schemi. Per visualizzare un elenco di scalari e le relative funzioni, vedi Riferimento ai tipi.

  Inoltre, potresti aver capito che l'immissione della definizione funziona direttamente per i tipi più piccoli ma non è fattibile per l'aggiunta di tipi più grandi o multipli. Puoi scegliere di aggiungere tutto in un .graphql file e poi passarlo come input.

CDK

Suggerimento

Prima di utilizzare il CDK, ti consigliamo di consultare la documentazione ufficiale del CDK insieme AWS AppSync ai riferimenti al CDK.

I passaggi elencati di seguito mostreranno solo un esempio generale dello snippet utilizzato per aggiungere una particolare risorsa. Questa non è pensata per essere una soluzione funzionante nel codice di produzione. Supponiamo inoltre che tu abbia già un'app funzionante.

Per aggiungere un tipo, devi aggiungerlo al tuo .graphql file. Ad esempio, l'esempio della console era:

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

Puoi aggiungere i tuoi tipi direttamente allo schema come qualsiasi altro file.

Nota

Per utilizzare le modifiche apportate alla tua API GraphQL, dovrai ridistribuire l'app.

Il tipo di oggetto ha campi di tipo scalare come stringhe e numeri interi. AWS AppSync consente inoltre di utilizzare tipi scalari avanzati, ad esempio AWSDateTime in aggiunta agli scalari GraphQL di base. Inoltre, è obbligatorio qualsiasi campo che termina con un punto esclamativo.

Il tipo ID scalare, in particolare, è un identificatore univoco che può essere uno o. String Int Puoi controllarli nel codice del tuo resolver per l'assegnazione automatica.

Esistono somiglianze tra tipi di oggetti speciali Query e tipi di oggetti «normali» come nell'esempio precedente in quanto entrambi utilizzano la type parola chiave e sono considerati oggetti. Tuttavia, per i tipi di oggetti speciali (QueryMutation, eSubscription), il loro comportamento è molto diverso perché sono esposti come punti di ingresso per l'API. Inoltre, riguardano più la modellazione delle operazioni che dei dati. Per ulteriori informazioni, vedi I tipi di query e mutazione.

Per quanto riguarda i tipi di oggetti speciali, il passaggio successivo potrebbe essere l'aggiunta di uno o più di essi per eseguire operazioni sui dati sagomati. In uno scenario reale, ogni schema GraphQL deve avere almeno un tipo di query root per la richiesta di dati. Puoi pensare alla query come a uno dei punti di ingresso (o endpoint) per il tuo server GraphQL. Aggiungiamo una query come esempio.

Console

• Per creare una query, puoi semplicemente aggiungerla al file dello schema come qualsiasi altro tipo. Una query richiederebbe un Query tipo e una voce nella radice come segue:

  schema {
    query: Name_of_Query
  }
  
  type Name_of_Query {
    # Add field operation here
  }

  Nota che Name_of_Query in un ambiente di produzione verrà semplicemente chiamato Query nella maggior parte dei casi. Consigliamo di mantenerlo a questo valore. All'interno del tipo di query, puoi aggiungere campi. Ogni campo eseguirà un'operazione nella richiesta. Di conseguenza, la maggior parte, se non tutti, di questi campi verrà collegata a un resolver. Tuttavia, questo non ci interessa in questa sezione. Per quanto riguarda il formato dell'operazione sul campo, potrebbe assomigliare a questo:

  Name_of_Query(params): Return_Type # version with params
  Name_of_Query: Return_Type # version without params

  Ecco un esempio:

  schema {
    query: Query
  }
  
  type Query {
    getObj: [Obj_Type_1]
  }
  
  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }

  Nota

  In questo passaggio, abbiamo aggiunto un Query tipo e lo abbiamo definito nella nostra schema radice. Il nostro Query tipo ha definito un getObj campo che restituisce un elenco di Obj_Type_1 oggetti. Nota che Obj_Type_1 è l'oggetto del passaggio precedente. Nel codice di produzione, le operazioni sul campo normalmente funzioneranno con dati modellati da oggetti comeObj_Type_1. Inoltre, campi come getObj normalmente dispongono di un resolver per eseguire la logica aziendale. Questo verrà trattato in una sezione diversa.

  Come nota aggiuntiva, aggiunge AWS AppSync automaticamente una radice dello schema durante le esportazioni, quindi tecnicamente non è necessario aggiungerla direttamente allo schema. Il nostro servizio elaborerà automaticamente gli schemi duplicati. Lo stiamo aggiungendo qui come best practice.

CLI

Nota

Ti consigliamo di leggere prima la versione per console se non l'hai già fatto.

1. Crea una schema radice con una query definizione eseguendo il create-type comando.

   Dovrai inserire alcuni parametri per questo particolare comando:

   1. La api-id tua API.

   2. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era:

      schema {
        query: Query
      }

   3. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

   Un comando di esempio può essere simile a questo:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "type": {
           "definition": "schema {query: Query}",
           "name": "schema",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   Nota

   Nota che se non hai inserito correttamente qualcosa nel create-type comando, puoi aggiornare la radice dello schema (o qualsiasi tipo nello schema) eseguendo il update-type comando. In questo esempio, modificheremo temporaneamente la radice dello schema per contenere una subscription definizione.

   Dovrai inserire alcuni parametri per questo particolare comando:

   1. La api-id tua API.

   2. La type-name del tuo tipo. Nell'esempio della console, questo eraschema.

   3. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era:

      schema {
        query: Query
      }

      Lo schema dopo aver aggiunto un subscription sarà simile al seguente:

      schema {
        query: Query
        subscription: Subscription
      }

   4. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

   Un comando di esempio può essere simile a questo:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "type": {
           "definition": "schema {query: Query subscription: Subscription}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   L'aggiunta di file preformattati funzionerà comunque in questo esempio.

2. Crea un Query tipo eseguendo il comando. create-type

   Dovrai inserire alcuni parametri per questo particolare comando:

   1. La api-id tua API.

   2. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era:

      type Query {
        getObj: [Obj_Type_1]
      }

   3. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

   Un comando di esempio può essere simile a questo:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "type": {
           "definition": "Query {getObj: [Obj_Type_1]}",
           "name": "Query",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
           "format": "SDL"
       }
   }

   Nota

   In questo passaggio, abbiamo aggiunto un Query tipo e lo abbiamo definito nella schema radice. Il nostro Query tipo ha definito un getObj campo che restituiva un elenco di Obj_Type_1 oggetti.

   Nel codice schema radicequery: Query, la query: parte indica che è stata definita una query nello schema, mentre la Query parte indica il nome effettivo dell'oggetto speciale.

CDK

Suggerimento

Prima di utilizzare il CDK, ti consigliamo di consultare la documentazione ufficiale del CDK insieme AWS AppSync ai riferimenti al CDK.

I passaggi elencati di seguito mostreranno solo un esempio generale dello snippet utilizzato per aggiungere una particolare risorsa. Questa non è pensata per essere una soluzione funzionante nel codice di produzione. Supponiamo inoltre che tu abbia già un'app funzionante.

Dovrai aggiungere la tua query e la radice dello schema al .graphql file. Il nostro esempio era simile a quello riportato di seguito, ma ti consigliamo di sostituirlo con il codice dello schema effettivo:

schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

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

Puoi aggiungere i tuoi tipi direttamente allo schema come qualsiasi altro file.

Nota

L'aggiornamento della radice dello schema è facoltativo. L'abbiamo aggiunto a questo esempio come best practice.

Per utilizzare le modifiche apportate all'API GraphQL, dovrai ridistribuire l'app.

Ora hai visto un esempio di creazione sia di oggetti che di oggetti speciali (query). Hai anche visto come questi possono essere interconnessi per descrivere dati e operazioni. Puoi avere schemi con solo la descrizione dei dati e una o più query. Tuttavia, vorremmo aggiungere un'altra operazione per aggiungere dati all'origine dati. Aggiungeremo un altro tipo di oggetto speciale chiamato Mutation che modifica i dati.

Console

• Verrà chiamata una mutazione. Mutation Ad esempioQuery, le operazioni sul campo all'interno Mutation descriveranno un'operazione e saranno collegate a un resolver. Inoltre, nota che dobbiamo definirlo nella schema radice perché è un tipo di oggetto speciale. Ecco un esempio di mutazione:

  schema {
    mutation: Name_of_Mutation
  }
  
  type Name_of_Mutation {
    # Add field operation here
  }

  Una mutazione tipica verrà elencata nella radice come una query. La mutazione viene definita utilizzando la type parola chiave insieme al nome. Name_of_Mutationdi solito viene chiamatoMutation, quindi consigliamo di mantenerlo così. Ogni campo eseguirà anche un'operazione. Per quanto riguarda il formato dell'operazione sul campo, potrebbe assomigliare a questo:

  Name_of_Mutation(params): Return_Type # version with params
  Name_of_Mutation: Return_Type # version without params

  Ecco un esempio:

  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
  }

  Nota

  In questo passaggio, abbiamo aggiunto un Mutation tipo con un addObj campo. Riassumiamo cosa fa questo campo:

  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1

  addObjsta usando l'Obj_Type_1oggetto per eseguire un'operazione. Ciò è evidente grazie ai campi, ma la sintassi lo dimostra nel tipo : Obj_Type_1 restituito. All'internoaddObj, accetta i date campi idtitle, e dell'Obj_Type_1oggetto come parametri. Come puoi vedere, assomiglia molto a una dichiarazione di metodo. Tuttavia, non abbiamo ancora descritto il comportamento del nostro metodo. Come affermato in precedenza, lo schema serve solo a definire quali saranno i dati e le operazioni e non come funzioneranno. L'implementazione della logica aziendale effettiva avverrà più tardi, quando creeremo i nostri primi resolver.

  Una volta terminato lo schema, c'è un'opzione per esportarlo come file. schema.graphql Nell'editor dello schema, puoi scegliere Esporta schema per scaricare il file in un formato supportato.

  Come nota aggiuntiva, aggiunge AWS AppSync automaticamente una radice dello schema durante le esportazioni, quindi tecnicamente non è necessario aggiungerla direttamente allo schema. Il nostro servizio elaborerà automaticamente gli schemi duplicati. Lo stiamo aggiungendo qui come best practice.

CLI

Nota

Ti consigliamo di leggere prima la versione per console se non l'hai già fatto.

1. Aggiorna lo schema principale eseguendo il update-type comando.

   Dovrai inserire alcuni parametri per questo particolare comando:

   1. La api-id tua API.

   2. La type-name del tuo tipo. Nell'esempio della console, questo eraschema.

   3. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era:

      schema {
        query: Query
        mutation: Mutation
      }

   4. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

   Un comando di esempio può essere simile a questo:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "type": {
           "definition": "schema {query: Query mutation: Mutation}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

2. Crea un Mutation tipo eseguendo il create-type comando.

   Dovrai inserire alcuni parametri per questo particolare comando:

   1. La api-id tua API.

   2. Ildefinition, o il contenuto del tuo tipo. Nell'esempio della console, questo era

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

   3. Il format numero del tuo input. In questo esempio, stiamo usandoSDL.

   Un comando di esempio può essere simile a questo:

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

   Verrà restituito un output nella CLI. Ecco un esempio:

   {
       "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

Suggerimento

Prima di utilizzare il CDK, ti consigliamo di consultare la documentazione ufficiale del CDK insieme AWS AppSync ai riferimenti al CDK. https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html

I passaggi elencati di seguito mostreranno solo un esempio generale dello snippet utilizzato per aggiungere una particolare risorsa. Questa non è pensata per essere una soluzione funzionante nel codice di produzione. Supponiamo inoltre che tu abbia già un'app funzionante.

Dovrai aggiungere la tua query e la radice dello schema al .graphql file. Il nostro esempio era simile all'esempio seguente, ma ti consigliamo di sostituirlo con il codice dello schema effettivo:

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
}

Nota

L'aggiornamento della radice dello schema è facoltativo. L'abbiamo aggiunto a questo esempio come best practice.

Per utilizzare le modifiche apportate all'API GraphQL, dovrai ridistribuire l'app.

Considerazioni opzionali: utilizzo delle enumerazioni come stati

A questo punto, sai come creare uno schema di base. Tuttavia, ci sono molte cose che potresti aggiungere per aumentare la funzionalità dello schema. Una cosa comune che si trova nelle applicazioni è l'uso di enumerazioni come stati. È possibile utilizzare un enum per forzare un valore specifico da un insieme di valori da scegliere quando viene chiamato. Questo è utile per cose che sai non cambieranno drasticamente per lunghi periodi di tempo. Ipoteticamente parlando, potremmo aggiungere un enum che restituisca il codice di stato o la stringa nella risposta.

Ad esempio, supponiamo di creare un'app per social media che memorizza i dati dei post di un utente nel backend. Il nostro schema contiene un Post tipo che rappresenta i dati di un singolo post:

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

Il nostro Post conterrà un post title univoco id date di pubblicazione e un enum chiamato PostStatus che rappresenta lo stato del post mentre viene elaborato dall'app. Per le nostre operazioni, avremo una query che restituisce tutti i dati del post:

type Query {
  getPosts: [Post]
}

Avremo anche una mutazione che aggiunge post alla fonte di dati:

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

Guardando il nostro schema, l'PostStatusenum potrebbe avere diversi stati. Potremmo volere che i tre stati di base si chiamino success (post processato con successo), pending (post in corso di elaborazione) e error (post non può essere elaborato). Per aggiungere l'enum, potremmo fare questo:

enum PostStatus {
  success
  pending
  error
}

Lo schema completo potrebbe assomigliare a questo:

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
}

Se un utente aggiunge un Post nell'applicazione, verrà chiamata l'addPostoperazione per elaborare quei dati. Man mano che il resolver collegato addPost elabora i dati, li aggiornerà continuamente poststatus con lo stato dell'operazione. Quando richiesto, Post conterrà lo stato finale dei dati. Tieni presente che stiamo solo descrivendo come vogliamo che i dati funzionino nello schema. Facciamo molte supposizioni sull'implementazione dei nostri resolver, che implementeranno l'effettiva logica aziendale per la gestione dei dati per soddisfare la richiesta.

Considerazioni opzionali - Abbonamenti

Le sottoscrizioni in AWS AppSync vengono richiamate come risposta a una mutazione. È possibile configurare ciò con un tipo Subscription e una direttiva @aws_subscribe() nello schema, per indicare quali mutazioni richiamano una o più sottoscrizioni. Per ulteriori informazioni sulla configurazione degli abbonamenti, vedi dati. Real-time

Considerazioni opzionali: relazioni e impaginazione

Supponiamo di avere un milione di Posts dati memorizzati in una tabella DynamoDB e di voler restituire alcuni di quei dati. Tuttavia, la query di esempio sopra riportata restituisce solo tutti i post. Non vorrai recuperarli tutti ogni volta che fai una richiesta. Invece, vorresti scorrerli tra le pagine. Apporta le modifiche seguenti allo schema:

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
}

Il PostIterator tipo consente di restituire una parte dell'elenco di Post oggetti e una nextToken per ottenere la parte successiva. All'internoPostIterator, c'è un elenco di Post elementi ([Post]) che viene restituito con un token di impaginazione (nextToken). In AWS AppSync, questo verrebbe connesso ad Amazon DynamoDB tramite un resolver e generato automaticamente come token crittografato. Il modello converte il valore dell'argomento limit nel parametro maxResults e dell'argomento nextToken nel parametro exclusiveStartKey. Per esempi e esempi di modelli integrati nella AWS AppSync console, consulta Resolver reference (). JavaScript