API de baixo nível do DynamoDB

A API de baixo nível do Amazon DynamoDB é a interface de nível de protocolo para DynamoDB. Nesse nível, cada solicitação de HTTP(S) deve ser corretamente formatada e ter uma assinatura digital válida.

Os AWS SDKs criam solicitações da API do DynamoDB de baixo nível em seu nome e processam as respostas no DynamoDB. Isso permite que você se concentre na lógica do seu aplicativo, em vez de detalhes de baixo nível. No entanto, você ainda pode se beneficiar de um conhecimento básico de como a API de baixo nível do DynamoDB funciona.

Para obter mais informações sobre a API de baixo nível do DynamoDB, consulte a Referência da API do Amazon DynamoDB.

A API de baixo nível do DynamoDB usa a JavaScript Object Notation (JSON) como um formato de protocolo de conexão. O JSON apresenta dados em uma hierarquia de forma que os valores e a estrutura dos dados sejam transmitidos simultaneamente. O pares de nome-valor são definidos no formato name:value. A hierarquia de dados é definida por colchetes aninhados de pares de nome-valor.

O DynamoDB usa JSON somente como um protocolo de transporte, não como um formato de armazenamento. Os AWS SDKs usam JSON para enviar dados ao DynamoDB, e o DynamoDB responde com JSON. O DynamoDB não armazena dados persistentemente no formato JSON.

Formato de solicitação

A API de baixo nível do DynamoDB aceita solicitações POST HTTP(S) como entrada. Os AWS SDKs criam essas solicitações para você.

Vamos supor que você tenha uma tabela chamada Pets, com um esquema de chaves que consiste em AnimalType (chave de partição) e Name (chave de classificação). Ambos os atributos são do tipo string. Para recuperar um item de Pets, o AWS SDK cria a solicitação a seguir.

POST / HTTP/1.1
Host: dynamodb.<region>.<domain>;
Accept-Encoding: identity
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
X-Amz-Date: <Date> 
X-Amz-Target: DynamoDB_20120810.GetItem

{
    "TableName": "Pets",
    "Key": {
        "AnimalType": {"S": "Dog"},
        "Name": {"S": "Fido"}
    }
}

Observe o seguinte sobre essa solicitação:

Formato de resposta

Após o recebimento da solicitação, o DynamoDB a processa e retorna uma resposta. Para a solicitação mostrada anteriormente, a carga de resposta HTTP(S) contém os resultados da operação, conforme mostrado no exemplo a seguir.

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
x-amz-crc32: <Checksum>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
    "Item": {
        "Age": {"N": "8"},
        "Colors": {
            "L": [
                {"S": "White"},
                {"S": "Brown"},
                {"S": "Black"}
            ]
        },
        "Name": {"S": "Fido"},
        "Vaccinations": {
            "M": {
                "Rabies": {
                    "L": [
                        {"S": "2009-03-17"},
                        {"S": "2011-09-21"},
                        {"S": "2014-07-08"}
                    ]
                },
                "Distemper": {"S": "2015-10-13"}
            }
        },
        "Breed": {"S": "Beagle"},
        "AnimalType": {"S": "Dog"}
    }
}

Neste momento, o AWS SDK retorna os dados da resposta para sua aplicação para processamento adicional.

Descritores de tipo de dados

O protocolo da API de baixo nível do DynamoDB exige que cada atributo seja acompanhado por um descritor de tipo de dados. Descritores de tipos de dados são tokens que informam ao DynamoDB como interpretar cada atributo.

Os exemplos em Formato de solicitação e Formato de resposta mostram exemplos de como os descritores de tipo de dados são usados. A solicitação GetItem especifica S para os atributos de esquema de chaves de Pets (AnimalType e Name), que são do tipo string. A resposta GetItem contém o item Pets com atributos do tipo string (S), number (N), map (M) e list (L).

Veja a seguir uma lista completa dos descritores de tipos de dados do DynamoDB:

Dados numéricos

As diferentes linguagens de programação oferecem diferentes níveis de suporte para JSON. Em alguns casos, é possível decidir usar uma biblioteca de terceiros para validar e analisar documentos JSON.

Algumas bibliotecas de terceiros se desenvolvem com base no tipo número do JSON, fornecendo seus próprios tipos, como int, long ou double. No entanto, o tipo de dados de número nativo no DynamoDB não é mapeado exatamente nesses outros tipos de dados, portanto, essas distinções de tipo podem causar conflitos. Além disso, muitas bibliotecas do JSON não manipulam valores numéricos de precisão fixa, e elas inferem automaticamente um tipo de dados duplo para sequências de dígitos que contêm um separador decimal.

Para solucionar esses problemas, o DynamoDB fornece um único tipo numérico sem perda de dados. Para evitar conversões implícitas indesejadas para um valor duplo, o DynamoDB usa strings para a transferência de dados de valores numéricos. Essa abordagem fornece flexibilidade para atualizar valores de atributo, sem deixar de manter a semântica de classificação adequada, como colocar os valores "01", "2" e "03" na sequência apropriada.

Se a precisão numérica for importante para sua aplicação, você deverá converter valores numéricos em strings antes de passá-los para o DynamoDB.

Dados binários

O DynamoDB oferece suporte a atributos binários. No entanto, o JSON não é originalmente compatível com a codificação de dados binários. Para enviar dados binários em uma solicitação, será necessário codificá-los em formato base64. Ao receber a solicitação, o DynamoDB decodifica os dados em base64 de volta para binário.

O esquema de codificação base64 usado pelo DynamoDB é descrito na RFC 4648 no site da Internet Engineering Task Force (IETF).