Référence de modèle de mappage des résolveurs pour DynamoDB

Le résolveur AWS AppSync DynamoDB vous permet d'utiliser GraphQL pour stocker et extraire des données dans les tables Amazon DynamoDB existantes de votre compte. Ce résolveur fonctionne en vous permettant de mapper une requête GraphQL entrante dans un appel DynamoDB, puis de mapper en retour la réponse DynamoDB à GraphQL. Cette section décrit les modèles de mappage pour les opérations DynamoDB prises en charge.

GetItem

Le document de mappage des requêtes GetItem vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête GetItem à DynamoDB et vous donne la possibilité de spécifier :

• La clé de l'élément dans DynamoDB

• S'il convient d'utiliser une lecture cohérente ou non

Le document de mappage GetItem a la structure suivante :

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB GetItem, ce champ doit être défini sur GetItem. Cette valeur est obligatoire.

key

La clé de l'élément dans DynamoDB. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

consistentRead

Indique si une lecture à cohérence forte doit être effectuée avec DynamoDB. Ce champ est facultatif et false est la valeur définie par défaut.

L'élément renvoyé de DynamoDB est converti automatiquement en types primitifs GraphQL et JSON, et il est disponible dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Exemple

Voici un modèle de mappage pour une requête GraphQL getThing(foo: String!, bar: String!) :

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "consistentRead" : true
}

Pour de plus amples informations sur l'API de DynamoDB GetItem, veuillez consulter la Documentation sur les API de DynamoDB.

PutItem

Le document de mappage des requêtes PutItem vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête PutItem à DynamoDB et vous donne la possibilité de spécifier ce qui suit :

• La clé de l'élément dans DynamoDB

• Contenu complet de l'élément (composé de key et de attributeValues)

• Conditions de réussite de l'opération

Le document de mappage PutItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    },
    "_version" : 1
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB PutItem, ce champ doit être défini sur PutItem. Cette valeur est obligatoire.

key

La clé de l'élément dans DynamoDB. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

attributeValues

Le reste des attributs de l'élément doit être placé dans DynamoDB. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Ce champ est facultatif.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête PutItem remplace toute entrée existante pour cet élément. Pour plus d'informations sur les conditions, consultez Expressions de condition. Ce champ est facultatif.

_version

Valeur numérique représentant la dernière version connue d'un élément. Ce champ est facultatif. Ce champ est utilisé pour la détection de conflits et n'est pris en charge que sur les sources de données versionnées.

L'élément écrit dans DynamoDB est converti automatiquement en types primitifs GraphQL et JSON, et il est disponible dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Exemple 1

Voici un modèle de mappage pour une mutation GraphQL updateThing(foo: String!, bar: String!, name: String!, version: Int!).

S'il n'existe aucun élément avec la clé spécifiée, il est créé. S'il existe déjà un élément avec la clé spécifiée, il est remplacé.

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
    }
}

Exemple 2

Voici un modèle de mappage pour une mutation GraphQL updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!).

Cet exemple vérifie si le champ version de l'élément qui se trouve actuellement dans DynamoDB est bien défini sur expectedVersion.

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        #set( $newVersion = $context.arguments.expectedVersion + 1 )
        "version" : $util.dynamodb.toDynamoDBJson($newVersion)
    },
    "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

Pour de plus amples informations sur l'API de DynamoDB PutItem, veuillez consulter la Documentation sur les API de DynamoDB.

UpdateItem

Le document de mappage des requêtes UpdateItem vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête UpdateItem à DynamoDB et vous donne la possibilité de spécifier ce qui suit :

• La clé de l'élément dans DynamoDB

• Une expression de mise à jour décrivant comment mettre à jour l'élément dans DynamoDB

• Conditions de réussite de l'opération

Le document de mappage UpdateItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "UpdateItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "update" : {
        "expression" : "someExpression"
        "expressionNames" : {
           "#foo" : "foo"
       },
       "expressionValues" : {
           ":bar" : ... typed value
       }
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB UpdateItem, ce champ doit être défini sur UpdateItem. Cette valeur est obligatoire.

key

La clé de l'élément dans DynamoDB. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour plus d'informations sur la spécification d'une « valeur typée », consultez Système de types (mappage des requêtes). Cette valeur est obligatoire.

update

La section update vous permet de spécifier une expression de mise à jour qui décrit comment mettre à jour l'élément dans DynamoDB. pour plus d'informations sur la rédaction des expressions de mise à jour, consultez la documentation DynamoDB UpdateExpressions. Cette section est obligatoire.

La section update possède trois composants :

expression

Expression de mise à jour. Cette valeur est obligatoire.

expressionNames

Substituts des espaces réservés de nom des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de nom utilisé dans l'expression, et la valeur doit être une chaîne correspondant au nom d'attribut de l'élément dans DynamoDB. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de nom des attributs de l'expression utilisés dans l'expression.

expressionValues

Substituts des espaces réservés de valeur des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de valeur utilisé dans l'expression, et la valeur doit être typée. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cela doit être spécifié. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de valeur des attributs de l'expression utilisés dans l'expression.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête UpdateItem met à jour l'entrée existante quel que soit son état actuel. Pour plus d'informations sur les conditions, consultez Expressions de condition. Ce champ est facultatif.

_version

Valeur numérique représentant la dernière version connue d'un élément. Ce champ est facultatif. Ce champ est utilisé pour la détection de conflits et n'est pris en charge que sur les sources de données versionnées.

L'élément mis à jour dans DynamoDB est converti automatiquement en types primitifs GraphQL et JSON, et il est disponible dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Exemple 1

Voici un modèle de mappage pour la mutation GraphQL upvote(id: ID!).

Dans cet exemple, les champs upvotes et version d'un élément de DynamoDB sont incrémentés de 1.

{
    "version" : "2017-02-28",
    "operation" : "UpdateItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "update" : {
        "expression" : "ADD #votefield :plusOne, version :plusOne",
        "expressionNames" : {
            "#votefield" : "upvotes"
        },
        "expressionValues" : {
            ":plusOne" : { "N" : 1 }
        }
    }
}

Exemple 2

Voici un modèle de mappage pour une mutation GraphQL updateItem(id: ID!, title: String, author: String, expectedVersion: Int!).

Il s'agit d'un exemple complexe qui inspecte les arguments et génère dynamiquement l'expression de mise à jour incluant uniquement les arguments qui ont été fournis par le client. Par exemple, si title et author sont omis, ils ne sont pas mis à jour. Si un argument est spécifié, mais que sa valeur est null, ce champ est supprimé de l'objet dans DynamoDB. En dernier lieu, l'opération a une condition qui vérifie si le champ version de l'élément actuellement dans DynamoDB est bien défini sur expectedVersion :

{
    "version" : "2017-02-28",

    "operation" : "UpdateItem",

    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },

    ## Set up some space to keep track of things we're updating **
    #set( $expNames  = {} )
    #set( $expValues = {} )
    #set( $expSet = {} )
    #set( $expAdd = {} )
    #set( $expRemove = [] )

    ## Increment "version" by 1 **
    $!{expAdd.put("version", ":newVersion")}
    $!{expValues.put(":newVersion", { "N" : 1 })}

    ## Iterate through each argument, skipping "id" and "expectedVersion" **
    #foreach( $entry in $context.arguments.entrySet() )
        #if( $entry.key != "id" && $entry.key != "expectedVersion" )
            #if( (!$entry.value) && ("$!{entry.value}" == "") )
                ## If the argument is set to "null", then remove that attribute from the item in DynamoDB **

                #set( $discard = ${expRemove.add("#${entry.key}")} )
                $!{expNames.put("#${entry.key}", "$entry.key")}
            #else
                ## Otherwise set (or update) the attribute on the item in DynamoDB **

                $!{expSet.put("#${entry.key}", ":${entry.key}")}
                $!{expNames.put("#${entry.key}", "$entry.key")}

                #if( $entry.key == "ups" || $entry.key == "downs" )
                    $!{expValues.put(":${entry.key}", { "N" : $entry.value })}
                #else
                    $!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
                #end
            #end
        #end
    #end

    ## Start building the update expression, starting with attributes we're going to SET **
    #set( $expression = "" )
    #if( !${expSet.isEmpty()} )
        #set( $expression = "SET" )
        #foreach( $entry in $expSet.entrySet() )
            #set( $expression = "${expression} ${entry.key} = ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to ADD **
    #if( !${expAdd.isEmpty()} )
        #set( $expression = "${expression} ADD" )
        #foreach( $entry in $expAdd.entrySet() )
            #set( $expression = "${expression} ${entry.key} ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to REMOVE **
    #if( !${expRemove.isEmpty()} )
        #set( $expression = "${expression} REMOVE" )

        #foreach( $entry in $expRemove )
            #set( $expression = "${expression} ${entry}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
    "update" : {
        "expression" : "${expression}"
        #if( !${expNames.isEmpty()} )
            ,"expressionNames" : $utils.toJson($expNames)
        #end
        #if( !${expValues.isEmpty()} )
            ,"expressionValues" : $utils.toJson($expValues)
        #end
    },

    "condition" : {
        "expression"       : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
        }
    }
}

Pour de plus amples informations sur l'API de DynamoDB UpdateItem, veuillez consulter la Documentation sur les API de DynamoDB.

DeleteItem

Le document de mappage des requêtes DeleteItem vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête DeleteItem à DynamoDB et vous donne la possibilité de spécifier ce qui suit :

• La clé de l'élément dans DynamoDB

• Conditions de réussite de l'opération

Le document de mappage DeleteItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "DeleteItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB DeleteItem, ce champ doit être défini sur DeleteItem. Cette valeur est obligatoire.

key

La clé de l'élément dans DynamoDB. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour plus d'informations sur la spécification d'une « valeur typée », consultez Système de types (mappage des requêtes). Cette valeur est obligatoire.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête DeleteItem supprime un élément existant quel que soit son état actuel. Pour plus d'informations sur les conditions, consultez Expressions de condition. Ce champ est facultatif.

_version

Valeur numérique représentant la dernière version connue d'un élément. Ce champ est facultatif. Ce champ est utilisé pour la détection de conflits et n'est pris en charge que sur les sources de données versionnées.

L'élément supprimé de DynamoDB est converti automatiquement en types primitifs GraphQL et JSON, et il est disponible dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Exemple 1

Voici un modèle de mappage pour une mutation GraphQL deleteItem(id: ID!). S'il existe déjà un élément avec cet ID, il est supprimé.

{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

Exemple 2

Voici un modèle de mappage pour une mutation GraphQL deleteItem(id: ID!, expectedVersion: Int!). S'il existe déjà un élément avec cet ID, il est supprimé, mais uniquement si son champ version est défini sur expectedVersion :

{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "condition" : {
        "expression"       : "attribute_not_exists(id) OR version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

Pour de plus amples informations sur l'API de DynamoDB DeleteItem, veuillez consulter la Documentation sur les API de DynamoDB.

Interrogation

Le document de mappage des requêtes Query vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête Query à DynamoDB et vous donne la possibilité de spécifier ce qui suit :

• Expression de la clé

• Quel index utiliser

• Tout filtre supplémentaire

• Combien d'articles renvoyer

• S'il convient d'utiliser une lecture cohérente

• Sens de la requête (vers l'avant ou l'arrière)

• Jeton de pagination

Le document de mappage Query a la structure suivante :

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "some expression",
        "expressionNames" : {
            "#foo" : "foo"
        },
        "expressionValues" : {
            ":bar" : ... typed value
        }
    }
    "index" : "fooIndex",
    "nextToken" : "a pagination token",
    "limit" : 10,
    "scanIndexForward" : true,
    "consistentRead" : false,
    "select" : "ALL_ATTRIBUTES",
    "filter" : {
        ...
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB Query, ce champ doit être défini sur Query. Cette valeur est obligatoire.

query

La section query vous permet de spécifier une expression de condition de clé qui décrit les éléments à récupérer de DynamoDB. Pour plus d'informations sur la rédaction des expressions des conditions de clé, consultez laDocumentation sur le paramètre KeyConditions de DynamoDB. Cette section doit être spécifiée.

expression

Expression de la requête. Ce champ doit être spécifié.

expressionNames

Substituts des espaces réservés de nom des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de nom utilisé dans l'expression, et la valeur doit être une chaîne correspondant au nom d'attribut de l'élément dans DynamoDB. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de nom des attributs de l'expression utilisés dans l'expression.

expressionValues

Substituts des espaces réservés de valeur des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de valeur utilisé dans l'expression, et la valeur doit être typée. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de valeur des attributs de l'expression utilisés dans l'expression.

filter

Filtre supplémentaire qui peut être utilisé pour filtrer les résultats de DynamoDB avant qu'ils soient renvoyés. Pour plus d'informations sur les filtres, consultez Filters (Filtres). Ce champ est facultatif.

index

Nom de l'index à interroger. L'opération de requête DynamoDB vous permet d'analyser les index secondaires locaux et les index secondaires globaux, en plus de l'index de clé primaire pour une clé de hachage. Si cette valeur est spécifiée, DynamoDB interroge l'index spécifié. Si elle ne l'est pas, l'index de clé primaire est interrogé.

nextToken

Jeton de pagination pour continuer une requête précédente. Il a été obtenu à partir d'une requête précédente. Ce champ est facultatif.

limit

Nombre maximum d'éléments à évaluer (pas nécessairement le nombre d'éléments correspondants). Ce champ est facultatif.

scanIndexForward

Valeur booléenne indiquant s'il convient d'interroger vers l'avant ou vers l'arrière. Ce champ est facultatif et contient true par défaut.

consistentRead

Valeur booléenne indiquant s'il convient d'utiliser des lectures cohérentes lors de l'interrogation de DynamoDB. Ce champ est facultatif et contient false par défaut.

select

Par défaut, le résolveur AWS AppSync DynamoDB renvoie uniquement les attributs qui sont projetés dans l'index. Si un plus grand nombre d'attributs est requis, vous pouvez définir ce champ. Ce champ est facultatif. Les valeurs prises en charge sont :

ALL_ATTRIBUTES

Renvoie tous les attributs de l'élément depuis la table ou l'index spécifié. Si vous interrogez un index secondaire local, DynamoDB récupère l'ensemble de l'élément de la table parent pour chaque élément correspondant de l'index. Si l'index est configuré de façon à projeter tous les attributs de l'élément, toutes les données peuvent être obtenues à partir de l'index secondaire local, et aucune extraction n'est nécessaire.

ALL_PROJECTED_ATTRIBUTES

Autorisé seulement lorsque vous interrogez un index. Extrait tous les attributs qui ont été projetés dans l'index. Si l'index est configuré de façon à projeter tous les attributs, la valeur renvoyée revient à spécifier ALL_ATTRIBUTES.

Les résultats de DynamoDB sont convertis automatiquement en types primitifs GraphQL et JSON, et il sont disponibles dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Les résultats ont la structure suivante :

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

Les champs sont définis comme suit :

items

Liste contenant les éléments renvoyés par la requête DynamoDB.

nextToken

S'il peut y avoir plusieurs résultats, nextToken contient un jeton de pagination que vous pouvez utiliser dans une autre requête. Notez qu'AWS AppSync chiffrer et masque le jeton de pagination renvoyé de DynamoDB. Cela empêche que les données provenant de votre table ne soient accidentellement communiquées au mandataire. Notez également que ces jetons de pagination ne peuvent pas être utilisés dans les différents résolveurs.

scannedCount

Nombre d'éléments correspondant à l'expression de condition de requête, avant qu'une expression de filtre (si elle est présente) ne soit appliquée.

Exemple

Voici un modèle de mappage pour une requête GraphQL getPosts(owner: ID!).

Dans cet exemple, un index secondaire global sur une table est interrogé afin de renvoyer toutes les publications détenues par l'ID spécifié.

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "ownerId = :ownerId",
        "expressionValues" : {
            ":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
        }
    }
    "index" : "owner-index"
}

Pour de plus amples informations sur l'API de DynamoDB Query, veuillez consulter la Documentation sur les API de DynamoDB.

Analyser

Le document de mappage des requêtes Scan vous permet d'indiquer au résolveur AWS AppSync DynamoDB d'effectuer une requête Scan à DynamoDB et vous donne la possibilité de spécifier ce qui suit :

• Filtre pour exclure des résultats

• Quel index utiliser

• Combien d'articles renvoyer

• S'il convient d'utiliser une lecture cohérente

• Jeton de pagination

• Analyses parallèles

Le document de mappage Scan a la structure suivante :

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "index" : "fooIndex",
    "limit" : 10,
    "consistentRead" : false,
    "nextToken" : "aPaginationToken",
    "totalSegments" : 10,
    "segment" : 1,
    "filter" : {
        ...
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2017-02-28 et 2018-05-29 sont actuellement prises en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB Scan, ce champ doit être défini sur Scan. Cette valeur est obligatoire.

filter

Filtre qui peut être utilisé pour filtrer les résultats de DynamoDB avant qu'ils soient renvoyés. Pour plus d'informations sur les filtres, consultez Filters (Filtres). Ce champ est facultatif.

index

Nom de l'index à interroger. L'opération de requête DynamoDB vous permet d'analyser les index secondaires locaux et les index secondaires globaux, en plus de l'index de clé primaire pour une clé de hachage. Si cette valeur est spécifiée, DynamoDB interroge l'index spécifié. Si elle ne l'est pas, l'index de clé primaire est interrogé.

limit

Nombre maximal d'éléments à évaluer simultanément. Ce champ est facultatif.

consistentRead

Valeur booléenne indiquant s'il convient d'utiliser des lectures cohérentes lors de l'interrogation de DynamoDB. Ce champ est facultatif et contient false par défaut.

nextToken

Jeton de pagination pour continuer une requête précédente. Il a été obtenu à partir d'une requête précédente. Ce champ est facultatif.

select

Par défaut, le résolveur AWS AppSync DynamoDB renvoie uniquement les attributs qui sont projetés dans l'index. Si un plus grand nombre d'attributs est requis, ce champ peut être défini. Ce champ est facultatif. Les valeurs prises en charge sont :

ALL_ATTRIBUTES

Renvoie tous les attributs de l'élément depuis la table ou l'index spécifié. Si vous interrogez un index secondaire local, DynamoDB récupère l'ensemble de l'élément de la table parent pour chaque élément correspondant de l'index. Si l'index est configuré de façon à projeter tous les attributs de l'élément, toutes les données peuvent être obtenues à partir de l'index secondaire local, et aucune extraction n'est nécessaire.

ALL_PROJECTED_ATTRIBUTES

Autorisé seulement lorsque vous interrogez un index. Extrait tous les attributs qui ont été projetés dans l'index. Si l'index est configuré de façon à projeter tous les attributs, la valeur renvoyée revient à spécifier ALL_ATTRIBUTES.

totalSegments

Nombre de segments pour partitionner la table lors de l'exécution d'une analyse parallèle. Ce champ est facultatif, mais doit être spécifié si segment est spécifié.

segment

Segment de table de cette opération lorsque vous effectuez une analyse parallèle. Ce champ est facultatif, mais doit être spécifié si totalSegments est spécifié.

Les résultats renvoyés par DynamoDB sont convertis automatiquement en types primitifs GraphQL et JSON, et ils sont disponibles dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Les résultats ont la structure suivante :

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

Les champs sont définis comme suit :

items

Liste contenant les éléments renvoyés par l'analyse DynamoDB.

nextToken

S'il peut y avoir plusieurs résultats, nextToken contient un jeton de pagination que vous pouvez utiliser dans une autre requête. AWS AppSync chiffre et masque le jeton de pagination renvoyé de DynamoDB. Cela empêche que les données provenant de votre table ne soient accidentellement communiquées au mandataire. D'autre part, ces jetons de pagination ne peuvent pas être utilisés dans différents résolveurs.

scannedCount

Nombre d'éléments extraits par DynamoDB avant l'application d'une expression de filtre (si elle est présente).

Exemple 1

Voici un modèle de mappage pour la requête GraphQL : allPosts.

Dans cet exemple, toutes les entrées de la table sont renvoyées.

{
    "version" : "2017-02-28",
    "operation" : "Scan"
}

Exemple 2

Voici un modèle de mappage pour la requête GraphQL : postsMatching(title: String!).

Dans cet exemple, toutes les entrées de la table sont renvoyées lorsque le titre commence par l'argument title.

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "filter" : {
        "expression" : "begins_with(title, :title)",
        "expressionValues" : {
            ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
        },
    }
}

Pour de plus amples informations sur l'API de DynamoDB Scan, veuillez consulter la Documentation sur les API de DynamoDB.

Sync

Le document de mappage de requête Sync vous permet de récupérer tous les résultats d'une table DynamoDB, puis de ne recevoir que les données modifiées depuis votre dernière requête (les mises à jour delta). Les requêtes Sync ne peuvent être effectuées qu'auprès des sources de données DynamoDB versionnées. Vous pouvez spécifier les valeurs suivantes :

• Filtre pour exclure des résultats

• Combien d'articles renvoyer

• Jeton de pagination.

• Lorsque votre dernière opération Sync a été lancée

Le document de mappage Sync a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. 2018-05-29 est le seul à être pris en charge actuellement. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération Sync, ce champ doit être défini sur Sync. Cette valeur est obligatoire.

filter

Filtre qui peut être utilisé pour filtrer les résultats de DynamoDB avant qu'ils soient renvoyés. Pour plus d'informations sur les filtres, consultez Filters (Filtres). Ce champ est facultatif.

limit

Nombre maximal d'éléments à évaluer simultanément. Ce champ est facultatif. Si cette option est omise, la limite par défaut sera définie sur 100 éléments. La valeur maximale de ce champ est 1000 éléments.

nextToken

Jeton de pagination pour continuer une requête précédente. Il a été obtenu à partir d'une requête précédente. Ce champ est facultatif.

lastSync

Le moment, en millisecondes Epoch, où la dernière opération Sync réussie a commencé. Si spécifié, seuls les éléments qui ont changé après lastSync sont retournés. Ce champ est facultatif et ne doit être renseigné qu'après avoir récupéré toutes les pages d'une opération Sync initiale. Si cette option est omise, les résultats de la table Base seront retournés, sinon les résultats de la table Delta seront retournés.

Les résultats renvoyés par la synchronisation DynamoDB sont convertis automatiquement en types primitifs GraphQL et JSON, et ils sont disponibles dans le contexte de mappage ($context.result).

Pour plus d'informations sur la conversion de type DynamoDB, consultez Système de types (mappage des demandes).

Pour plus d'informations sur les modèles de mappage des réponses, consultez Présentation des modèles de mappage des résolveurs.

Les résultats ont la structure suivante :

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10,
    startedAt = 1550000000000
}

Les champs sont définis comme suit :

items

Liste contenant les éléments renvoyés par la synchronisation.

nextToken

S'il peut y avoir plusieurs résultats, nextToken contient un jeton de pagination que vous pouvez utiliser dans une autre requête. AWS AppSync chiffre et masque le jeton de pagination renvoyé de DynamoDB. Cela empêche que les données provenant de votre table ne soient accidentellement communiquées au mandataire. D'autre part, ces jetons de pagination ne peuvent pas être utilisés dans différents résolveurs.

scannedCount

Nombre d'éléments extraits par DynamoDB avant l'application d'une expression de filtre (si elle est présente).

startedAt

Le moment, en millisecondes Epoch, où l'opération de synchronisation a commencé, que vous pouvez stocker localement et utiliser dans une autre requête comme argument lastSync. Si un jeton de pagination a été inclus dans la requête, cette valeur sera la même que celle renvoyée par la requête pour la première page de résultats.

Exemple 1

Voici un modèle de mappage pour la requête GraphQL : syncPosts(nextToken: String, lastSync: AWSTimestamp).

Dans cet exemple, si lastSync est omis, toutes les entrées de la table de base sont renvoyées. Si lastSync est fourni, seules les entrées de la table de synchronisation delta qui ont changé depuis lastSync sont renvoyées.

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit": 100,
    "nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
    "lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}

BatchGetItem

Le document de mappage de requête BatchGetItem vous permet de demander au résolveur AWS AppSync DynamoDB d'envoyer une requête BatchGetItem à DynamoDB pour récupérer plusieurs éléments, potentiellement sur plusieurs tables. Pour ce modèle de requête, vous devez spécifier les valeurs suivantes :

• Les noms de tables à partir desquels récupérer les éléments

• Les clés des éléments à récupérer dans chaque table

Les limites DynamoDBBatchGetItem s'appliquent et aucune expression de condition ne peut être fournie.

Le document de mappage BatchGetItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "BatchGetItem",
    "tables" : {
        "table1": {
           "keys": [
              ## Item to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item2 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        },
        "table2": {
           "keys": [
              ## Item3 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item4 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        }
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. Seul 2018-05-29 est pris en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération BatchGetItemDynamoDB, ce champ doit être défini sur BatchGetItem. Cette valeur est obligatoire.

tables

Les tables DynamoDB à partir desquels récupérer les éléments. La valeur est une carte où les noms de table sont spécifiés en tant que clés de la carte. Vous devez fournir au moins une table. Cette valeur tables est obligatoire.

keys

Liste de clés DynamoDB représentant la clé principale des éléments à récupérer. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes).

consistentRead

Définit s'il convient d'utiliser une lecture cohérente lors de l'exécution d'une opération GetItem. Cette valeur est facultative et est définie comme faux par défaut.

Objets à mémoriser :

• Si un élément n'a pas été récupéré à partir de la table, un élément null s'affiche dans le bloc de données pour cette table.

• Les résultats d'appel sont triés par table, dans l'ordre dans lequel ils ont été fournis dans le modèle de mappage de la requête.

• Chaque commande Get dans un BatchGetItem est atomique, toutefois, un lot peut être traité partiellement. Si un lot est traité partiellement en raison d'une erreur, les clés non traitées sont renvoyées dans le cadre du résultat de l'appel dans le bloc unprocessedKeys.

• BatchGetItem est limité à 100 clés.

Pour l'exemple de modèle de mappage de requête suivant :

{
  "version": "2018-05-29",
  "operation": "BatchGetItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

Le résultat de l'appel disponible dans $ctx.result est le suivant :

{
   "data": {
     "authors": [null],
     "posts": [
        # Was retrieved
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title",
          "post_description": "description",
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error contient des détails sur l'erreur. Les données clés, unprocessedKeys et la clé de chaque table fournie dans le modèle de mappage de requête sont assurés d'être présents dans le résultat de l'appel. Les éléments ayant été supprimés apparaissent dans le bloc de données. Les éléments qui n'ont pas été traités sont marqués comme null dans le bloc de données et sont placés dans le bloc unprocessedKeys.

Pour une description plus complète, suivez le didacticiel sur les lots DynamoDB avec AppSync ici Didacticiel : résolveurs par lots DynamoDB.

BatchDeleteItem

Le document de mappage de requête BatchDeleteItem vous permet de demander au résolveur AWS AppSync DynamoDB d'envoyer une requête BatchWriteItem à DynamoDB pour supprimer plusieurs éléments dans potentiellement plusieurs tables. Pour ce modèle de requête, vous devez spécifier les valeurs suivantes :

• Les noms de tables à partir desquels supprimer les éléments

• Les clés des éléments à supprimer dans chaque table

Les limites DynamoDBBatchWriteItem s'appliquent et aucune expression de condition ne peut être fournie.

Le document de mappage BatchDeleteItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "BatchDeleteItem",
    "tables" : {
        "table1": [
        ## Item to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. Seul 2018-05-29 est pris en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB BatchDeleteItem, ce champ doit être défini sur BatchDeleteItem. Cette valeur est obligatoire.

tables

Les tables DynamoDB à partir desquels supprimer les éléments. Chaque table est une liste de clés DynamoDB représentant la clé principale des éléments à supprimer. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Vous devez fournir au moins une table. Cette valeur tables est obligatoire.

Objets à mémoriser :

• Contrairement à l'opération DeleteItem, l'élément complètement supprimé n'est pas renvoyé dans la réponse. Seule la clé passée est renvoyée.

• Si un élément n'a pas été supprimé à partir de la table, un élément null s'affiche dans le bloc de données pour cette table.

• Les résultats d'appel sont triés par table, dans l'ordre dans lequel ils ont été fournis dans le modèle de mappage de la requête.

• Chaque commande delete à l'intérieur d'un BatchDeleteItem est atomique. Cependant, un lot peut être partiellement traité. Si un lot est traité partiellement en raison d'une erreur, les clés non traitées sont renvoyées dans le cadre du résultat de l'appel dans le bloc unprocessedKeys.

• BatchDeleteItem est limité à 25 clés.

Pour l'exemple de modèle de mappage de requête suivant :

{
  "version": "2018-05-29",
  "operation": "BatchDeleteItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

Le résultat de l'appel disponible dans $ctx.result est le suivant :

{
   "data": {
     "authors": [null],
     "posts": [
        # Was deleted
        {
          "author_id": "a1",
          "post_id": "p2"
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This key was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error contient des détails sur l'erreur. Les données clés, unprocessedKeys et la clé de chaque table fournie dans le modèle de mappage de requête sont assurés d'être présents dans le résultat de l'appel. Les éléments ayant été supprimés sont présents dans le bloc de données. Les éléments qui n'ont pas été traités sont marqués comme null dans le bloc de données et sont placés dans le bloc unprocessedKeys.

Pour une description plus complète, suivez le didacticiel sur les lots DynamoDB avec AppSync ici Didacticiel : résolveurs par lots DynamoDB.

BatchPutItem

Le document de mappage de requête BatchPutItem vous permet de demander au résolveur AWS AppSync DynamoDB d'envoyer une requête BatchWriteItem à DynamoDB pour placer plusieurs éléments dans potentiellement plusieurs tables. Pour ce modèle de requête, vous devez spécifier les valeurs suivantes :

• Les noms de tables dans lesquels placer les éléments

• Les éléments complets à placer dans chaque table

Les limites DynamoDBBatchWriteItem s'appliquent et aucune expression de condition ne peut être fournie.

Le document de mappage BatchPutItem a la structure suivante :

{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        "table1": [
        ## Item to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. Seul 2018-05-29 est pris en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB BatchPutItem, ce champ doit être défini sur BatchPutItem. Cette valeur est obligatoire.

tables

Les tables DynamoDB dans lesquelles placer les éléments. Chaque entrée de table représente une liste d'éléments DynamoDB à insérer pour cette table spécifique. Vous devez fournir au moins une table. Cette valeur est obligatoire.

Objets à mémoriser :

• Les éléments entièrement insérés sont renvoyés dans la réponse, en cas de succès.

• Si un élément n'a pas été inséré dans la table, un élément null s'affiche dans le bloc de données pour cette table.

• Les éléments insérés sont triés par table, dans l'ordre dans lequel ils ont été fournis dans le modèle de mappage de la requête.

• Chaque commande insérée dans un BatchPutItem est atomique, toutefois, un lot peut être traité partiellement. Si un lot est traité partiellement en raison d'une erreur, les clés non traitées sont renvoyées dans le cadre du résultat de l'appel dans le bloc unprocessedKeys.

• BatchPutItem est limité à 25 éléments.

Pour l'exemple de modèle de mappage de requête suivant :

{
  "version": "2018-05-29",
  "operation": "BatchPutItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          },
          "author_name": {
            "S": "a1_name"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          },
          "post_title": {
            "S": "title"
          }
        }
    ],
  }
}

Le résultat de l'appel disponible dans $ctx.result est le suivant :

{
   "data": {
     "authors": [
         null
     ],
     "posts": [
        # Was inserted
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title"
        }
     ]
   },
   "unprocessedItems": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1",
          "author_name": "a1_name"
        }
      ],
     "posts": []
   }
}

$ctx.error contient des détails sur l'erreur. Les données clés, unprocessedItems et la clé de chaque table fournie dans le modèle de mappage de requête sont assurés d'être présents dans le résultat de l'appel. Les éléments ayant été insérés sont dans le bloc de données. Les éléments qui n'ont pas été traités sont marqués comme null dans le bloc de données et sont placés dans le bloc unprocessedItems.

Pour une description plus complète, suivez le didacticiel sur les lots DynamoDB avec AppSync ici Didacticiel : résolveurs par lots DynamoDB.

TransactGetItems

Le document de mappage de requête TransactGetItems vous permet de demander au résolveur AWS AppSync DynamoDB d'envoyer une requête TransactGetItems à DynamoDB pour récupérer plusieurs éléments, potentiellement dans plusieurs tables. Pour ce modèle de requête, vous devez spécifier les valeurs suivantes :

• Nom de la table de chaque élément de requête dans lequel extraire l'élément

• La clé de chaque élément de requête à récupérer à partir de chaque table

Les limites TransactGetItems DynamoDB s'appliquent et aucune expression de condition ne peut être fournie.

Le document de mappage TransactGetItems a la structure suivante :

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "table1",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       },
       ## Second request item
       {
           "table": "table2",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       }
    ]
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. Seul 2018-05-29 est pris en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB TransactGetItems, ce champ doit être défini sur TransactGetItems. Cette valeur est obligatoire.

transactItems

Les éléments de requête à inclure. La valeur est un tableau d'éléments de requête. Au moins un élément de requête doit être fourni. Cette valeur transactItems est obligatoire.

table

Table DynamoDB à partir de laquelle extraire l'élément. La valeur est une chaîne du nom de la table. Cette valeur table est obligatoire.

key

Liste de clés DynamoDB représentant la clé principale des éléments à récupérer. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes).

Objets à mémoriser :

• Si une transaction réussit, l'ordre des éléments récupérés dans le bloc items sera le même que celui des éléments de la requête.

• Les transactions sont effectuées de manière tout ou rien. Si un élément de requête provoque une erreur, la transaction entière ne sera pas effectuée et les détails de l'erreur seront retournés.

• Un élément de requête qui ne peut pas être récupéré n'est pas une erreur. Au lieu de cela, un élément null apparaît dans le bloc éléments dans la position correspondante.

• Si l'erreur d'une transaction est TransactionCanceledException, le bloc cancellationReasons est rempli. L'ordre des motifs d'annulation dans le bloc cancellationReasons sera le même que l'ordre des éléments de demande.

• TransactGetItems est limité à 25 éléments de demande.

Pour l'exemple de modèle de mappage de requête suivant :

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "posts",
           "key": {
               "post_id": {
                 "S": "p1"
               }
           }
       },
       ## Second request item
       {
           "table": "authors",
           "key": {
               "author_id": {
                 "S": a1
               }
           }
       }
    ]
}

Si la transaction réussit et que seul le premier élément demandé est extrait, le résultat d'appel disponible dans $ctx.result est le suivant :

{
    "items": [
       {
           // Attributes of the first requested item
           "post_id": "p1",
           "post_title": "title",
           "post_description": "description"
       },
       // Could not retrieve the second requested item
       null,
    ],
    "cancellationReasons": null
}

Si la transaction échoue en raison de TransactionCanceledException causée par le premier élément de requête, le résultat d'appel disponible dans $ctx.result est le suivant :

{
    "items": null,
    "cancellationReasons": [
       {
           "type":"Sample error type",
           "message":"Sample error message"
       },
       {
           "type":"None",
           "message":"None"
       }
    ]
}

$ctx.error contient des détails sur l'erreur. Les éléments clés et cancellationReasons sont nécessairement présents dans $ctx.result.

Pour un exemple plus complet, suivez le didacticiel Transaction DynamoDB avec AppSync ici Didacticiel : Résolveurs de transactions DynamoDB.

TransactWriteItems

Le document de mappage de requête TransactWriteItems vous permet de demander au résolveur AWS AppSync DynamoDB d'envoyer une requête TransactWriteItems à DynamoDB pour placer plusieurs éléments dans potentiellement plusieurs tables. Pour ce modèle de requête, vous devez spécifier les valeurs suivantes :

• Nom de la table de destination de chaque élément de requête

• L'opération de chaque élément de demande à effectuer. Quatre types d'opérations sont pris en charge : PutItem, UpdateItem, DeleteItem et ConditionCheck

• La clé de chaque élément de demande à écrire

Les limites TransactWriteItems DynamoDB s'appliquent.

Le document de mappage TransactWriteItems a la structure suivante :

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "table1",
           "operation": "PutItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "attributeValues": {
               "baz": ... typed value
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table":"table2",
           "operation": "UpdateItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "update": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               }
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo":"foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table3",
           "operation": "DeleteItem",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table4",
           "operation": "ConditionCheck",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       }
    ]
}

Les champs sont définis comme suit :

version

Version de la définition du modèle. Seul 2018-05-29 est pris en charge. Cette valeur est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB TransactWriteItems, ce champ doit être défini sur TransactWriteItems. Cette valeur est obligatoire.

transactItems

Les éléments de requête à inclure. La valeur est un tableau d'éléments de requête. Au moins un élément de requête doit être fourni. Cette valeur transactItems est obligatoire.

Pour PutItem, les champs sont définis comme suit :

table

Table DynamoDB de destination. La valeur est une chaîne du nom de la table. Cette valeur table est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB PutItem, ce champ doit être défini sur PutItem. Cette valeur est obligatoire.

key

La clé DynamoDB représentant la clé principale des éléments à récupérer. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

attributeValues

Le reste des attributs de l'élément doit être placé dans DynamoDB. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Ce champ est facultatif.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête PutItem remplace toute entrée existante pour cet élément. Vous pouvez spécifier s'il faut récupérer l'élément existant en cas d'échec de la vérification de l'état. Pour de plus amples informations sur les conditions transactionnelles, veuillez consulter Expressions de condition de transaction. Ce champ est facultatif.

Pour UpdateItem, les champs sont définis comme suit :

table

Table DynamoDB à mettre à jour. La valeur est une chaîne du nom de la table. Cette valeur table est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB UpdateItem, ce champ doit être défini sur UpdateItem. Cette valeur est obligatoire.

key

Liste de clés DynamoDB représentant la clé principale des éléments à mettre à jour. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

update

La section update vous permet de spécifier une expression de mise à jour qui décrit comment mettre à jour l'élément dans DynamoDB. pour plus d'informations sur la rédaction des expressions de mise à jour, consultez la documentation DynamoDB UpdateExpressions. Cette section est obligatoire.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête UpdateItem met à jour l'entrée existante quel que soit son état actuel. Vous pouvez spécifier s'il faut récupérer l'élément existant en cas d'échec de la vérification de l'état. Pour de plus amples informations sur les conditions transactionnelles, veuillez consulter Expressions de condition de transaction. Ce champ est facultatif.

Pour DeleteItem, les champs sont définis comme suit :

table

La table DynamoDB dans laquelle supprimer l'élément. La valeur est une chaîne du nom de la table. Cette valeur table est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB DeleteItem, ce champ doit être défini sur DeleteItem. Cette valeur est obligatoire.

key

La clé DynamoDB représentant la clé principale des éléments à supprimer. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Si aucune condition n'est spécifiée, la requête DeleteItem supprime un élément existant quel que soit son état actuel. Vous pouvez spécifier s'il faut récupérer l'élément existant en cas d'échec de la vérification de l'état. Pour de plus amples informations sur les conditions transactionnelles, veuillez consulter Expressions de condition de transaction. Ce champ est facultatif.

Pour ConditionCheck, les champs sont définis comme suit :

table

La table DynamoDB dans laquelle vérifier la condition. La valeur est une chaîne du nom de la table. Cette valeur table est obligatoire.

operation

Opération DynamoDB à effectuer. Pour que vous puissiez effectuer l'opération DynamoDB ConditionCheck, ce champ doit être défini sur ConditionCheck. Cette valeur est obligatoire.

key

La clé DynamoDB représentant la clé principale des éléments dont les conditions doivent être vérifiées. Les éléments DynamoDB peuvent avoir une seule clé de hachage, ou une clé de hachage et une clé de tri, en fonction de la structure de la table. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cette valeur est obligatoire.

condition

Condition permettant de déterminer si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB. Vous pouvez spécifier s'il faut récupérer l'élément existant en cas d'échec de la vérification de l'état. Pour de plus amples informations sur les conditions transactionnelles, veuillez consulter Expressions de condition de transaction. Cette valeur est obligatoire.

Objets à mémoriser :

• Seules les clés des éléments de demande sont renvoyées dans la réponse, si elles réussissent. L'ordre des clés sera le même que l'ordre des éléments de demande.

• Les transactions sont effectuées de manière tout ou rien. Si un élément de requête provoque une erreur, la transaction entière ne sera pas effectuée et les détails de l'erreur seront retournés.

• Aucun élément de demande ne peut cibler le même élément. Sinon, ils provoqueront une erreur TransactionCanceledException.

• Si l'erreur d'une transaction est TransactionCanceledException, le bloc cancellationReasons est rempli. Si la vérification de l'état d'un élément de demande échoue et que vous n'avez pas spécifié returnValuesOnConditionCheckFailure comme étant false, l'élément existant dans la table est récupéré et stocké item à la position correspondante du bloc cancellationReasons.

• TransactWriteItems est limité à 25 éléments de demande.

Pour l'exemple de modèle de mappage de requête suivant :

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "posts",
           "operation": "PutItem",
           "key": {
               "post_id": {
                   "S": "p1"
               }
           },
           "attributeValues": {
               "post_title": {
                   "S": "New title"
               },
               "post_description": {
                   "S": "New description"
               }
           },
           "condition": {
               "expression": "post_title = :post_title",
               "expressionValues": {
                   ":post_title": {
                       "S": "Expected old title"
                   }
               }
           }
       },
       {
           "table":"authors",
           "operation": "UpdateItem",
           "key": {
               "author_id": {
                   "S": "a1"
               },
           },
           "update": {
               "expression": "SET author_name = :author_name",
               "expressionValues": {
                   ":author_name": {
                       "S": "New name"
                   }
               }
           },
       }
    ]
}

Si la transaction réussit, le résultat d'appel disponible dans $ctx.result est le suivant :

{
    "keys": [
       // Key of the PutItem request
       {
           "post_id": "p1",
       },
       // Key of the UpdateItem request
       {
           "author_id": "a1"
       }
    ],
    "cancellationReasons": null
}

Si la transaction échoue en raison de l'échec du contrôle de condition de la demande PutItem, le résultat d'appel disponible dans $ctx.result est le suivant :

{
    "keys": null,
    "cancellationReasons": [
       {
           "item": {
               "post_id": "p1",
               "post_title": "Actual old title",
               "post_description": "Old description"
           },
           "type": "ConditionCheckFailed",
           "message": "The condition check failed."
       },
       {
           "type": "None",
           "message": "None"
       }
    ]
}

$ctx.error contient des détails sur l'erreur. Les clés clés et cancellationReasons sont nécessairement présentes dans $ctx.result.

Pour un exemple plus complet, suivez le didacticiel Transaction DynamoDB avec AppSync ici Didacticiel : Résolveurs de transactions DynamoDB.

Système de types (mappage des demandes)

Lorsque vous utilisez le résolveur AWS AppSync DynamoDB pour appeler vos tables DynamoDB, AWS AppSync a besoin de connaître le type de chaque valeur à utiliser dans cet appel. En effet, DynamoDB prend en charge des types primitifs autres que GraphQL ou JSON (par exemple, données binaires et ensembles).. AWS AppSync a besoin d'indices lors de la conversion entre GraphQL et DynamoDB, , sinon il doit effectuer certaines hypothèses sur la façon dont les données sont structurées dans votre table.

Pour plus d'informations sur les types de données DynamoDB, consultez la documentation de DynamoDB sur les Descripteurs de types de données et les Types de données.

Une valeur DynamoDB est représentée par un objet JSON contenant une seule paire clé-valeur. La clé spécifie le type de DynamoDB, et la valeur spécifie la valeur elle-même. Dans l'exemple suivant, la clé S indique que la valeur est une chaîne, et la valeur identifier est la valeur de chaîne elle-même.

{ "S" : "identifier" }

Notez que l'objet JSON ne peut pas avoir plus d'une paire clé-valeur. Si plusieurs paires clé-valeur sont spécifiées, le document de mappage des requêtes n'est pas analysé.

Une valeur DynamoDB est utilisée n'importe où dans une demande de mappage des documents pour laquelle vous devez spécifier une valeur. Vous devrez notamment procéder ainsi dans les sections suivantes : key et attributeValue, ainsi que la section expressionValues des sections d'expression. Dans l'exemple suivant, la valeur de chaîne DynamoDB identifier est attribuée au champ id d'une section key (peut-être dans un document de mappage des requêtes GetItem).

"key" : {
   "id" : { "S" : "identifier" }
}

Types pris en charge

AWS AppSync prend en charge les types scalaires, de document et d'ensemble DynamoDB suivants :

Type de chaîne S

Valeur de chaîne unique. Une valeur de chaîne DynamoDB est indiquée par :

{ "S" : "some string" }

Voici un exemple d'utilisation :

"key" : {
   "id" : { "S" : "some string" }
}

Type d'ensemble de chaîne SS

Ensemble de valeurs de chaîne. Une valeur d'ensemble de chaîne DynamoDB est indiquée par :

{ "SS" : [ "first value", "second value", ... ] }

Voici un exemple d'utilisation :

"attributeValues" : {
   "phoneNumbers" : { "SS" : [ "[phone]", "[phone]" ] }
}

Type de nombre N

Valeur numérique unique. Une valeur numérique DynamoDB est indiquée par :

{ "N" : 1234 }

Voici un exemple d'utilisation :

"expressionValues" : {
   ":expectedVersion" : { "N" : 1 }
}

Type d'ensemble de nombres NS

Ensemble de valeurs de nombres. Une valeur d'ensemble de nombres DynamoDB est indiquée par :

{ "NS" : [ 1, 2.3, 4 ... ] }

Voici un exemple d'utilisation :

"attributeValues" : {
   "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] }
}

Type binaire B

Valeur binaire. Une valeur binaire DynamoDB est indiquée par :

{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

Notez que la valeur est une chaîne, avec une représentation encodée en base64 des données binaires. AWS AppSync décode cette chaîne en valeur binaire avant de l'envoyer DynamoDB. AWS AppSync utilise le schéma de décodage base64 tel que défini par la norme RFC 2045 : tout caractère qui ne se trouve pas dans l'alphabet en base64 est ignoré.

Voici un exemple d'utilisation :

"attributeValues" : {
   "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" }
}

Type d'ensemble binaire BS

Ensemble de valeurs binaires. Une valeur d'ensemble binaire DynamoDB est indiquée par :

{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

Notez que la valeur est une chaîne, avec une représentation encodée en base64 des données binaires. AWS AppSync décode cette chaîne en valeur binaire avant de l'envoyer DynamoDB. AWS AppSync utilise le schéma de décodage base64 tel que défini par la norme RFC 2045 : tout caractère qui ne se trouve pas dans l'alphabet en base64 est ignoré.

Voici un exemple d'utilisation :

"attributeValues" : {
   "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] }
}

Type booléen BOOL

Valeur booléenne. Une valeur booléenne DynamoDB est indiquée par :

{ "BOOL" : true }

Notez que seules les valeurs true et false sont valides.

Voici un exemple d'utilisation :

"attributeValues" : {
   "orderComplete" : { "BOOL" : false }
}

Type de liste L

Liste de n'importe quelle autre valeur DynamoDB prise en charge. Une valeur de liste DynamoDB est indiquée par :

{ "L" : [ ... ] }

Notez que la valeur est composée et que la liste peut contenir zéro ou plusieurs valeurs DynamoDB prises en charge (y compris d'autres listes). La liste peut également contenir une combinaison de différents types.

Voici un exemple d'utilisation :

{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}

Type de mappage M

Représentation d'une collection désordonnée de paires clé/valeur des autres valeurs DynamoDB prises en charge. Une valeur de mappage DynamoDB est indiquée par :

{ "M" : { ... } }

Notez qu'un mappage peut contenir zéro ou plusieurs paires clé-valeur. La clé doit être une chaîne et la valeur peut être n'importe quelle valeur DynamoDB prise en charge (y compris d'autres mappages). Le mappage peut également contenir une combinaison de différents types.

Voici un exemple d'utilisation :

{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}

Type nul NULL

Valeur null. Une valeur Null DynamoDB est indiquée par :

{ "NULL" : null }

Voici un exemple d'utilisation :

"attributeValues" : {
   "phoneNumbers" : { "NULL" : null }
}

Pour plus d'informations sur chaque type, consultez la documentation DynamoDB.

Système de types (mappage des réponses)

Lors de la réception d'une réponse de DynamoDB, AWS AppSync la convertit automatiquement en types primitifs JSON et GraphQL. Chaque attribut de DynamoDB est décodé et renvoyé dans le contexte de mappage des réponses.

Par exemple, si DynamoDB renvoie ce qui suit :

{
    "id" : { "S" : "1234" },
    "name" : { "S" : "Nadia" },
    "age" : { "N" : 25 }
}

Ensuite, le résolveur AWS AppSync DynamoDB convertit les types GraphQL et JSON comme suit :

{
    "id" : "1234",
    "name" : "Nadia",
    "age" : 25
}

Cette section explique comment AWS AppSync convertit les types scalaires, de document et d'ensemble DynamoDB suivants :

Type de chaîne S

Valeur de chaîne unique. Une valeur de chaîne DynamoDB est renvoyée comme chaîne.

Par exemple, si DynamoDB a renvoyé la valeur de chaîne DynamoDB suivante :

{ "S" : "some string" }

AWS AppSync convertit la valeur en chaîne :

"some string"

Type d'ensemble de chaîne SS

Ensemble de valeurs de chaîne. Une valeur d'ensemble de chaîne DynamoDB est renvoyée comme liste de chaînes.

Par exemple, si DynamoDB a renvoyé la valeur d'ensemble de chaîne DynamoDB suivante :

{ "SS" : [ "first value", "second value", ... ] }

AWS AppSync la convertit en liste de chaînes :

[ "[phone]", "[phone]" ]

Type de nombre N

Valeur numérique unique. Une valeur de nombre DynamoDB est renvoyée sous la forme d'un nombre.

Par exemple, si DynamoDB a renvoyé la valeur de nombre DynamoDB suivante :

{ "N" : 1234 }

AWS AppSync la convertit en nombre :

1234

Type d'ensemble de nombres NS

Ensemble de valeurs de nombres. Une valeur d'ensemble de nombres DynamoDB est renvoyée comme liste de nombres.

Par exemple, si DynamoDB a renvoyé la valeur d'ensemble de nombres DynamoDB suivante :

{ "NS" : [ 67.8, 12.2, 70 ] }

AWS AppSync la convertit en liste de nombres :

[ 67.8, 12.2, 70 ]

Type binaire B

Valeur binaire. Une valeur binaire DynamoDB est renvoyée sous la forme d'une chaîne contenant la représentation Base64 de cette valeur.

Par exemple, si DynamoDB a renvoyé la valeur binaire DynamoDB suivante :

{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

AWS AppSync la convertit en chaîne contenant la représentation Base64 de la valeur :

"SGVsbG8sIFdvcmxkIQo="

Notez que les données binaires sont codées selon le schéma Base64 tel que spécifié dans RFC 4648 et RFC 2045.

Type d'ensemble binaire BS

Ensemble de valeurs binaires. Une valeur d'ensemble binaire DynamoDB est renvoyée sous forme de liste de chaînes contenant la représentation Base64 de ces valeurs.

Par exemple, si DynamoDB a renvoyé la valeur d'ensemble binaire DynamoDB suivante :

{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

AWS AppSync la convertit en liste de chaînes contenant la représentation Base64 des valeurs :

[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]

Notez que les données binaires sont codées selon le schéma Base64 tel que spécifié dans RFC 4648 et RFC 2045.

Type booléen BOOL

Valeur booléenne. Une valeur booléenne DynamoDB est renvoyée sous la forme d'une valeur booléenne.

Par exemple, si DynamoDB a renvoyé la valeur booléenne DynamoDB suivante :

{ "BOOL" : true }

AWS AppSync la convertit en booléen :

true

Type de liste L

Liste de n'importe quelle autre valeur DynamoDB prise en charge. Une valeur de liste DynamoDB est renvoyée sous la forme d'une liste de valeurs, où chaque valeur interne est également convertie.

Par exemple, si DynamoDB a renvoyé la valeur de liste DynamoDB suivante :

{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}

AWS AppSync la convertit en liste de valeurs converties :

[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]

Type de mappage M

Collection clé-valeur de n'importe quelle autre valeur DynamoDB prise en charge. Une valeur de mappage DynamoDB est renvoyée sous la forme d'un objet JSON, où chaque clé/valeur est également convertie.

Par exemple, si DynamoDB a renvoyé la valeur de mappage DynamoDB suivante :

{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}

AWS AppSync la convertit en objet JSON :

{
   "someString" : "A string value",
   "someNumber" : 1,
   "stringSet"  : [ "Another string value", "Even more string values!" ]
}

Type nul NULL

Valeur null.

Par exemple, si DynamoDB a renvoyé la valeur Null DynamoDB suivante :

{ "NULL" : null }

AWS AppSync la convertit en valeur null :

null

Filtres

Lors de l'interrogation des objets dans DynamoDB à l'aide des opérations Query et Scan, vous pouvez spécifier un filter qui évalue les résultats et renvoie uniquement les valeurs souhaitées.

La section de mappage de filtre d'un document de mappage Query ou Scan a la structure suivante :

"filter" : {
    "expression" : "filter expression"
    "expressionNames" : {
        "#name" : "name",
    },
    "expressionValues" : {
        ":value" : ... typed value
    },
}

Les champs sont définis comme suit :

expression

Expression de la requête. Pour plus d'informations sur la rédaction des expressions de filtre, consultez la documentation QueryFilter DynamoDB et ScanFilter DynamoDB. Ce champ doit être spécifié.

expressionNames

Substituts des espaces réservés de nom des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de nom utilisé dans le expression. La valeur doit être une chaîne qui correspond au nom d'attribut de l'élément dans DynamoDB. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de nom des attributs de l'expression utilisés dans l'expression.

expressionValues

Substituts des espaces réservés de valeur des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de valeur utilisé dans l'expression, et la valeur doit être typée. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cela doit être spécifié. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de valeur des attributs de l'expression utilisés dans l'expression.

Exemple

Voici une section de filtre pour un modèle de mappage, où les entrées extraites de DynamoDB sont renvoyées uniquement si le titre commence par l'argument title.

"filter" : {
    "expression" : "begins_with(#title, :title)",
    "expressionNames" : {
        "#title" : "title"
    }
    "expressionValues" : {
        ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
    }
}

Expressions de condition

Lorsque vous mutez des objets dans DynamoDB à l'aide des opérations DynamoDB PutItem, UpdateItem et DeleteItem, vous pouvez spécifier une expression de condition qui vérifie si la demande doit réussir ou non, en fonction de l'état de l'objet déjà dans DynamoDB avant que l'opération soit effectuée.

Le résolveur AWS AppSync DynamoDB permet la spécification d'une expression de condition dans les documents de mappage des requêtes PutItem, UpdateItem et DeleteItem, ainsi que d'une stratégie à suivre si la condition échoue et si l'objet n'a pas été mis à jour.

Exemple 1

Le document de mappage PutItem suivant ne dispose pas d'une expression de condition. Par conséquent, il met un élément dans DynamoDB, même si un élément avec la même clé existe déjà, ce qui remplace l'élément existant.

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   }
}

Exemple 2

Le document de mappage PutItem suivant contient une expression de condition qui permet la réussite de l'opération uniquement si un élément avec la même clé n'existe pas dans DynamoDB.

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   },
   "condition" : {
      "expression" : "attribute_not_exists(id)"
   }
}

Par défaut, si le contrôle de la condition échoue, le résolveur AWS AppSync DynamoDB renvoie une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB dans un champ data de la section error de la réponse GraphQL. Toutefois, le résolveur AWS AppSync DynamoDB offre des fonctions supplémentaires pour aider les développeurs à gérer certains cas limites courants :

• Si le résolveur AWS AppSync DynamoDB peut déterminer que la valeur actuelle dans DynamoDB correspond au résultat souhaité, il traite l'opération comme si elle était réussie quoi qu'il arrive.

• Au lieu de renvoyer une erreur, vous pouvez configurer le résolveur personnalisé de façon à appeler une fonction Lambda pour déterminer la manière dont le résolveur AWS AppSync DynamoDB doit gérer la défaillance.

Cette opération est décrite plus en détail dans la section Gestion d'un échec de contrôle de condition.

Pour plus d'informations sur les expressions de condition DynamoDB, consultez la Documentation ConditionExpressions de DynamoDB.

Spécification d'une condition

Les documents de mappage des demandes PutItem, UpdateItem et DeleteItem permettent tous la spécification d'une section de condition facultative. Si cette section est omise, aucune vérification de condition n'est effectuée. Si elle est spécifiée, la condition doit être true pour que l'opération réussisse.

Une section condition a la structure suivante :

"condition" : {
    "expression" : "someExpression"
    "expressionNames" : {
        "#foo" : "foo"
    },
    "expressionValues" : {
        ":bar" : ... typed value
    },
    "equalsIgnore" : [ "version" ],
    "consistentRead" : true,
    "conditionalCheckFailedHandler" : {
        "strategy" : "Custom",
        "lambdaArn" : "arn:..."
    }
}

Les champs suivants spécifient la condition :

expression

Expression de mise à jour elle-même. Pour plus d'informations sur la rédaction des expressions de condition, consultez la Documentation sur le paramètre ConditionExpressions de DynamoDB. Ce champ doit être spécifié.

expressionNames

Substituts des espaces réservés de nom des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de nom utilisé dans l'expression, et la valeur doit être une chaîne correspondant au nom d'attribut de l'élément dans DynamoDB. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de nom des attributs de l'expression utilisés dans l'expression.

expressionValues

Substituts des espaces réservés de valeur des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de valeur utilisé dans l'expression, et la valeur doit être typée. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cela doit être spécifié. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de valeur des attributs de l'expression utilisés dans l'expression.

Les champs restants indiquent au résolveur AWS AppSync DynamoDB comment gérer un échec de vérification de condition :

equalsIgnore

Lorsqu'une vérification de condition échoue lors de l'utilisation de l'opération PutItem, le résolveur AWS AppSync DynamoDB compare l'élément actuellement dans DynamoDB à celui qu'il a tenté d'écrire. S'ils sont identiques, il traite l'opération comme si elle avait réussi. Vous pouvez utiliser le champ equalsIgnore afin de spécifier une liste d'attributs qu'AWS AppSync doit ignorer lors de l'exécution de cette comparaison. Par exemple, si la seule différence était un attribut version, il traite l'opération comme si elle avait réussi. Ce champ est facultatif.

consistentRead

Lorsqu'une vérification de condition échoue, AWS AppSync obtient la valeur actuelle de l'élément à partir de DynamoDB à l'aide d'une lecture à cohérence forte. Vous pouvez utiliser ce champ pour indiquer au résolveur AWS AppSync DynamoDB d'utiliser une lecture cohérente à terme (eventually consistent) à la place. Ce champ est facultatif et contient true par défaut.

conditionalCheckFailedHandler

Cette section vous permet de spécifier comment le résolveur AWS AppSync DynamoDB traite l'échec d'une vérification de condition après la comparaison de la valeur actuelle dans DynamoDB aux résultats prévus. Cette section est facultative. Si elle n'est pas spécifiée, la valeur par défaut est une stratégie Reject.

strategy

La stratégie du résolveur AWS AppSync DynamoDB est appliquée après la comparaison de la valeur actuelle dans DynamoDB aux résultats prévus. Ce champ est obligatoire et les valeurs suivantes sont possibles :

Reject

La mutation échoue et une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB dans un champ data de la section error de la réponse GraphQL.

Custom

Le résolveur AWS AppSync DynamoDB appelle une fonction Lambda personnalisée pour décider du traitement de l'échec de vérification de la condition. Lorsque la strategy est définie sur Custom, le champ lambdaArn doit contenir l'ARN de la fonction Lambda à appeler.

lambdaArn

ARN de la fonction Lambda à appeler, qui détermine comment le résolveur AWS AppSync DynamoDB doit gérer l'échec de vérification de la condition. Ce champ doit être spécifié uniquement lorsque strategy est défini sur Custom. Pour plus d'informations sur l'utilisation de cette fonction, consultez Gestion de l'échec d'une vérification de condition.

Gestion de l'échec d'une vérification de condition

Par défaut, lorsqu'un contrôle de condition échoue, le résolveur AWS AppSync DynamoDB renvoie une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB dans un champ data de la section error de la réponse GraphQL. Toutefois, le résolveur AWS AppSync DynamoDB offre des fonctions supplémentaires pour aider les développeurs à gérer certains cas limites courants :

• Si le résolveur AWS AppSync DynamoDB peut déterminer que la valeur actuelle dans DynamoDB correspond au résultat souhaité, il traite l'opération comme si elle était réussie quoi qu'il arrive.

• Au lieu de renvoyer une erreur, vous pouvez configurer le résolveur personnalisé de façon à appeler une fonction Lambda pour déterminer la manière dont le résolveur AWS AppSync DynamoDB doit gérer la défaillance.

Le diagramme de ce processus est le suivant :

Vérification du résultat souhaité

Lorsque la vérification de la condition échoue, le résolveur AWS AppSync DynamoDB effectue une demande DynamoDB GetItem pour obtenir la valeur actuelle de l'élément auprès de DynamoDB. Par défaut, il utilise une lecture à cohérence forte, mais cela peut être configuré à l'aide du champ consistentRead dans le bloc condition et comparé aux résultats prévus :

• Pour l'opération PutItem, le résolveur AWS AppSync DynamoDB compare la valeur actuelle à celle qu'il a tenté d'écrire, en excluant tous les attributs répertoriés dans equalsIgnore à partir de la comparaison. Si les éléments sont identiques, il traite l'opération comme réussie et renvoie l'élément qui a été récupéré de DynamoDB. Dans le cas contraire, il suit la stratégie configurée.

  Par exemple, si le document de mappage des requêtes PutItem ressemble à ce qui suit :

  {
     "version" : "2017-02-28",
     "operation" : "PutItem",
     "key" : {
        "id" : { "S" : "1" }
     },
     "attributeValues" : {
        "name" : { "S" : "Steve" },
        "version" : { "N" : 2 }
     },
     "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : { "N" : 1 }
        },
        "equalsIgnore": [ "version" ]
     }
  }

  Et si l'élément actuellement dans DynamoDB ressemble à ce qui suit :

  {
     "id" : { "S" : "1" },
     "name" : { "S" : "Steve" },
     "version" : { "N" : 8 }
  }

  Le résolveur AWS AppSync DynamoDB compare l'élément qu'il a tenté d'écrire à la valeur actuelle, voit que la seule différence était le champ version, mais dans la mesure où il est configuré pour ignorer le champ version, il traite l'opération comme réussie et renvoie l'élément qui a été extrait de DynamoDB.

• Pour l'opération DeleteItem, le résolveur AWS AppSync DynamoDB vérifie si un élément a été renvoyé de DynamoDB. Si aucun élément n'a été renvoyé, il traite l'opération comme réussie. Dans le cas contraire, il suit la stratégie configurée.

• Pour l'opération UpdateItem, le résolveur AWS AppSync DynamoDB ne dispose pas de suffisamment d'informations pour déterminer si l'élément actuellement dans DynamoDB correspond aux résultats prévus, et respecte donc la stratégie configurée.

Si l'état actuel de l'objet dans DynamoDB est différent du résultat attendu, le résolveur AWS AppSync DynamoDB suit la stratégie configurée, c'est-à-dire qu'il rejette les mutations ou appelle une fonction Lambda pour déterminer les opérations suivantes.

Respect de la stratégie de rejet

Lorsqu'il suit la stratégie Reject, le résolveur AWS AppSync DynamoDB renvoie une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB est également renvoyée dans un champ data de la section error de la réponse GraphQL. L'élément renvoyé de DynamoDB suit le modèle de mappage des réponses pour le convertir au format attendu par le client. Il est également filtré par l'ensemble de sélection.

Par exemple, si nous avons la demande de mutation suivante :

mutation {
    updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
        Name
        theVersion
    }
}

Si l'élément renvoyé de DynamoDB ressemble à ce qui suit :

{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}

Et si le modèle de mappage des réponses ressemble à ce qui suit :

{
   "id" : $util.toJson($context.result.id),
   "Name" : $util.toJson($context.result.name),
   "theVersion" : $util.toJson($context.result.version)
}

La réponse GraphQL se présente comme suit :

{
  "data": null,
  "errors": [
    {
      "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      "data": {
        "Name": "Steve",
        "theVersion": 8
      },
      ...
    }
  ]
}

Notez également que si des champs de l'objet renvoyé sont remplis par d'autres résolveurs et que la mutation a réussi, ils ne seront pas résolus lorsque l'objet sera renvoyé dans la section error.

Respect de la stratégie personnalisée

Lors du respect de la stratégie Custom, le résolveur AWS AppSync DynamoDB appelle une fonction Lambda pour décider de ce qu'il faut faire ensuite. La fonction Lambda choisit l'une des options suivantes :

• reject la mutation. Cela indique au résolveur AWS AppSync DynamoDB de se comporter comme si la stratégie configurée était Reject, en renvoyant une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB, comme décrit à la section précédente.

• discard la mutation. Cela indique au résolveur AWS AppSync DynamoDB d'ignorer silencieusement l'échec de la vérification de condition et de retourner la valeur dans DynamoDB.

• retry la mutation. Cela indique au résolveur AWS AppSync DynamoDB de retenter la mutation avec un nouveau document de mappage des requêtes.

Requête d'appel Lambda

Le résolveur AWS AppSync DynamoDB appelle la fonction Lambda spécifiée dans lambdaArn. Il utilise le même service-role-arn que celui configuré sur la source de données. La charge utile de l'appel a la structure suivante :

{
    "arguments": { ... },
    "requestMapping": {... },
    "currentValue": { ... },
    "resolver": { ... },
    "identity": { ... }
}

Les champs sont définis comme suit :

arguments

Arguments de la mutation GraphQL. Ce sont les mêmes arguments que ceux disponibles pour le document de mappage des demandes dans $context.arguments.

requestMapping

Document de mappage des demandes pour cette opération.

currentValue

Valeur actuelle de l'objet dans DynamoDB.

resolver

Informations sur le résolveur AWS AppSync.

identity

Informations sur l'appelant. Ce sont les mêmes informations que celles disponibles pour le document de mappage des demandes dans $context.identity.

Exemple complet de la charge utile :

{
    "arguments": {
        "id": "1",
        "name": "Steve",
        "expectedVersion": 1
    },
    "requestMapping": {
        "version" : "2017-02-28",
        "operation" : "PutItem",
        "key" : {
           "id" : { "S" : "1" }
        },
        "attributeValues" : {
           "name" : { "S" : "Steve" },
           "version" : { "N" : 2 }
        },
        "condition" : {
           "expression" : "version = :expectedVersion",
           "expressionValues" : {
               ":expectedVersion" : { "N" : 1 }
           },
           "equalsIgnore": [ "version" ]
        }
    },
    "currentValue": {
        "id" : { "S" : "1" },
        "name" : { "S" : "Steve" },
        "version" : { "N" : 8 }
    },
    "resolver": {
        "tableName": "People",
        "awsRegion": "us-west-2",
        "parentType": "Mutation",
        "field": "updatePerson",
        "outputType": "Person"
    },
    "identity": {
        "accountId": "123456789012",
        "sourceIp": "x.x.x.x",
        "user": "AIDAAAAAAAAAAAAAAAAAA",
        "userArn": "arn:aws:iam::123456789012:user/appsync"
    }
}

Réponse à l'appel de Lambda

La fonction Lambda peut inspecter la charge utile de l'appel et appliquer une logique métier afin de décider comment le résolveur AWS AppSync DynamoDB doit gérer la défaillance. Il existe trois options pour gérer l'échec de vérification de la condition :

• reject la mutation. La charge utile de la réponse pour cette option doit avoir cette structure :

  {
      "action": "reject"
  }

  Cela indique au résolveur AWS AppSync DynamoDB de se comporter comme si la stratégie configurée était Reject, en renvoyant une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB, comme décrit à la section ci-dessus.

• discard la mutation. La charge utile de la réponse pour cette option doit avoir cette structure :

  {
      "action": "discard"
  }

  Cela indique au résolveur AWS AppSync DynamoDB d'ignorer silencieusement l'échec de la vérification de condition et de retourner la valeur dans DynamoDB.

• retry la mutation. La charge utile de la réponse pour cette option doit avoir cette structure :

  {
      "action": "retry",
      "retryMapping": { ... }
  }

  Cela indique au résolveur AWS AppSync DynamoDB de retenter la mutation avec un nouveau document de mappage des requêtes. La structure de la section retryMapping dépend de l'opération de DynamoDB, et il s'agit d'un sous-ensemble de l'intégralité du document de mappage des requêtes pour cette opération.

  Pour PutItem, la section retryMapping a la structure suivante. Pour obtenir une description du champ attributeValues, consultez PutItem.

  {
      "attributeValues": { ... },
      "condition": {
          "equalsIgnore" = [ ... ],
          "consistentRead" = true
      }
  }

  Pour UpdateItem, la section retryMapping a la structure suivante. Pour obtenir une description de la section update, consultez UpdateItem.

  {
      "update" : {
          "expression" : "someExpression"
          "expressionNames" : {
              "#foo" : "foo"
          },
          "expressionValues" : {
              ":bar" : ... typed value
          }
      },
      "condition": {
          "consistentRead" = true
      }
  }

  Pour DeleteItem, la section retryMapping a la structure suivante.

  {
      "condition": {
          "consistentRead" = true
      }
  }

  Il n'y a aucun moyen de spécifier une autre opération ou une autre clé sur laquelle travailler. Le résolveur AWS AppSync DynamoDB autorise uniquement les nouvelles tentatives de la même opération sur le même objet. D'autre part, la section condition ne permet pas de spécifier un conditionalCheckFailedHandler. Si la nouvelle tentative échoue, le résolveur AWS AppSync DynamoDB suit la stratégie Reject.

Voici un exemple de fonction Lambda pour traiter une demande PutItem qui a échoué. La logique métier s'adresse à celui qui effectue l'appel. S'il a été effectué par jeffTheAdmin, il renouvelle la requête, en mettant à jour version et expectedVersion à partir de l'élément actuellement dans DynamoDB. Dans le cas contraire, il rejette la mutation.

exports.handler = (event, context, callback) => {
    console.log("Event: "+ JSON.stringify(event));

    // Business logic goes here.

    var response;
    if ( event.identity.user == "jeffTheAdmin" ) {
        response = {
            "action" : "retry",
            "retryMapping" : {
                "attributeValues" : event.requestMapping.attributeValues,
                "condition" : {
                    "expression" : event.requestMapping.condition.expression,
                    "expressionValues" : event.requestMapping.condition.expressionValues
                }
            }
        }
        response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
        response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version

    } else {
        response = { "action" : "reject" }
    }

    console.log("Response: "+ JSON.stringify(response))
    callback(null, response)
};

Expressions de condition de transaction

Les expressions de condition de transaction sont disponibles dans les modèles de mappage de requêtes des quatre types d'opérations dans TransactWriteItems, à savoir PutItem, DeleteItem, UpdateItem et ConditionCheck.

Pour PutItem, DeleteItem et UpdateItem, l'expression de condition de transaction est facultative. Pour ConditionCheck, l'expression de condition de transaction est obligatoire.

Exemple 1

Le document de mappage transactionnel DeleteItem suivant n'a pas d'expression de condition. Par conséquent, il supprime l'élément dans DynamoDB.

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
      }
   ]
}

Exemple 2

Le document de mappage transactionnel DeleteItem suivant possède une expression de condition de transaction qui permet à l'opération de réussir uniquement si l'auteur de cette publication est égal à un certain nom.

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
         "condition": {
            "expression": "author = :author",
            "expressionValues": {
               ":author": { "S" : "Chunyan" }
            }
         }
      }
   ]
}

Si la vérification de condition échoue, elle provoque TransactionCanceledException et les détails de l'erreur sont renvoyés dans $ctx.result.cancellationReasons. Notez que par défaut, l'ancien élément de DynamoDB qui est responsable de l'échec de cette vérification de condition est retourné dans $ctx.result.cancellationReasons

Spécification d'une condition

Les documents de mappage des demandes PutItem, UpdateItem et DeleteItem permettent tous la spécification d'une section de condition facultative. Si cette section est omise, aucune vérification de condition n'est effectuée. Si elle est spécifiée, la condition doit être true pour que l'opération réussisse. Le ConditionCheck doit avoir une section condition à spécifier. La condition doit être vraie pour que l'ensemble de la transaction réussisse.

Une section condition a la structure suivante :

"condition": {
    "expression": "someExpression",
    "expressionNames": {
        "#foo": "foo"
    },
    "expressionValues": {
        ":bar": ... typed value
    },
    "returnValuesOnConditionCheckFailure": false
}

Les champs suivants spécifient la condition :

expression

Expression de mise à jour elle-même. Pour plus d'informations sur la rédaction des expressions de condition, consultez la Documentation sur le paramètre ConditionExpressions de DynamoDB. Ce champ doit être spécifié.

expressionNames

Substituts des espaces réservés de nom des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de nom utilisé dans l'expression, et la valeur doit être une chaîne correspondant au nom d'attribut de l'élément dans DynamoDB. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de nom des attributs de l'expression utilisés dans l'expression.

expressionValues

Substituts des espaces réservés de valeur des attributs de l'expression, sous la forme de paires clé-valeur. La clé correspond à un espace réservé de valeur utilisé dans l'expression, et la valeur doit être typée. Pour de plus amples informations sur la spécification d'une « valeur typée », veuillez consulter Système de types (mappage des requêtes). Cela doit être spécifié. Ce champ est facultatif et doit être renseigné uniquement avec des substituts des espaces réservés de valeur des attributs de l'expression utilisés dans l'expression.

returnValuesOnConditionCheckFailure

Indiquez s'il faut récupérer l'élément dans DynamoDB lorsqu'un contrôle de condition échoue. L'élément récupéré est dans $ctx.result.cancellationReasons[$index].item, où $index est l'index de l'élément de demande qui a échoué à la vérification de condition. La valeur par défaut est true.