TransactWriteItems

El objeto de solicitud TransactWriteItems permite indicar a la función de DynamoDB de AWS AppSync que realice una solicitud TransactWriteItems a DynamoDB para escribir varios elementos, potencialmente en varias tablas. Para este objeto de solicitud, debe especificar lo siguiente:

El nombre de la tabla de destino de cada elemento de solicitud
La operación de cada elemento de solicitud que se va a realizar. Hay cuatro tipos de operaciones compatibles: PutItem, UpdateItem, DeleteItem y ConditionCheck.
La clave de cada elemento de solicitud que se va a escribir

Se aplican los límites de TransactWriteItems de DynamoDB.

El objeto de solicitud TransactWriteItems tiene la siguiente estructura:


type DynamoDBTransactWriteItemsRequest = {
  operation: 'TransactWriteItems';
  transactItems: TransactItem[];
};
type TransactItem =
  | TransactWritePutItem
  | TransactWriteUpdateItem
  | TransactWriteDeleteItem
  | TransactWriteConditionCheckItem;
type TransactWritePutItem = {
  table: string;
  operation: 'PutItem';
  key: { [key: string]: any };
  attributeValues: { [key: string]: string};
  condition?: TransactConditionCheckExpression;
};
type TransactWriteUpdateItem = {
  table: string;
  operation: 'UpdateItem';
  key: { [key: string]: any };
  update: DynamoDBExpression;
  condition?: TransactConditionCheckExpression;
};
type TransactWriteDeleteItem = {
  table: string;
  operation: 'DeleteItem';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactWriteConditionCheckItem = {
  table: string;
  operation: 'ConditionCheck';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
  returnValuesOnConditionCheckFailure: boolean;
};

Campos TransactWriteItems

Los campos se definen de la siguiente manera:

operation

La operación de DynamoDB que se ha de realizar. Para ejecutar la operación de DynamoDB TransactWriteItems, este valor se debe establecer en TransactWriteItems. Este valor es obligatorio.

transactItems

Los elementos de solicitud que se van a incluir. El valor es una matriz de elementos de solicitud. Se debe proporcionar al menos un elemento de solicitud. Este valor transactItems es obligatorio.

Para PutItem, los campos se definen de la siguiente manera:

table: La tabla de DynamoDB de destino. El valor es una cadena con el nombre de la tabla. Este valor table es obligatorio.
operation: La operación de DynamoDB que se ha de realizar. Para ejecutar la operación de DynamoDB PutItem, este valor se debe establecer en PutItem. Este valor es obligatorio.
key: La clave de DynamoDB que representa la clave principal del elemento que se desea colocar. Los elementos de DynamoDB pueden tener solo una clave hash o una clave hash y una clave de clasificación, dependiendo de la estructura de la tabla. Para obtener más información sobre cómo especificar un “valor con tipo”, consulte Sistema de tipos (mapeo de solicitud). Este valor es obligatorio.
attributeValues: El resto de los atributos del elemento que debe colocarse en DynamoDB. Para obtener más información sobre cómo especificar un “valor con tipo”, consulte Sistema de tipos (mapeo de solicitud). Este campo es opcional.
condition: Una condición para determinar si la solicitud debe realizarse correctamente o no, en función del estado del objeto ya incluido en DynamoDB. Si no se especifica ninguna condición, la solicitud PutItem sobrescribe todas las entradas existentes para dicho elemento. Puede especificar si desea recuperar el elemento existente cuando se produzca un error en la comprobación de condiciones. Para obtener más información acerca de las condiciones transaccionales, consulte Expresiones de condición de transacción. Este valor es opcional.

Para UpdateItem, los campos se definen de la siguiente manera:

table: La tabla de DynamoDB que se va a actualizar. El valor es una cadena con el nombre de la tabla. Este valor table es obligatorio.
operation: La operación de DynamoDB que se ha de realizar. Para ejecutar la operación de DynamoDB UpdateItem, este valor se debe establecer en UpdateItem. Este valor es obligatorio.
key: La clave de DynamoDB que representa la clave principal del elemento que se va a actualizar. Los elementos de DynamoDB pueden tener solo una clave hash o una clave hash y una clave de clasificación, dependiendo de la estructura de la tabla. Para obtener más información sobre cómo especificar un “valor con tipo”, consulte Sistema de tipos (mapeo de solicitud). Este valor es obligatorio.
update: La sección update permite especificar una expresión de actualización que describe cómo se actualiza el elemento en DynamoDB. Para obtener más información sobre el modo de escribir expresiones de actualización, consulte la documentación de DynamoDB UpdateExpressions. Esta sección es obligatoria.
condition: Una condición para determinar si la solicitud debe realizarse correctamente o no, en función del estado del objeto ya incluido en DynamoDB. Si no se especifica ninguna condición, la solicitud UpdateItem actualiza todas las entradas existentes independientemente de su estado actual. Puede especificar si desea recuperar el elemento existente cuando se produzca un error en la comprobación de condiciones. Para obtener más información acerca de las condiciones transaccionales, consulte Expresiones de condición de transacción. Este valor es opcional.

Para DeleteItem, los campos se definen de la siguiente manera:

table: La tabla de DynamoDB en la que se elimina el elemento. El valor es una cadena con el nombre de la tabla. Este valor table es obligatorio.
operation: La operación de DynamoDB que se ha de realizar. Para ejecutar la operación de DynamoDB DeleteItem, este valor se debe establecer en DeleteItem. Este valor es obligatorio.
key: La clave de DynamoDB que representa la clave principal del elemento que se desea eliminar. Los elementos de DynamoDB pueden tener solo una clave hash o una clave hash y una clave de clasificación, dependiendo de la estructura de la tabla. Para obtener más información sobre cómo especificar un “valor con tipo”, consulte Sistema de tipos (mapeo de solicitud). Este valor es obligatorio.
condition: Una condición para determinar si la solicitud debe realizarse correctamente o no, en función del estado del objeto ya incluido en DynamoDB. Si no se especifica ninguna condición, la solicitud DeleteItem elimina un elemento independientemente de su estado actual. Puede especificar si desea recuperar el elemento existente cuando se produzca un error en la comprobación de condiciones. Para obtener más información acerca de las condiciones transaccionales, consulte Expresiones de condición de transacción. Este valor es opcional.

Para ConditionCheck, los campos se definen de la siguiente manera:

table: La tabla de DynamoDB en la que se comprueba la condición. El valor es una cadena con el nombre de la tabla. Este valor table es obligatorio.
operation: La operación de DynamoDB que se ha de realizar. Para ejecutar la operación de DynamoDB ConditionCheck, este valor se debe establecer en ConditionCheck. Este valor es obligatorio.
key: La clave de DynamoDB que representa la clave principal del elemento que hay que someter a una comprobación de condición. Los elementos de DynamoDB pueden tener solo una clave hash o una clave hash y una clave de clasificación, dependiendo de la estructura de la tabla. Para obtener más información sobre cómo especificar un “valor con tipo”, consulte Sistema de tipos (mapeo de solicitud). Este valor es obligatorio.
condition: Una condición para determinar si la solicitud debe realizarse correctamente o no, en función del estado del objeto ya incluido en DynamoDB. Puede especificar si desea recuperar el elemento existente cuando se produzca un error en la comprobación de condiciones. Para obtener más información acerca de las condiciones transaccionales, consulte Expresiones de condición de transacción. Este valor es obligatorio.

Cosas que tener en cuenta:

Solo las claves de los elementos de solicitud se devuelven en la respuesta, si se realiza correctamente. El orden de las claves será el mismo que el orden de los elementos de solicitud.
Las transacciones se realizan en régimen de todo o nada. Si algún elemento de solicitud causa un error, no se realizará la transacción completa y se devolverán los detalles del error.
No se pueden dirigir dos elementos de solicitud al mismo elemento. De lo contrario, causarán un error de TransactionCanceledException.
Si el error de una transacción es TransactionCanceledException, se rellenará el bloque cancellationReasons. Si se produce un error en la comprobación de condición de un elemento de solicitud y no se ha especificado que returnValuesOnConditionCheckFailure sea false, el elemento existente en la tabla se recuperará y almacenará en item en la posición correspondiente del bloque cancellationReasons.
TransactWriteItems está limitado a 100 elementos de solicitud.
Esta operación no se admite cuando se utiliza con la detección de conflictos. El uso de ambas al mismo tiempo generará un error.

Para el siguiente controlador de solicitudes de función de ejemplo:


import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId, title, description, oldTitle, authorName } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: 'posts',
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ postId }),
        attributeValues: util.dynamodb.toMapValues({ title, description }),
        condition: util.transform.toDynamoDBConditionExpression({
          title: { eq: oldTitle },
        }),
      },
      {
        table: 'authors',
        operation: 'UpdateItem',
        key: util.dynamodb.toMapValues({ authorId }),
        update: {
          expression: 'SET authorName = :name',
          expressionValues: util.dynamodb.toMapValues({ ':name': authorName }),
        },
      },
    ],
  };
}

Si la transacción se realiza correctamente, el resultado de la invocación disponible en ctx.result es el siguiente:


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

Si la transacción no se realiza correctamente debido a un error de comprobación de condición de la solicitud PutItem, el resultado de la invocación disponible en ctx.result es el siguiente:


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

El ctx.error contiene detalles acerca del error. Los valores de keys y cancellationReasons estarán presentes sin duda en ctx.result.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

TransactGetItems

Sistema de tipos (mapeo de solicitud)