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à.

AWS AppSync panoramica del modello di mappatura del resolver

AWS AppSync ti consente di rispondere alle richieste GraphQL eseguendo operazioni sulle tue risorse. Per ogni campo GraphQL su cui si desidera eseguire una query o una mutazione, è necessario collegare un resolver per comunicare con una fonte di dati. La comunicazione avviene in genere tramite parametri o operazioni che sono unici per l'origine dati.

I resolver sono i connettori tra GraphQL e una fonte di dati. Spiegano AWS AppSync come tradurre una richiesta GraphQL in arrivo in istruzioni per l'origine dati di backend e come tradurre la risposta da tale fonte di dati in una risposta GraphQL. Sono scritti in Apache Velocity Template Language (VTL), che accetta la richiesta come input e genera un documento JSON contenente le istruzioni per il resolver. È possibile utilizzare modelli di mappatura per istruzioni semplici, come il passaggio di argomenti dai campi GraphQL, o per istruzioni più complesse, come scorrere gli argomenti per creare un elemento prima di inserirlo in DynamoDB.

Esistono due tipi di resolver che sfruttano i modelli di mappatura in AWS AppSync modi leggermente diversi:

Risolutori di unità

Gli unit resolver sono entità autonome che includono solo un modello di richiesta e risposta. Possono essere utilizzati per operazioni semplici come elencare le voci di un'unica origine dati.

Risolutori di pipeline

I risolutori di pipeline contengono una o più funzioni eseguite in ordine sequenziale. Ogni funzione include un modello di richiesta e un modello di risposta. Un pipeline resolver ha anche un modello before e un after che racchiudono la sequenza di funzioni che il modello contiene. Il modello after è mappato al tipo di output del campo GraphQL. I risolutori di pipeline differiscono dai risolutori di unità nel modo in cui il modello di risposta mappa l'output. Un pipeline resolver può mappare qualsiasi output desiderato, incluso l'input per un'altra funzione o il modello successivo del pipeline resolver.

Le funzioni di pipeline resolver consentono di scrivere una logica comune che è possibile riutilizzare su più resolver nello schema. Le funzioni sono collegate direttamente a un'origine dati e, come un risolutore di unità, contengono lo stesso formato di modello di mappatura di richieste e risposte.

Il diagramma seguente illustra il flusso di processo di un unit resolver a sinistra e di un pipeline resolver a destra.

I pipeline resolver contengono un superset delle funzionalità supportate dai resolver unitari e molto altro, al costo di un po' più di complessità.

Anatomia di un resolver di pipeline

Un pipeline resolver è composto da un modello Before mapping, un modello After mapping e un elenco di funzioni. Ogni funzione dispone di un modello di mappatura delle richieste e delle risposte che viene eseguito su un'origine dati. Dal momento che delega l'esecuzione a un elenco di funzioni, il resolver di pipeline non prevede il collegamento a un'origine dati. Funzioni e resolver di unità sono primitive che eseguono un'operazione su origini dati. Per ulteriori informazioni, consulta la panoramica del modello di mappatura Resolver.

Prima della mappatura del modello

Il modello di mappatura delle richieste di un risolutore di pipeline, o il passaggio Before, consente di eseguire alcune logiche di preparazione prima di eseguire le funzioni definite.

Elenco delle funzioni

L'elenco delle funzioni eseguite in sequenza da un resolver di pipeline. Il risultato valutato del modello di mappatura della richiesta afferente al resolver di pipeline viene reso disponibile alla prima funzione, come $ctx.prev.result. L'output di ogni funzione è reso disponibile per la successiva come $ctx.prev.result.

Modello di mappatura della fase successiva

Il modello di mappatura delle risposte di un pipeline resolver, o After step, consente di eseguire una logica di mappatura finale dall'output dell'ultima funzione al tipo di campo GraphQL previsto. Il risultato dell'ultima funzione in elenco è riportato nel modello di mappatura del resolver di pipeline come $ctx.prev.result o $ctx.result.

Flusso di esecuzione

Dato un risolutore di pipeline composto da due funzioni, l'elenco seguente rappresenta il flusso di esecuzione quando viene richiamato il resolver:

Utili utilità per Apache Velocity Template Language (VTL)

In fase di sviluppo, al crescere della complessità di un'applicazione, possono tornare utili direttive, comandi e funzionalità di VTL. Nell'utilizzo dei resolver di pipeline, è possibile avvalersi delle seguenti funzionalità.

$ctx.stash

La scorta è disponibile all'interno di ogni Map resolver e modello di mappatura delle funzioni. La sua istanza viene attivata dall'esecuzione del resolver. Ciò significa che permette di trasferire arbitrariamente i dati tra i modelli di mappatura della richiesta e della risposta e tra le funzioni di un resolver di pipeline. Lo stash espone gli stessi metodi della struttura dei dati della mappa Java. https://docs.oracle.com/javase/8/docs/api/java/util/Map.html

$ctx.prev.result

$ctx.prev.resultRappresenta il risultato dell'operazione precedente eseguita nel risolutore della pipeline.

Se l'operazione precedente era il modello di mappatura Before del pipeline resolver, $ctx.prev.result rappresenta l'output della valutazione del modello ed è resa disponibile per la prima funzione nella pipeline. Se l'operazione precedente corrisponde alla prima funzione, $ctx.prev.result è l'output della prima funzione, disponibile per la seconda funzione della pipeline. Se l'operazione precedente era l'ultima funzione, $ctx.prev.result rappresenta l'output dell'ultima funzione e viene resa disponibile al modello di mappatura After del pipeline resolver.

#return(data: Object)

La direttiva #return(data: Object) torna utile se occorre uscire prematuramente da un modello di mappatura. #return(data: Object), come la parola chiave return dei linguaggi di programmazione, restituisce dati ed esce dal più recente blocco definito di operazioni logiche. Se utilizzato all'interno di un modello di mappatura del resolver, quindi, #return esce dal resolver. L'utilizzo di #return(data: Object) in un modello di mappatura del resolver prevede l'impostazione di data sul campo GraphQL. L'utilizzo di #return(data: Object) da un modello di mappatura della funzione prevede l'uscita dalla funzione corrente e l'esecuzione della successiva nella pipeline o del modello di mappatura della risposta del resolver.

#return

È uguale a#return(data: Object), ma null verrà invece restituito.

$util.error

Con $util.error è possibile generare un errore di campo. Utilizzando $util.error all'interno di un modello di mappatura della funzione, è possibile generare immediatamente un errore di campo e, quindi, bloccare l'esecuzione delle funzioni successive. Per maggiori dettagli e altre $util.error firme, consulta il riferimento all'utilità Resolver Mapping Template.

$util.appendError

$util.appendError, per quanto molto simile a $util.error(), non interrompe la valutazione del modello di mappatura. Al contrario, segnala che si è verificato un errore con il campo, ma consente al modello di essere valutato e, di conseguenza, di restituire i dati. L'utilizzo di $util.appendError all'interno di una funzione non interrompe il flusso di esecuzione della pipeline. Per maggiori dettagli e altre $util.error firme, consulta il riferimento all'utilità per i modelli di mappatura Resolver.

Modello di esempio

Supponiamo di avere un'origine dati DynamoDB e un resolver Unit su un campo denominato getPost(id:ID!) che restituisce un tipo con la seguente query GraphQL: Post

getPost(id:1){
    id
    title
    content
}

Il modello di resolver potrebbe essere simile a quanto segue:

{
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

In questo modo si sostituisce il valore del parametro di input iddi 1 con ${ctx.args.id} e si genera il JSON seguente:

{
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : { "S" : "1" }
    }
}

AWS AppSync utilizza questo modello per generare istruzioni per comunicare con DynamoDB e ottenere dati (o eseguire altre operazioni a seconda dei casi). Dopo aver restituito i dati, AWS AppSync li esegue tramite un modello di mappatura della risposta opzionale, che è possibile usare per eseguire il modellamento dei dati o la logica. Ad esempio, quando riceviamo i risultati da DynamoDB, potrebbero assomigliare a questo:

{
        "id" : 1,
        "theTitle" : "AWS AppSync works offline!",
        "theContent-part1" : "It also has realtime functionality",
        "theContent-part2" : "using GraphQL"
}

È possibile scegliere di unire due dei campi in un unico campo con il seguente modello di mappatura della risposta:

{
        "id" : $util.toJson($context.data.id),
        "title" : $util.toJson($context.data.theTitle),
        "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}")
}

Ecco il modo in cui vengono modellati i dati dopo che a essi viene applicato il modello:

{
        "id" : 1,
        "title" : "AWS AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

Questi dati vengono restituiti come risposta a un client nel seguente modo:

{
        "data": {
                "getPost":      {
                        "id" : 1,
                        "title" : "AWS AppSync works offline!",
                        "content" : "It also has realtime functionality using GraphQL"
                }
        }
}

Si noti che nella maggior parte dei casi, i modelli di mappatura di risposta sono un semplice passthrough di dati, per lo più divergenti se si restituisce un singolo elemento o un elenco di elementi. Per un singolo elemento il passthrough è:

$util.toJson($context.result)

Per elenchi il passthrough è in genere:

$util.toJson($context.result.items)

Per vedere altri esempi di risolutori di unità e pipeline, consulta i tutorial su Resolver. Tutorials

Regole di deserializzazione dei modelli di mappatura valutate

I modelli di mappatura vengono valutati in una stringa. In AWS AppSync, la stringa di output deve seguire una struttura JSON per essere valida.

Inoltre, vengono applicate le seguenti regole di deserializzazione.

Le chiavi duplicate non sono consentite negli oggetti JSON

Se la stringa del modello di mappatura valutata rappresenta un oggetto JSON o contiene un oggetto con chiavi duplicate, il modello di mapping restituisce il seguente messaggio di errore:

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

Esempio di una chiave duplicata in un modello di mapping delle richieste valutate:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
        "field": "getPost" ## key 'field' has been redefined
    }
}

Per correggere questo errore, non ridefinire le chiavi negli oggetti JSON.

I caratteri finali non sono consentiti negli oggetti JSON

Se la stringa del modello di mappatura valutata rappresenta un oggetto JSON e contiene caratteri estranei finali, il modello di mapping restituisce il seguente messaggio di errore:

Trailing characters at the end of the JSON string are not allowed.

Esempio di caratteri finali in un modello di mappatura delle richieste valutate:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
    }
}extraneouschars

Per correggere questo errore, assicurati che i modelli valutati restituiscano rigorosamente JSON.