Expressões de condição

Quando objetos sofrem mutação no DynamoDB usando as operações PutItem, UpdateItem e DeleteItem do DynamoDB, opcionalmente, é possível especificar uma expressão de condição que controla se a solicitação deve ser bem-sucedida ou não, com base no estado do objeto que já está no DynamoDB antes que a operação seja realizada.

A função do DynamoDB do AWS AppSync permite que uma expressão de condição seja especificada nos objetos da solicitação PutItem, UpdateItem e DeleteItem, além de uma estratégia para seguir se a condição falhar e o objeto não for atualizado.

Exemplo 1

O objeto de solicitação PutItem a seguir não tem uma expressão de condição. Como resultado, ele coloca um item no DynamoDB mesmo se um item com a mesma chave já existir, sobrescrevendo o item existente.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
  };
}

Exemplo 2

O seguinte objeto PutItem possui uma expressão de condição que permite que a operação seja bem-sucedida somente se um item com a mesma chave não existir no DynamoDB.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
    condition: { expression: "attribute_not_exists(id)" }
  };
}

Por padrão, se a verificação da condição falhar, a função DynamoDB do AWS AppSync fornecerá um erro para a mutação.

No entanto, a função do DynamoDB do AWS AppSync oferece alguns atributos adicionais para ajudar os desenvolvedores a lidar com alguns problemas em parâmetros comuns:

Isso é descrito com mais detalhes na seção Tratamento de uma falha de verificação da condição.

Para obter mais informações sobre as expressões de condições do DynamoDB, consulte a Documentação ConditionExpressions do DynamoDB.

Especificação de uma condição

Os objetos da solicitação PutItem, UpdateItem e DeleteItem permitem que uma seção condition opcional seja especificada. Se omitida, nenhuma verificação de condição é feita. Se especificada, a condição deve ser verdadeira para que a operação seja bem-sucedida.

A seção condition tem a seguinte estrutura:

type ConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
  equalsIgnore?: string[];
  consistentRead?: boolean;
  conditionalCheckFailedHandler?: {
    strategy: 'Custom' | 'Reject';
    lambdaArn?: string;
  };
};

Os campos a seguir especificam a condição:

Os campos restantes informam à função do DynamoDB do AWS AppSync como lidar com uma falha de verificação da condição:

Tratamento de uma falha de verificação da condição

Quando uma verificação de condição falha, a função do DynamoDB do AWS AppSync pode transmitir o erro da mutação e o valor atual do objeto usando o utilitário util.appendError. No entanto, a função do DynamoDB do AWS AppSync oferece alguns atributos adicionais para ajudar os desenvolvedores a lidar com alguns problemas em parâmetros comuns:

O fluxograma para esse processo é:

Verificação do resultado desejado

Quando a verificação de condição falha, a função do DynamoDB do AWS AppSync realiza uma solicitação GetItem do DynamoDB para obter o valor atual do item do DynamoDB. Por padrão, ele usa uma leitura fortemente consistente, mas isso pode ser configurado usando o campo consistentRead no bloco condition e compará-lo com o resultado esperado:

Se o estado atual do objeto no DynamoDB for diferente do resultado esperado, a função do DynamoDB do AWS AppSync seguirá a estratégia configurada, para rejeitar a mutação ou invocar uma função do Lambda a fim de determinar o que fazer a seguir.

Seguir a estratégia "Rejeitar"

Ao seguir a estratégia Reject, a função DynamoDB do AWS AppSync retorna um erro para a mutação.

Por exemplo, considere a solicitação de mutação a seguir:

mutation {
    updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
        Name
        theVersion
    }
}

Se o item retornado do DynamoDB for semelhante ao seguinte:

{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}

E o manipulador de resposta da função tem a seguinte aparência:

import { util } from '@aws-appsync/utils';
export function response(ctx) {
  const { version, ...values } = ctx.result;
  const result = { ...values, theVersion: version };
  if (ctx.error) {
    if (error) {
      return util.appendError(error.message, error.type, result, null);
    }
  }
  return result
}

A resposta do GraphQL é semelhante à seguinte:

{
  "data": null,
  "errors": [
    {
      "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      ...
    }
  ]
}

Além disso, se qualquer campo no objeto retornado for preenchido por outros resolvedores e a mutação foi bem-sucedida, eles não serão resolvidos quando o objeto for retornado na seção error.

Seguir a estratégia "Personalizada"

Ao seguir a estratégia Custom, a função do DynamoDB do AWS AppSync invoca uma função do Lambda para decidir o que fazer a seguir. A Função Lambda escolhe um destas opções a seguir:

A solicitação de invocação do Lambda

A função do DynamoDB do AWS AppSync invoca a função do Lambda especificada no lambdaArn. Ele usa o mesmo service-role-arn configurado na fonte de dados. A carga da invocação tem a seguinte estrutura:

{
    "arguments": { ... },
    "requestMapping": {... },
    "currentValue": { ... },
    "resolver": { ... },
    "identity": { ... }
}

Os campos são definidos da seguinte forma:

Um exemplo completo da carga:

{
    "arguments": {
        "id": "1",
        "name": "Steve",
        "expectedVersion": 1
    },
    "requestMapping": {
        "version" : "2017-02-28",
        "operation" : "PutItem",
        "key" : {
           "id" : { "S" : "1" }
        },
        "attributeValues" : {
           "name" : { "S" : "Steve" },
           "version" : { "N" : 2 }
        },
        "condition" : {
           "expression" : "version = :expectedVersion",
           "expressionValues" : {
               ":expectedVersion" : { "N" : 1 }
           },
           "equalsIgnore": [ "version" ]
        }
    },
    "currentValue": {
        "id" : { "S" : "1" },
        "name" : { "S" : "Steve" },
        "version" : { "N" : 8 }
    },
    "resolver": {
        "tableName": "People",
        "awsRegion": "us-west-2",
        "parentType": "Mutation",
        "field": "updatePerson",
        "outputType": "Person"
    },
    "identity": {
        "accountId": "123456789012",
        "sourceIp": "x.x.x.x",
        "user": "AIDAAAAAAAAAAAAAAAAAA",
        "userArn": "arn:aws:iam::123456789012:user/appsync"
    }
}

A resposta de invocação do Lambda

A função do Lambda pode inspecionar o payload da invocação e aplicar qualquer lógica de negócios para decidir como a função do DynamoDB do AWS AppSync deve tratar a falha. Existem três opções para tratamento da falha de verificação da condição:

Veja aqui um exemplo de função do Lambda para lidar com uma solicitação PutItem com falha. A lógica de negócios analisa quem fez a chamada. Se foi feita pelo jeffTheAdmin, ela tentará novamente a solicitação, atualizando version e expectedVersion do item atualmente no DynamoDB. Caso contrário, ela rejeitará a mutação.

exports.handler = (event, context, callback) => {
    console.log("Event: "+ JSON.stringify(event));

    // Business logic goes here.

    var response;
    if ( event.identity.user == "jeffTheAdmin" ) {
        response = {
            "action" : "retry",
            "retryMapping" : {
                "attributeValues" : event.requestMapping.attributeValues,
                "condition" : {
                    "expression" : event.requestMapping.condition.expression,
                    "expressionValues" : event.requestMapping.condition.expressionValues
                }
            }
        }
        response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
        response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version

    } else {
        response = { "action" : "reject" }
    }

    console.log("Response: "+ JSON.stringify(response))
    callback(null, response)
};