TransactWriteItems - AWS AppSync
Campos TransactWriteItems

TransactWriteItems

O documento de mapeamento de solicitação TransactWriteItems permite que você oriente o resolvedor do DynamoDB do AWS AppSync a fazer uma solicitação TransactWriteItems ao DynamoDB para gravar vários itens, potencialmente em diversas tabelas. Para esse modelo 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 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 documento de mapeamento TransactWriteItems possui a seguinte estrutura:

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "table1",
           "operation": "PutItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "attributeValues": {
               "baz": ... typed value
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table":"table2",
           "operation": "UpdateItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "update": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               }
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo":"foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table3",
           "operation": "DeleteItem",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table4",
           "operation": "ConditionCheck",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       }
    ]
}

Campos TransactWriteItems

Os campos são definidos da seguinte forma:
version

A versão de definição do modelo. Somente 2018-05-29 é suportado. Este valor é obrigatório.

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 gravar expressões de atualização, consulte a documentação UpdateExpressions do 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 executadas na sua totalidade ou não são realizadas. 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 erro TransactionCanceledException .

  • Se o erro de uma transação for TransactionCanceledException, o bloco cancellationReasons 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.

Para o seguinte exemplo do modelo de mapeamento de solicitação:

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "posts",
           "operation": "PutItem",
           "key": {
               "post_id": {
                   "S": "p1"
               }
           },
           "attributeValues": {
               "post_title": {
                   "S": "New title"
               },
               "post_description": {
                   "S": "New description"
               }
           },
           "condition": {
               "expression": "post_title = :post_title",
               "expressionValues": {
                   ":post_title": {
                       "S": "Expected old title"
                   }
               }
           }
       },
       {
           "table":"authors",
           "operation": "UpdateItem",
           "key": {
               "author_id": {
                   "S": "a1"
               },
           },
           "update": {
               "expression": "SET author_name = :author_name",
               "expressionValues": {
                   ":author_name": {
                       "S": "New name"
                   }
               }
           },
       }
    ]
}

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

O $ctx.error contém detalhes sobre o erro. A presença de chaves e cancelationReasons está garantida em $ctx.result.

Para obter um exemplo mais completo, siga o tutorial de transação do DynamoDB com o AppSync aqui Tutorial: Resolvedores de transação do DynamoDB.