Référence du modèle de mappage du résolveur pour DynamoDB - AWS AppSync

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Référence du modèle de mappage du résolveur pour DynamoDB

Le résolveurAWS AppSync DynamoDB vous permet d'utiliser GraphQL pour stocker et récupérer 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 reconnecter 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 desGetItem requêtes vous permet de demander au résolveurAWS AppSync DynamoDB d'GetItemenvoyer une requête à DynamoDB et vous permet 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 :

Champs de GetItem

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 clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes). Cette valeur est obligatoire.

consistentRead

S'il faut effectuer ou non une lecture fortement cohérente avec DynamoDB. Ce champ est facultatif et false est la valeur définie par défaut.

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

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

Exemple

L'exemple suivant est un modèle de mappage pour une requête GraphQLgetThing(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 vous permet dePutItem demander au résolveurAWS AppSync DynamoDB d'envoyer unePutItem requête à DynamoDB, et vous permet de spécifier les éléments suivants :

  • 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", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... }, "_version" : 1 }

Les champs sont définis comme suit :

PutItem champs

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 clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes). Cette valeur est obligatoire.

attributeValues

Le reste des attributs de l'élément doit être placé dans DynamoDB. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 de plus amples informations sur les conditions, veuillez consulter Expressions de condition. Cette valeur est facultative.

_version

Valeur numérique représentant la dernière version connue d'un élément. Cette valeur est facultative. 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.

customPartitionKey

Lorsqu'elle est activée, cette valeur de chaîne modifie le format desds_pk enregistrementsds_sk et utilisés par la table de synchronisation delta lorsque le contrôle de version est activé (pour plus d'informations, voir Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur). Lorsque cette option est activée, le traitement de l'populateIndexFieldsentrée est également activé. Ce champ est facultatif.

populateIndexFields

Valeur booléenne qui, lorsqu'elle est activée en même temps que lecustomPartitionKey, crée de nouvelles entrées pour chaque enregistrement de la table de synchronisation delta, en particulier dans lesgsi_ds_sk colonnesgsi_ds_pk et. Pour plus d'informations, consultez la section Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur. Ce champ est facultatif.

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

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

Exemple 1

L'exemple suivant est un modèle de mappage pour une mutation GraphQLupdateThing(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

L'exemple suivant est un modèle de mappage pour une mutation GraphQLupdateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!).

Cet exemple vérifie que leversion champ est défini sur l'élément actuellement dans DynamoDBexpectedVersion.

{ "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 vous permet deUpdateItem demander au résolveurAWS AppSync DynamoDB d'envoyer uneUpdateItem requête à DynamoDB et vous permet de spécifier les éléments suivants :

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

  • 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", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "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 :

UpdateItem champs

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 clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la spécification d'une « valeur saisie », voir Système de types (mappage de requêtes). Cette valeur est obligatoire.

update

Laupdate section vous permet de spécifier une expression de mise à jour qui décrit comment mettre à jour l'élément dans DynamoDB. Pour de plus amples informations sur la façon d'écrire des expressions de mise à jour, veuillez consulter la UpdateExpressions documentation DynamoDB. 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é au nom utilisé dans leexpression, 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 plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 de plus amples informations sur les conditions, veuillez consulter Expressions de condition. Cette valeur est facultative.

_version

Valeur numérique représentant la dernière version connue d'un élément. Cette valeur est facultative. 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.

customPartitionKey

Lorsqu'elle est activée, cette valeur de chaîne modifie le format desds_pk enregistrementsds_sk et utilisés par la table de synchronisation delta lorsque le contrôle de version est activé (pour plus d'informations, voir Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur). Lorsque cette option est activée, le traitement de l'populateIndexFieldsentrée est également activé. Ce champ est facultatif.

populateIndexFields

Valeur booléenne qui, lorsqu'elle est activée en même temps que lecustomPartitionKey, crée de nouvelles entrées pour chaque enregistrement de la table de synchronisation delta, en particulier dans lesgsi_ds_sk colonnesgsi_ds_pk et. Pour plus d'informations, consultez la section Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur. Ce champ est facultatif.

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

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

Exemple 1

L'exemple suivant est un modèle de mappage pour la mutation GraphQLupvote(id: ID!).

Dans cet exemple, lesversion champsupvotes et 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

L'exemple suivant est un modèle de mappage pour une mutation GraphQLupdateItem(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 l'estnull, ce champ est supprimé de l'objet dans DynamoDB. Enfin, l'opération comporte une condition qui vérifie si leversion champ de l'élément actuellement dans DynamoDB est défini surexpectedVersion :

{ "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 vous permet deDeleteItem demander au résolveurAWS AppSync DynamoDB d'envoyer uneDeleteItem requête à DynamoDB, et vous permet de spécifier les éléments suivants :

  • 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", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "key": { "foo" : ... typed value, "bar" : ... typed value }, "condition" : { ... }, "_version" : 1 }

Les champs sont définis comme suit :

Champs de DeleteItem

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 clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la spécification d'une « valeur saisie », voir Système de types (mappage de 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 de plus amples informations sur les conditions, veuillez consulter Expressions de condition. Cette valeur est facultative.

_version

Valeur numérique représentant la dernière version connue d'un élément. Cette valeur est facultative. 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.

customPartitionKey

Lorsqu'elle est activée, cette valeur de chaîne modifie le format desds_pk enregistrementsds_sk et utilisés par la table de synchronisation delta lorsque le contrôle de version est activé (pour plus d'informations, voir Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur). Lorsque cette option est activée, le traitement de l'populateIndexFieldsentrée est également activé. Ce champ est facultatif.

populateIndexFields

Valeur booléenne qui, lorsqu'elle est activée en même temps que lecustomPartitionKey, crée de nouvelles entrées pour chaque enregistrement de la table de synchronisation delta, en particulier dans lesgsi_ds_sk colonnesgsi_ds_pk et. Pour plus d'informations, consultez la section Détection et synchronisation des conflits dans le Guide duAWS AppSync développeur. Ce champ est facultatif.

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

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

Exemple 1

L'exemple suivant est un modèle de mappage pour une mutation GraphQLdeleteItem(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

L'exemple suivant est un modèle de mappage pour une mutation GraphQLdeleteItem(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.

Query

Le document de mappage des requêtes vous permet deQuery demander au résolveurAWS AppSync DynamoDB d'envoyer uneQuery requête à DynamoDB, et vous permet de spécifier les éléments suivants :

  • 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 :

Champs de requête

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

Laquery section vous permet de spécifier une expression de condition clé qui décrit les éléments à récupérer depuis DynamoDB. Pour de plus amples informations sur l'écriture d'expressions de condition de clé, veuillez consulter la KeyConditions documentation 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é au nom utilisé dans leexpression, 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 plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 de rechercher une clé de hachage sur les index secondaires locaux et les index secondaires globaux en plus de l'index de clé primaire. Si spécifié, cela indique à DynamoDB d'interroger 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

Un booléen indiquant s'il faut 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ésolveurAWS AppSync DynamoDB retourne 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 extrait l'élément complet 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 automatiquement convertis en types primitifs GraphQL et JSON et sont disponibles dans le contexte de mappage ($context.result).

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

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 que celaAWS AppSync chiffre et masque le jeton de pagination renvoyé par 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

L'exemple suivant est un modèle de mappage pour une requête GraphQLgetPosts(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 vous permet deScan demander au résolveurAWS AppSync DynamoDB d'envoyer uneScan requête à DynamoDB, et vous permet de spécifier les éléments suivants :

  • 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 :

Champs de numérisation

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 ne 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 de rechercher une clé de hachage sur les index secondaires locaux et les index secondaires globaux en plus de l'index de clé primaire. Si spécifié, cela indique à DynamoDB d'interroger 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

Boolean qui indique s'il faut 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ésolveurAWS AppSync DynamoDB renvoie uniquement les attributs 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 extrait l'élément complet 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 le scan DynamoDB sont automatiquement convertis en types primitifs GraphQL et JSON et sont disponibles dans le contexte de mappage ($context.result).

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

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 le scan 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é par 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 qui ont été extraits par DynamoDB avant qu'une expression de filtre (le cas échéant) soit appliquée.

Exemple 1

L'exemple suivant est 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

L'exemple suivant est 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 desSync requêtes 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 du delta). Syncles requêtes ne peuvent être adressées qu'à 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", "basePartitionKey": "Base Tables PartitionKey", "deltaIndexName": "delta-index-name", "limit" : 10, "nextToken" : "aPaginationToken", "lastSync" : 1550000000000, "filter" : { ... } }

Les champs sont définis comme suit :

Champs Sync

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

basePartitionKey

La clé de partition de la table de base utilisée lors de l'exécution d'uneSync opération. Ce champ permet d'effectuer uneSync opération lorsque la table utilise une clé de partition personnalisée. Il s'agit d'un champ facultatif.

deltaIndexName

L'indice utilisé pour l'Syncopération. Cet index est nécessaire pour activer uneSync opération sur l'ensemble de la table delta store lorsque la table utilise une clé de partition personnalisée. L'Syncopération sera réalisée sur le GSI (créé legsi_ds_pk etgsi_ds_sk). Ce champ est facultatif.

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

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

Pour de plus amples informations sur les modèles de mappage de réponses, veuillez consulter Présentation des modèles de mappage Resolver.

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é par 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 qui ont été extraits par DynamoDB avant qu'une expression de filtre (le cas échéant) soit appliquée.

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

L'exemple suivant est 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 desBatchGetItem requêtes vous permet de demander au résolveurAWS AppSync DynamoDB d'BatchGetItemenvoyer une demande à DynamoDB pour récupérer plusieurs éléments, éventuellement 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 BatchGetItem DynamoDB 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 :

Champs de BatchGetItem

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 BatchGetItem, ce champ doit être défini sur BatchGetItem. Cette valeur est obligatoire.

tables

Les tables DynamoDB à partir desquelles 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 des clés DynamoDB qui représentent la clé primaire des éléments à extraire. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes).

consistentRead

S'il faut utiliser une lecture cohérente lors de l'exécution d'une GetItemopération. 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, en fonction de l'ordre dans lequel ils ont été fournis dans le modèle de mappage des requêtes.

  • ChaqueGet commande contenue dans aBatchGetItem est atomique, mais 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.

  • 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 un exemple plus complet, suivez le didacticiel DynamoDB Batch avec AppSync ici Tutoriel : Résolveurs de lots DynamoDB.

BatchDeleteItem

Le document de mappage des requêtes vous permet deBatchDeleteItem demander au résolveurAWS AppSync DynamoDB deBatchWriteItem demander à DynamoDB de supprimer plusieurs éléments, éventuellement dans 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 BatchWriteItem DynamoDB 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 :

Champs de BatchDeleteItem

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 dont vous souhaitez supprimer les éléments. Chaque tableau est une liste de clés DynamoDB représentant la clé primaire des éléments à supprimer. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes). Vous devez fournir au moins une table. Latables valeur 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, en fonction de l'ordre dans lequel ils ont été fournis dans le modèle de mappage des requêtes.

  • ChaqueDelete commande à l'intérieur de aBatchDeleteItem 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 un exemple plus complet, suivez le didacticiel DynamoDB Batch avec AppSync ici Tutoriel : Résolveurs de lots DynamoDB.

BatchPutItem

Le document de mappage des requêtes vous permet deBatchPutItem demander au résolveurAWS AppSync DynamoDB de faire uneBatchWriteItem demande à DynamoDB afin de placer plusieurs éléments, éventuellement sur 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 BatchWriteItem DynamoDB 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 :

Champs de BatchPutItem

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, en fonction de l'ordre dans lequel ils ont été fournis dans le modèle de mappage des requêtes.

  • ChaquePut commande contenue dans aBatchPutItem est atomique, mais 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.

  • 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 un exemple plus complet, suivez le didacticiel DynamoDB Batch avec AppSync ici Tutoriel : Résolveurs de lots DynamoDB.

TransactGetItems

Le document de mappage desTransactGetItems requêtes vous permet de demander au résolveurAWS AppSync DynamoDB de faire uneTransactGetItems demande à DynamoDB pour récupérer plusieurs éléments, éventuellement sur 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 :

Champs de TransactGetItems

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

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

key

Clé DynamoDB qui représente la clé primaire de l'élément à extraire. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 d'une all-or-nothing manière ou d'une autre. 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 TransactionCanceledExceptionvraie, lecancellationReasons bloc sera 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 TransactionCanceledExceptiondu premier élément de la demande, le résultat d'invocation disponible$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 sur les transactions DynamoDB avec AppSync ici Tutoriel : Résolveurs de transactions DynamoDB.

TransactWriteItems

Le document de mappage des requêtes vous permet deTransactWriteItems demander au résolveurAWS AppSync DynamoDB deTransactWriteItems demander à DynamoDB d'écrire plusieurs éléments, éventuellement dans 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 : PutItemUpdateItem, 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 } } ] }

Champs de TransactWriteItems

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

Clé DynamoDB qui représente la clé primaire de l'élément à insérer. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes). Cette valeur est obligatoire.

attributeValues

Le reste des attributs de l'élément doit être placé dans DynamoDB. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 plus d'informations sur les conditions transactionnelles, voir Expressions de conditions de transaction. Cette valeur est facultative.

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

table

La 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

Clé DynamoDB qui représente la clé primaire de l'élément à effectuer. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de requêtes). Cette valeur est obligatoire.

update

Laupdate section vous permet de spécifier une expression de mise à jour qui décrit comment mettre à jour l'élément dans DynamoDB. Pour de plus amples informations sur la façon d'écrire des expressions de mise à jour, veuillez consulter la UpdateExpressions documentation DynamoDB. 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 plus d'informations sur les conditions transactionnelles, voir Expressions de conditions de transaction. Cette valeur est facultative.

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

table

Le tableau DynamoDB dans lequel 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

Clé DynamoDB qui représente la clé primaire de l'élément à supprimer. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 plus d'informations sur les conditions transactionnelles, voir Expressions de conditions de transaction. Cette valeur est facultative.

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

Clé DynamoDB qui représente la clé primaire de l'élément à vérifier. Les éléments DynamoDB peuvent avoir une clé de hachage unique, ou une clé de hachage et une clé de tri, selon la structure de la table. Pour plus d'informations sur la façon de spécifier une « valeur saisie », voir Système de types (mappage de 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 plus d'informations sur les conditions transactionnelles, voir Expressions de conditions 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 d'une all-or-nothing manière ou d'une autre. 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. Dans le cas contraire, ils provoqueront TransactionCanceledExceptionune erreur.

  • Si l'erreur d'une transaction est TransactionCanceledExceptionvraie, lecancellationReasons bloc sera 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 de la vérification de l'état de laPutItem demande, le résultat d'invocation 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 sur les transactions DynamoDB avec AppSync ici Tutoriel : Résolveurs de transactions DynamoDB.

Système de types (mappage des demandes)

Lorsque vous utilisez le résolveurAWS AppSync DynamoDB pour appeler vos tables DynamoDB,AWS AppSync vous devez connaître le type de chaque valeur à utiliser dans cet appel. En effet, DynamoDB prend en charge davantage de primitives de type que GraphQL ou JSON (telles que les ensembles et les données binaires). AWS AppSync a besoin de quelques conseils lors de la traduction entre GraphQL et DynamoDB, sinon il devrait faire des hypothèses sur la façon dont les données sont structurées dans votre tableau.

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

Une valeur DynamoDB est représentée par un objet JSON contenant une seule paire clé-valeur. La clé indique le type DynamoDB et la valeur indique 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 un document de mappage de requêtes où 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 DynamoDBidentifier est affectée auid champ dans unekey section (peut-être dans un document de mappage deGetItem requêtes).

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

Types pris en charge

AWS AppSync prend en charge les types de scalaires, de documents et d'ensembles 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înes DynamoDB est indiquée par :

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

Voici un exemple d'utilisation :

"attributeValues" : { "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] } }
Type de nombre N

Valeur numérique unique. Une valeur de numéro 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 numéros 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 désignée par :

{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

Notez que la valeur est en fait une chaîne, la chaîne étant la représentation codée en base64 des données binaires. AWS AppSync décode cette chaîne en sa valeur binaire avant de l'envoyer à DynamoDB. AWS AppSync utilise le schéma de décodage base64 tel que défini par la RFC 2045 : tout caractère qui ne figure pas dans l'alphabet 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 en fait une chaîne, la chaîne étant la représentation codée en base64 des données binaires. AWS AppSync décode cette chaîne en sa valeur binaire avant de l'envoyer à DynamoDB. AWS AppSync utilise le schéma de décodage base64 tel que défini par la RFC 2045 : tout caractère ne figurant pas dans l'alphabet 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 toute autre valeur DynamoDB prise en charge. Une valeur de liste DynamoDB est indiquée par :

{ "L" : [ ... ] }

Notez que la valeur est une valeur composée, la liste pouvant contenir zéro ou plus de toutes les valeurs DynamoDB prises en charge (y compris les 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ésentant une collection non ordonnée de paires clé-valeur d'autres valeurs DynamoDB prises en charge. Une valeur de carte 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 les autres cartes). 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 DynamoDB Null 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.

Type de système (mappage des réponses)

Lorsque vous recevez une réponse de DynamoDB, elle la convertitAWS AppSync automatiquement en types primitifs GraphQL et JSON. Chaque attribut de DynamoDB est décodé et renvoyé dans le contexte de mappage des réponses.

Par exemple, si DynamoDB retourne ce qui suit :

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

Ensuite, le résolveurAWS AppSync DynamoDB le convertit en 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 DynamoDB est renvoyée sous la forme d'une chaîne.

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

{ "S" : "some string" }

AWS AppSync le convertit en chaîne :

"some string"
Type d'ensemble de chaîne SS

Ensemble de valeurs de chaîne. Une valeur DynamoDB String Set est renvoyée sous la forme d'une liste de chaînes.

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

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

AWS AppSync le convertit en une liste de chaînes :

[ "+1 555 123 4567", "+1 555 234 5678" ]
Type de nombre N

Valeur numérique unique. Une valeur de numéro DynamoDB est renvoyée sous forme de nombre.

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

{ "N" : 1234 }

AWS AppSync le convertit en un nombre :

1234
Type d'ensemble de nombres NS

Ensemble de valeurs de nombres. Une valeur d'ensemble de numéros DynamoDB est renvoyée sous forme de liste de nombres.

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

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

AWS AppSync le convertit en une liste de nombres :

[ 67.8, 12.2, 70 ]
Type binaire B

Valeur binaire. Une valeur binaire DynamoDB est renvoyée sous forme de chaîne contenant la représentation en base64 de cette valeur.

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

{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

AWS AppSync le convertit en une chaîne contenant la représentation en 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 la forme d'une liste de chaînes contenant la représentation en base64 des valeurs.

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

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

AWS AppSync le convertit en une liste de chaînes contenant la représentation en 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 forme booléenne.

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

{ "BOOL" : true }

AWS AppSync le convertit en booléen :

true
Type de liste L

Liste de toute autre valeur DynamoDB prise en charge. Une valeur de liste DynamoDB est renvoyée sous forme de 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 le convertit en une liste de valeurs converties :

[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
Type de mappage M

Collection clé/valeur de toute autre valeur DynamoDB prise en charge. Une valeur de carte DynamoDB est renvoyée sous forme d'objet JSON, où chaque clé/valeur est également convertie.

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

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

AWS AppSync le 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 DynamoDB Null suivante :

{ "NULL" : null }

AWS AppSync le convertit en valeur nulle :

null

Filtres

Lorsque vous interrogez des objets dans DynamoDB à l'aideScan des opérationsQuery et, vous pouvez éventuellement spécifier unefilter 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 façon d'écrire des expressions de filtre, consultez la ScanFilter documentation de DynamoDB QueryFilter et 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

L'exemple suivant est une section de filtre pour un modèle de mappage, dans laquelle les entrées extraites de DynamoDB ne sont renvoyées que si le titre commence par l'titleargument.

"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érationsPutItemUpdateItem, etDeleteItem DynamoDB, vous pouvez éventuellement spécifier une expression de condition qui contrôle si la demande doit aboutir ou non, en fonction de l'état de l'objet déjà présent dans DynamoDB avant l'exécution de l'opération.

Le résolveurAWS AppSync DynamoDB permet de spécifier une expression de condition dansPutItem et deDeleteItem demander des documents de mappage, ainsi que d'établir une stratégie à suivre si la condition échoue et que l'objet n'a pas été mis à jour.UpdateItem

Exemple 1

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

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

Exemple 2

Le document dePutItem mappage suivant contient une expression de condition qui permet à l'opération de réussir uniquement si aucun élément avec la même clé n'existe dans DynamoDB.

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

Par défaut, si la vérification des conditions échoue, le résolveurAWS AppSync DynamoDB renvoie une erreur concernant la mutation et la valeur actuelle de l'objet dans DynamoDB dans undata champ de laerror section de la réponse GraphQL. Cependant, le résolveurAWS AppSync DynamoDB propose des fonctionnalités supplémentaires pour aider les développeurs à gérer certains cas complexes courants :

  • Si le résolveurAWS AppSync DynamoDB peut déterminer que la valeur actuelle dans DynamoDB correspond au résultat souhaité, il considère l'opération comme si elle avait réussi de toute façon.

  • Au lieu de renvoyer une erreur, vous pouvez configurer le résolveur pour qu'il invoque une fonction Lambda personnalisée afin de décider de la manière dont le résolveurAWS AppSync DynamoDB doit gérer la panne.

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

Pour de plus amples informations sur les expressions de conditions DynamoDB, veuillez consulter la ConditionExpressions documentation DynamoDB.

Spécifier 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 façon d'écrire des expressions de condition, consultez la ConditionExpressions documentation 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é au 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ésolveurAWS 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'PutItemopération, le résolveurAWS AppSync DynamoDB compare l'élément actuellement dans DynamoDB à l'élément qu'il a essayé 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 est unversion attribut, 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 en utilisant une lecture très cohérente. Vous pouvez utiliser ce champ pour indiquer au résolveurAWS AppSync DynamoDB d'utiliser une lecture éventuellement cohérente. Ce champ est facultatif et contient true par défaut.

conditionalCheckFailedHandler

Cette section vous permet de spécifier comment le résolveurAWS AppSync DynamoDB traite un échec de vérification de condition après avoir comparé la valeur actuelle dans DynamoDB au résultat attendu. Cette section est facultative. Si elle n'est pas spécifiée, la valeur par défaut est une stratégie Reject.

strategy

Stratégie adoptée par le résolveurAWS AppSync DynamoDB après avoir comparé la valeur actuelle dans DynamoDB au résultat attendu. Ce champ est obligatoire et les valeurs suivantes sont possibles :

Reject

La mutation échoue, et une erreur concernant la mutation et la valeur actuelle de l'objet dans DynamoDB apparaît dans undata champ de laerror section de la réponse GraphQL.

Custom

Le résolveurAWS AppSync DynamoDB invoque une fonction Lambda personnalisée pour décider comment gérer l'échec du contrôle d'état. Lorsque la strategy est définie sur Custom, le champ lambdaArn doit contenir l'ARN de la fonction Lambda à appeler.

lambdaArn

L'ARN de la fonction Lambda à invoquer qui détermine la manière dont le résolveurAWS AppSync DynamoDB doit gérer l'échec de la vérification de 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 d'un échec de vérification de l'état

Par défaut, lorsqu'une vérification de condition échoue, le résolveurAWS AppSync DynamoDB renvoie une erreur concernant la mutation et la valeur actuelle de l'objet dans DynamoDB dans undata champ de laerror section de la réponse GraphQL. Cependant, le résolveurAWS AppSync DynamoDB propose des fonctionnalités supplémentaires pour aider les développeurs à gérer certains cas complexes courants :

  • Si le résolveurAWS AppSync DynamoDB peut déterminer que la valeur actuelle dans DynamoDB correspond au résultat souhaité, il considère l'opération comme si elle avait réussi de toute façon.

  • Au lieu de renvoyer une erreur, vous pouvez configurer le résolveur pour qu'il invoque une fonction Lambda personnalisée afin de décider comment le résolveurAWS AppSync DynamoDB doit gérer la panne.

Le diagramme de ce processus est le suivant :

Vérification du résultat souhaité

Lorsque la vérification de l'état échoue, le résolveurAWS AppSync DynamoDB exécute une requêteGetItem DynamoDB 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 cettePutItem opération, le résolveurAWS AppSync DynamoDB compare la valeur actuelle à celle qu'il a tenté d'écrire, en excluant les attributs répertoriés dansequalsIgnore la comparaison. Si les éléments sont identiques, l'opération est considérée comme réussie et renvoie l'élément qui a été récupéré depuis 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ésolveurAWS AppSync DynamoDB comparerait l'élément qu'il a essayé d'écrire à la valeur actuelle, vérifierait que la seule différence était leversion champ, mais comme il est configuré pour ignorer leversion champ, il considère l'opération comme réussie et renvoie l'élément extrait DynamoDB.

  • Pour cetteDeleteItem opération, le résolveurAWS AppSync DynamoDB vérifie qu'un élément a été renvoyé par 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'UpdateItemopération, le résolveurAWS AppSync DynamoDB ne dispose pas de suffisamment d'informations pour déterminer si l'élément actuellement présent dans DynamoDB correspond au résultat attendu et suit donc la stratégie configurée.

Si l'état actuel de l'objet dans DynamoDB est différent du résultat attendu, le résolveurAWS AppSync DynamoDB suit la stratégie configurée, soit pour rejeter la mutation, soit pour invoquer une fonction Lambda pour déterminer la marche à suivre.

Suivre la stratégie de « rejet »

Lorsque vous suivez laReject stratégie, le résolveurAWS AppSync DynamoDB renvoie une erreur pour la mutation, et la valeur actuelle de l'objet dans DynamoDB est également renvoyée dans undata champ de laerror section de la réponse GraphQL. L'élément renvoyé par DynamoDB est soumis au modèle de mappage des réponses afin de le traduire dans le format attendu par le client, puis il est filtré en fonction du jeu 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é par 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.

Suivre la stratégie « personnalisée »

Lorsque vous suivez laCustom stratégie, le résolveurAWS AppSync DynamoDB invoque une fonction Lambda pour décider de la marche à suivre. La fonction Lambda choisit l'une des options suivantes :

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

  • discard la mutation. Cela indique au résolveurAWS AppSync DynamoDB d'ignorer silencieusement l'échec de la vérification de l'état et renvoie la valeur dans DynamoDB.

  • retry la mutation. Cela indique au résolveurAWS AppSync DynamoDB de réessayer la mutation avec un nouveau document de mappage de requêtes.

Requête d'appel Lambda

Le résolveurAWS AppSync DynamoDB invoque la fonction Lambda spécifiée dans lelambdaArn. 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 d'invocation et appliquer n'importe quelle logique métier pour décider de la manière dont le résolveurAWS AppSync DynamoDB doit gérer la panne. 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ésolveurAWS AppSync DynamoDB de se comporter comme si la stratégie configurée l'étaitReject, renvoyant une erreur pour la mutation et la valeur actuelle de l'objet dans DynamoDB, comme décrit dans 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ésolveurAWS AppSync DynamoDB d'ignorer silencieusement l'échec de la vérification de l'état et renvoie 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ésolveurAWS AppSync DynamoDB de réessayer la mutation avec un nouveau document de mappage de requêtes. La structure de laretryMapping section dépend de l'opération DynamoDB et constitue un sous-ensemble du document de mappage de requêtes complet pour cette opération.

    Pour PutItem, la section retryMapping a la structure suivante. Pour une description duattributeValues champ, reportez-vous à la section PutItem.

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

    Pour UpdateItem, la section retryMapping a la structure suivante. Pour une description de laupdate section, reportez-vous à la section 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ésolveurAWS 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ésolveurAWS AppSync DynamoDB suit laReject stratégie.

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. Si elle a été faite parjeffTheAdmin, il réessaie la demande en mettant à jour leversion et àexpectedVersion partir de l'élément actuellement présent 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 conditions 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.

PourPutItem, etDeleteItemUpdateItem, l'expression de la condition de transaction est facultative. PourConditionCheck, l'expression de la condition de transaction est requise.

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 deDeleteItem mappage transactionnel suivant contient une expression de condition de transaction qui permet à l'opération de réussir uniquement si l'auteur de cette publication correspond à 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 a fait échouer la vérification de l'état sera renvoyé dans$ctx.result.cancellationReasons.

Spécifier 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 façon d'écrire des expressions de condition, consultez la ConditionExpressions documentation 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é au 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

Spécifiez si vous souhaitez récupérer l'élément dans DynamoDB en cas d'échec de la vérification de l'état. 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 (vrai).