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 de baixo nível da API do DynamoDB em seu nome e processam as respostas do 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.

nota

O DynamoDB Streams tem sua própria API de baixo nível, que é separada da do DynamoDB e é totalmente suportada pelos SDKs. AWS

Para ter mais informações, consulte Capturar dados de alterações para o DynamoDB Streams. Para obter a API de baixo nível do DynamoDB Streams, consulte a Referência da API do Amazon DynamoDB Streams.

A API de baixo nível do DynamoDB JavaScript usa Object Notation (JSON) como formato de protocolo de conexão eletrônica. 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.

nota

Para obter mais informações sobre JSON Introdução ao JSON site JSON.org.

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 itemPets, o AWS SDK cria a seguinte solicitação.

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:

• O cabeçalho Authorization contém as informações necessárias para o DynamoDB autenticar a solicitação. Para obter mais informações, consulte Solicitações de AWS API de assinatura e Processo de assinatura do Signature versão 4 no Referência geral da Amazon Web Services.

• O cabeçalho X-Amz-Target contém o nome de uma operação do DynamoDB: GetItem. (Isso também é acompanhado pela versão da API de baixo nível, neste caso 20120810.)

• A carga útil (corpo) da solicitação contém os parâmetros da operação, no formato JSON. Para a operação GetItem, os parâmetros são TableName e Key.

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

Nesse ponto, o AWS SDK retorna os dados de resposta ao seu aplicativo para processamento adicional.

nota

Se o DynamoDB não puder processar uma solicitação, ele retornará uma mensagem e um código de erro HTTP. O AWS SDK propaga esses elementos em sua aplicação na forma de exceções. Para ter mais informações, consulte Tratamento de erros com o DynamoDB.

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:

• S – String

• N – Number

• B – Binary

• BOOL – Boolean

• NULL – Null

• M – Map

• L – List

• SS – String Set

• NS – Number Set

• BS – Binary Set

nota

Para obter descrições detalhadas dos tipos de dados do DynamoDB, consulte Tipos de dados.

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).