TransactWriteItems

Modo de foco

TransactWriteItems - AWS AppSync GraphQL

O objeto de TransactWriteItems solicitação permite que você peça à função do AWS AppSync DynamoDB que faça uma TransactWriteItems solicitação ao DynamoDB para gravar vários itens, potencialmente em várias tabelas. Para esse objeto de solicitação, você deve especificar o seguinte:

O nome da tabela de destino de cada item de solicitação
A operação de cada item de solicitação a ser executado. Há quatro tipos de operações que são compatíveis: PutItem, UpdateItem, DeleteItem, e ConditionCheck
A chave de cada item de solicitação a ser gravado

Os limites TransactWriteItems do DynamoDB são aplicáveis.

O objeto de solicitação TransactWriteItems tem a seguinte estrutura:


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;
};

TransactWriteItems campos

Os campos são definidos da seguinte forma:

operation

A operação do DynamoDB para execução. Para executar a operação TransactWriteItems do DynamoDB, ela deve ser definida como TransactWriteItems. Este valor é obrigatório.

transactItems

Os itens de solicitação a serem incluídos. O valor é uma matriz de itens de solicitação. Pelo menos um item de solicitação deve ser fornecido. Este valor transactItems é obrigatório.

Em PutItem, os campos são definidos da seguinte forma:

table: A tabela de destino do DynamoDB. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação PutItem do DynamoDB, ela deve ser definida como PutItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser inserida. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
attributeValues: O restante dos atributos do item a ser colocado no DynamoDB. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Esse campo é opcional.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, uma solicitação PutItem substitui qualquer entrada existente para esse item. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em UpdateItem, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB a ser atualizada. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação UpdateItem do DynamoDB, ela deve ser definida como UpdateItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser atualizada. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
update: A seção update permite especificar uma expressão de atualização que descreve como atualizar o item no DynamoDB. Para obter mais informações sobre como escrever expressões de atualização, consulte a documentação do UpdateExpressions DynamoDB. Esta seção é obrigatória.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, a solicitação UpdateItem atualizará as entradas existentes independentemente do estado atual. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em DeleteItem, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB na qual excluir o item. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação DeleteItem do DynamoDB, ela deve ser definida como DeleteItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser excluída. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, a solicitação DeleteItem excluirá um item independentemente do estado atual. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em ConditionCheck, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB na qual verificar a condição. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação ConditionCheck do DynamoDB, ela deve ser definida como ConditionCheck. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item para verificar a condição. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é obrigatório.

TransactWriteItems lista de campos

Os campos são definidos da seguinte forma:

operation

A operação do DynamoDB para execução. Para executar a operação TransactWriteItems do DynamoDB, ela deve ser definida como TransactWriteItems. Este valor é obrigatório.

transactItems

Os itens de solicitação a serem incluídos. O valor é uma matriz de itens de solicitação. Pelo menos um item de solicitação deve ser fornecido. Este valor transactItems é obrigatório.

Em PutItem, os campos são definidos da seguinte forma:

table: A tabela de destino do DynamoDB. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação PutItem do DynamoDB, ela deve ser definida como PutItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser inserida. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
attributeValues: O restante dos atributos do item a ser colocado no DynamoDB. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Esse campo é opcional.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, uma solicitação PutItem substitui qualquer entrada existente para esse item. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em UpdateItem, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB a ser atualizada. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação UpdateItem do DynamoDB, ela deve ser definida como UpdateItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser atualizada. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
update: A seção update permite especificar uma expressão de atualização que descreve como atualizar o item no DynamoDB. Para obter mais informações sobre como escrever expressões de atualização, consulte a documentação do UpdateExpressions DynamoDB. Esta seção é obrigatória.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, a solicitação UpdateItem atualizará as entradas existentes independentemente do estado atual. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em DeleteItem, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB na qual excluir o item. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação DeleteItem do DynamoDB, ela deve ser definida como DeleteItem. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item a ser excluída. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Se nenhuma condição for especificada, a solicitação DeleteItem excluirá um item independentemente do estado atual. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é opcional.

Em ConditionCheck, os campos são definidos da seguinte forma:

table: A tabela do DynamoDB na qual verificar a condição. O valor é uma string do nome da tabela. Este valor table é obrigatório.
operation: A operação do DynamoDB para execução. Para executar a operação ConditionCheck do DynamoDB, ela deve ser definida como ConditionCheck. Este valor é obrigatório.
key: A chave do DynamoDB representando a chave primária do item para verificar a condição. Os itens do DynamoDB podem ter uma única chave de hash ou uma chave de hash e uma chave de classificação, dependendo da estrutura da tabela. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório.
condition: Uma condição para determinar se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB. Você pode especificar se deseja recuperar o item existente quando a verificação de condição falhar. Para obter mais informações sobre as condições transacionais, consulte Expressões de condição da transação. Este valor é obrigatório.

Informações importantes:

Somente chaves de itens de solicitação são retornadas na resposta, se bem-sucedidas. A ordem das chaves será a mesma que a ordem dos itens solicitados.
As transações são realizadas de all-or-nothing alguma forma. Se algum item de solicitação causar um erro, não será executada a transação inteira e os detalhes do erro serão retornados.
Dois itens de solicitação não podem segmentar o mesmo item. Caso contrário, eles causarão TransactionCanceledExceptionerros.
Se o erro de uma transação for TransactionCanceledException, o cancellationReasons bloco será preenchido. Se a verificação de condição de um item de solicitação falhar e você não especificar returnValuesOnConditionCheckFailure como false, o item existente na tabela será recuperado e armazenado em item na posição correspondente do bloco cancellationReasons.
TransactWriteItems está limitado a 100 itens de solicitação.
Essa operação não é compatível quando usada com detecção de conflitos. Usar ambos ao mesmo tempo pode gerar um erro.

Veja a seguir um exemplo de manipulador de solicitação de função:


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 }),
        },
      },
    ],
  };
}

Se a transação for bem-sucedida, o resultado de invocação disponível em ctx.result será o seguinte:


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

Se a transação falhar devido a falha de verificação de condição da solicitação PutItem, o resultado de invocação disponível em ctx.result será o seguinte:


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