Registro de cambios de plantillas de mapeo de solucionador - AWS AppSync
Disponibilidad de operación de un origen de datos por matriz de la versiónCambio de la versión en una plantilla de mapeo de solucionador de unidadCambio de la versión en una función2018-05-292017-02-28

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Registro de cambios de plantillas de mapeo de solucionador

nota

Ahora admitimos de forma básica el tiempo de ejecución APPSYNC_JS y su documentación. Considere la opción de utilizar el tiempo de ejecución APPSYNC_JS y sus guías aquí.

El solucionador y las plantillas de mapeo de función tienen varias versiones. La versión de la plantilla de mapeo (por ejemplo, 2018-05-29) establece lo siguiente: *La forma esperada de la configuración de solicitud de origen de datos proporcionada por la plantilla de solicitud. *El comportamiento de ejecución de la plantilla de mapeo de solicitud y la plantilla de asignación de respuesta.

Las versiones se representan con el formato AAAA-MM-DD, una fecha posterior corresponde a una versión más reciente. En esta página se muestran las diferencias entre las versiones de la plantilla de mapeo admitidas actualmente en AWS AppSync.

Disponibilidad de operación de un origen de datos por matriz de la versión

Operación/versión admitida 2017-02-28 2018-05-29

AWS Lambda Invoke

Sí

Sí

AWS Lambda BatchInvoke

Sí

Sí

None Datasource

Sí

Sí

Amazon OpenSearch GET

Sí

Sí

Amazon OpenSearch POST

Sí

Sí

Amazon OpenSearch PUT

Sí

Sí

Amazon OpenSearch DELETE

Sí

Sí

Amazon OpenSearch GET

Sí

Sí

DynamoDB GetItem

Sí

Sí

DynamoDB Scan

Sí

Sí

DynamoDB Query

Sí

Sí

DynamoDB DeleteItem

Sí

Sí

DynamoDB PutItem

Sí

Sí

DynamoDB BatchGetItem

No

Sí

DynamoDB BatchPutItem

No

Sí

DynamoDB BatchDeleteItem

No

Sí

HTTP

No

Sí

Amazon RDS

No

Sí

Nota: Solo la versión 2018-05-29 es compatible actualmente en las funciones.

Cambio de la versión en una plantilla de mapeo de solucionador de unidad

Para los solucionadores de unidad, la versión se especifica como parte del cuerpo de la plantilla de mapeo de solicitud. Para actualizar la versión, solo tiene que actualizar el campo version a la nueva versión.

Por ejemplo, para actualizar la versión en la plantilla de AWS Lambda:

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

Debe actualizar el campo de versión de 2017-02-28 a 2018-05-29, tal y como se indica a continuación:

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

Cambio de la versión en una función

Para funciones, la versión se especifica como el campo functionVersion en el objeto de función. Para actualizar la versión, basta con actualizar functionVersion. Nota: Actualmente, solo 2018-05-29 es compatible con las funciones.

Lo siguiente es un ejemplo de comando CLI para actualizar una versión de función existente:

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

Nota: Se recomienda omitir el campo de la versión de la plantilla de mapeo de solicitudes de función, ya que no será atendido. Si especifica una versión dentro de una plantilla de mapeo de solicitudes de función, el valor de la versión se anulará por el valor del campo functionVersion.

2018-05-29

Cambio de comportamiento

  • Si el resultado de la invocación del origen de datos es null, la plantilla de mapeo de respuesta se ejecuta.

  • Si la invocación de origen de datos genera un error, le corresponde a usted gestionar el error, el resultado evaluado de la plantilla de mapeo de respuesta siempre se colocará dentro del bloque data de la respuesta GraphQL.

Razonamiento

  • Un resultado de invocación null tiene un significado y en algunos casos de uso de aplicaciones es posible que desee gestionar los resultados null de un modo personalizado. Por ejemplo, una aplicación podría comprobar si existe un registro en una tabla de Amazon DynamoDB para realizar alguna comprobación de autorización. En este caso, un resultado de invocación null supondría que el usuario podría no estar autorizado. Ejecutar la plantilla de mapeo de respuesta ahora ofrece la posibilidad de generar un error no autorizado. Este comportamiento proporciona un mayor control al diseñador de la API.

En el caso de la siguiente plantilla de mapeo de respuesta:

$util.toJson($ctx.result)

Anteriormente con 2017-02-28, si $ctx.result volvía nulo, la plantilla de mapeo de respuesta no se ejecutaba. Con 2018-05-29, ya podemos gestionar este escenario. Por ejemplo, podemos optar por generar un error de autorización tal como se indica a continuación:

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

Nota: Los errores que vuelven de un origen de datos en ocasiones no son graves o incluso previstos, por eso a la plantilla de mapeo de respuesta se le debe dar la flexibilidad de gestionar el error de invocación y decidir si pasarlo por alto, volver a generarlo o generar un error diferente.

En el caso de la siguiente plantilla de mapeo de respuesta:

$util.toJson($ctx.result)

Anteriormente, con 2017-02-28, en caso de que se produzca un error de invocación, la plantilla de mapeo de respuesta se evaluaba y el resultado se colocaba automáticamente en el bloque errors de la respuesta GraphQL. Con 2018-05-29, ya podemos elegir qué hacer con el error, volver a generarlo, generar otro error o añadir el error al devolver los datos.

Volver a generar un error de invocación

En la siguiente plantilla de respuesta, generamos el mismo error que volvió del origen de datos.

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

En caso de un error de invocación (por ejemplo, si $ctx.error está presente), la respuesta es como la del siguiente ejemplo:

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

Generar un error diferente

En la siguiente plantilla de respuesta, generamos nuestro propio error personalizado después de procesar error que volvió del origen de datos.

#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 caso de un error de invocación (por ejemplo, si $ctx.error está presente), la respuesta es como la del siguiente ejemplo:

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

Añadir un error a los datos de retorno

En la siguiente plantilla de respuesta, añadimos el mismo error que volvió del origen de datos al devolver los datos dentro de la respuesta. Esto también se conoce como una respuesta parcial.

#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 caso de un error de invocación (por ejemplo, si $ctx.error está presente), la respuesta es como la del siguiente ejemplo:

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

Migración de 2017-02-28 a 2018-05-29

La migración de 2017-02-28 a 2018-05-29 es sencilla. Cambie el campo de versión en la plantilla de mapeo de solicitudes de solucionador o en el objeto de la versión de función. No obstante, tenga en cuenta que la ejecución de 2018-05-29 tiene un comportamiento diferente al de 2017-02-28; los cambios se describen aquí.

Mantener el mismo comportamiento de ejecución de 2017-02-28 en 2018-05-29

En algunos casos, es posible mantener el mismo comportamiento de ejecución que en la versión 2017-02-28 al ejecutar una plantilla con la versión 2018-05-29.

Ejemplo: DynamoDB PutItem

Con la siguiente plantilla de solicitud DynamoDB PutItem 2017-02-28:

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

Y la siguiente plantilla de respuesta:

$util.toJson($ctx.result)

La migración a 2018-05-29 estas plantillas tal y como se indica a continuación:

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

Y cambia la plantilla de respuesta tal y como se indica a continuación:

## 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)

Ahora que es su responsabilidad gestionar errores, optamos por generar el mismo error utilizando $util.error() que se obtuvo de DynamoDB. Puede adaptar este fragmento de código para convertir su plantilla de mapeo a 2018-05-29; tenga en cuenta que si su plantilla de respuesta es diferente tendrá que tener en cuenta los cambios del comportamiento de ejecución.

Ejemplo: DynamoDB GetItem

Con la siguiente plantilla de solicitud de DynamoDB GetItem 2017-02-28:

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

Y la siguiente plantilla de respuesta:

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

$util.toJson($ctx.result)

La migración a 2018-05-29 estas plantillas tal y como se indica a continuación:

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

Y cambia la plantilla de respuesta tal y como se indica a continuación:

## 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)

En la versión 2017-02-28, si la invocación del origen de datos fuera null, lo que significa que no hay ningún elemento en la tabla de DynamoDB que coincida con la clave, la plantilla de mapeo de respuesta no se ejecutaría. Podría estar bien para la mayoría de los casos, pero si espera que $ctx.result no sea null, ahora tiene que gestionar dicho escenario.

2017-02-28

Características

  • Si el resultado de la invocación del origen de datos es null, la plantilla de mapeo de respuesta no se ejecuta.

  • Si la invocación de origen de datos genera un error, se ejecuta la plantilla de mapeo de respuesta y el resultado evaluado se coloca dentro del bloque errors.data de la respuesta GraphQL.