Journal des modifications du modèle de mappage du résolveur - 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.

Journal des modifications du modèle de mappage du résolveur

Les modèles de mappage des résolveurs et des fonctions sont versionnés. La version du modèle de mappage, telle que2018-05-29) dicte ce qui suit : * La forme attendue de la configuration de requête de source de données fournie par le modèle de requête * Le comportement d'exécution du modèle de mappage de requête et du modèle de mappage de réponse

Les versions sont représentés à l'aide du format AAAA/MM/JJ, une date ultérieure correspondant à une version plus récente. Cette page répertorie les différences entre les versions de modèle de mappage actuellement prises en charge dansAWS AppSync.

Disponibilité des opérations de sources de données par matrice de version

Opération/Version prise en charge 2017-02-28 2018-05-29

AWS LambdaInvoquer

Oui

Oui

AWS LambdaBatchInvoke

Oui

Oui

Aucune source de données

Oui

Oui

Amazon OpenSearch GET

Oui

Oui

Amazon OpenSearch POST

Oui

Oui

Amazon OpenSearch PUT

Oui

Oui

Amazon OpenSearch DELETE

Oui

Oui

Amazon OpenSearch GET

Oui

Oui

DynamoDB GetItem

Oui

Oui

DynamoDB Scan

Oui

Oui

DynamoDB Query

Oui

Oui

DynamoDB DeleteItem

Oui

Oui

DynamoDB PutItem

Oui

Oui

DynamoDB BatchGetItem

Non

Oui

DynamoDB BatchPutItem

Non

Oui

DynamoDB BatchDeleteItem

Non

Oui

HTTP

Non

Oui

Amazon RDS

Non

Oui

Remarque : uniquement2018-05-29version est actuellement prise en charge dans les fonctions.

Modification de la version sur un modèle de mappage de résolveur d'unité

Pour les résolveurs d'unité, la version est spécifiée dans le corps du modèle de mappage de la requête. Pour mettre à jour la version, il vous suffit de mettre à jour le champ version avec la nouvelle version.

Par exemple, pour mettre à jour la version sur leAWS Lambdamodèle :

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "arguments": $utils.toJson($context.arguments) } }

Vous devez mettre à jour le champ de version de 2017-02-28 en 2018-05-29 comme suit :

{ "version": "2018-05-29", ## Note the version "operation": "Invoke", "payload": { "field": "getPost", "arguments": $utils.toJson($context.arguments) } }

Modification de la version sur une fonction

Pour les fonctions, la version est spécifiée dans le champ functionVersion sur l'objet de la fonction. Pur mettre à jour la version, il vous suffit de mettre à jour functionVersion. Remarque : Actuellement, seul2018-05-29est pris en charge pour la fonction.

Voici un exemple de commande CLI pour mettre à jour la version d'une fonction existante :

aws appsync update-function \ --api-id REPLACE_WITH_API_ID \ --function-id REPLACE_WITH_FUNCTION_ID \ --data-source-name "PostTable" \ --function-version "2018-05-29" \ --request-mapping-template "{...}" \ --response-mapping-template "\$util.toJson(\$ctx.result)"

Remarque : Il est recommandé d'omettre le champ de version dans le modèle de mappage de requête de la fonction car il ne sera pas respecté. Si vous spécifiez une version dans le modèle de mappage de requête d'une fonction, la valeur de la version sera remplacée par la valeur du champ functionVersion.

2018-05-29

Changement de comportement

  • Si le résultat de l'appel de la source de données est null, le modèle de mappage de réponse est exécuté.

  • Si l'appel de la source de données génère une erreur, c'est à vous de la gérer, le résultat de l'évaluation du modèle de mappage de réponse sera toujours placé dans le bloc de réponse GraphQLdata.

Raisonnement

  • Un résultat d'appel null a une signification, et dans certains cas d'utilisation d'application, il est possible que nous voulions gérer des résultats null de façon personnalisée. Par exemple, une application peut vérifier si un enregistrement existe dans une table Amazon DynamoDB pour réaliser un contrôle d'autorisation. Dans ce cas, un résultat d'appel null signifierait que l'utilisateur n'est probablement pas autorisé. L'exécution du modèle de mappage de réponse offre désormais la possibilité de générer une erreur de non autorisation. Ce comportement procure un meilleur contrôle au concepteur d'API.

Selon le modèle de mappage de réponse suivant :

$util.toJson($ctx.result)

Auparavant avec 2017-02-28, si $ctx.result revenait nul, le modèle de mappage de réponse n'était pas exécuté. Avec 2018-05-29, on peut désormais traiter ce scénario. Par exemple, on peut choisir de générer une erreur d'autorisation comme suit :

# throw an unauthorized error if the result is null #if ( $util.isNull($ctx.result) ) $util.unauthorized() #end $util.toJson($ctx.result)

Remarque : Les erreurs provenant d'une source de données peuvent ne pas être fatales, voire attendues, c'est pourquoi le modèle de mappage de réponse devrait disposer de la possibilité de traiter l'erreur d'appel et de décider de l'ignorer, de la générer de nouveau ou de générer une autre erreur.

Selon le modèle de mappage de réponse suivant :

$util.toJson($ctx.result)

Auparavant, avec 2017-02-28, en cas d'erreur d'appel, le modèle de mappage de réponse était évalué et le résultat était placé automatiquement dans le bloc errors de la réponse GraphQL. Avec 2018-05-29, on peut désormais choisir que faire de l'erreur : la générer de nouveau, générer une erreur différente ou ajouter l'erreur tout en renvoyant des données.

Générer de nouveau une erreur d'appel

Dans le modèle de réponse suivant, on génère la même erreur que celle ayant été renvoyée à partir de la source de données.

#if ( $ctx.error ) $util.error($ctx.error.message, $ctx.error.type) #end $util.toJson($ctx.result)

En cas d'erreur d'invocation (par exemple, présence de $ctx.error) la réponse ressemble à ceci :

{ "data": { "getPost": null }, "errors": [ { "path": [ "getPost" ], "errorType": "DynamoDB:ConditionalCheckFailedException", "message": "Conditional check failed exception...", "locations": [ { "line": 5, "column": 5 } ] } ] }

Générer une autre erreur

Dans le modèle de réponse suivant, on génère notre propre erreur personnalisée après avoir traité l'erreur renvoyée par la source de données.

#if ( $ctx.error ) #if ( $ctx.error.type.equals("ConditionalCheckFailedException") ) ## we choose here to change the type and message of the error for ConditionalCheckFailedExceptions $util.error("Error while updating the post, try again. Error: $ctx.error.message", "UpdateError") #else $util.error($ctx.error.message, $ctx.error.type) #end #end $util.toJson($ctx.result)

En cas d'erreur d'invocation (par exemple, présence de $ctx.error) la réponse ressemble à ceci :

{ "data": { "getPost": null }, "errors": [ { "path": [ "getPost" ], "errorType": "UpdateError", "message": "Error while updating the post, try again. Error: Conditional check failed exception...", "locations": [ { "line": 5, "column": 5 } ] } ] }

Ajouter une erreur à des données renvoyées

Dans le modèle de réponse suivant, on ajoute la même erreur renvoyée depuis la source de données tout en renvoyant des données dans la réponse. Ce processus est également connu sous le nom de réponse partielle.

#if ( $ctx.error ) $util.appendError($ctx.error.message, $ctx.error.type) #set($defaultPost = {id: "1", title: 'default post'}) $util.toJson($defaultPost) #else $util.toJson($ctx.result) #end

En cas d'erreur d'invocation (par exemple, présence de $ctx.error) la réponse ressemble à ceci :

{ "data": { "getPost": { "id": "1", "title: "A post" } }, "errors": [ { "path": [ "getPost" ], "errorType": "ConditionalCheckFailedException", "message": "Conditional check failed exception...", "locations": [ { "line": 5, "column": 5 } ] } ] }

Migration de 2017-02-28 à 2018-05-29

La migration de 2017-02-28 à 2018-05-29 est simple. Modifiez le champ de version sur le modèle de mappage de requête du résolveur ou sur l'objet de la version de la fonction. Cependant, notez que l'exécution de 2018-05-29 est différente de celle de 2017-02-28. Les modifications sont décrites ici.

Préservation du même comportement d'exécution de 2017-02-28 à 2018-05-29

Dans certains cas, il est possible de conserver le même comportement d'exécution que celui de la version 2017-02-28 lorsqu'on exécute le modèle de version 2018-05-29.

Exemple : DynamoDB PutItem

Avec le modèle de requête DynamoDB PutItem 2017-02-28 suivant :

{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... } }

Et le modèle de réponse suivant :

$util.toJson($ctx.result)

La migration vers 2018-05-29 modifie ces modèles comme suit :

{ "version" : "2018-05-29", ## Note the new 2018-05-29 version "operation" : "PutItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... } }

Et modifie le modèle de réponse de la façon suivante :

## If there is a datasource invocation error, we choose to raise the same error ## the field data will be set to null. #if($ctx.error) $util.error($ctx.error.message, $ctx.error.type, $ctx.result) #end ## If the data source invocation is null, we return null. #if($util.isNull($ctx.result)) #return #end $util.toJson($ctx.result)

Il est désormais de votre responsabilité de gérer les erreurs. Nous avons choisi de générer la même erreur en utilisant $util.error(), ayant été renvoyé depuis DynamoDB. Vous pouvez adapter cet extrait pour convertir votre modèle de mappage en 2018-05-29. Notez que si votre modèle de réponse est différent, vous devrez tenir compte des changements de comportement d'exécution.

Exemple : DynamoDB GetItem

Prenons les mesures suivantes :2017-02-28Modèle de demande GetItem DynamoDB :

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

Et le modèle de réponse suivant :

## map table attribute postId to field Post.id $util.qr($ctx.result.put("id", $ctx.result.get("postId"))) $util.toJson($ctx.result)

La migration vers 2018-05-29 modifie ces modèles comme suit :

{ "version" : "2018-05-29", ## Note the new 2018-05-29 version "operation" : "GetItem", "key" : { "foo" : ... typed value, "bar" : ... typed value }, "consistentRead" : true }

Et modifie le modèle de réponse de la façon suivante :

## If there is a datasource invocation error, we choose to raise the same error #if($ctx.error) $util.error($ctx.error.message, $ctx.error.type) #end ## If the data source invocation is null, we return null. #if($util.isNull($ctx.result)) #return #end ## map table attribute postId to field Post.id $util.qr($ctx.result.put("id", $ctx.result.get("postId"))) $util.toJson($ctx.result)

Dans la version 2017-02-28, si l'appel de source de données est null, ce qui signifie qu'aucun élément de la table DynamoDB ne correspond à notre clé, le modèle de mappage de réponse ne s'exécute pas. Cela ne pose aucun problème dans la plupart des cas, mais si vous attendiez que $ctx.result ne soit pas null, vous devez maintenant gérer ce scénario.

2017-02-28

Caractéristiques

  • Si le résultat de l'appel de source de données est null le modèle de mappage de réponse n'est pas exécuté.

  • Si l'appel de la source de données génère une erreur, le modèle de mappage de réponse est exécuté et le résultat évalué est placé dans le bloc errors.data de réponse GraphQL.