Journal des modifications du modèle de mappage Resolver

Note

Nous prenons désormais principalement en charge le runtime APPSYNC_JS et sa documentation. Pensez à utiliser le runtime APPSYNC_JS et ses guides ici.

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 demande de source de données fournie par le modèle de demande * Le comportement d'exécution du modèle de mappage de demande 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èles 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 Lambda BatchInvoke	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 SUPPRIMER	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 : Seule la version 2018-05-29 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 du AWS Lambda modè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, seul 2018-05-29 est 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

Compte tenu du modèle de demande DynamoDB 2017-02-28 suivant : PutItem

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

Compte tenu du modèle de demande DynamoDB 2017-02-28 suivant : GetItem

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