API de bajo nivel de DynamoDB

La API de bajo nivel de Amazon DynamoDB es la interfaz de nivel de protocolo de DynamoDB. En este nivel, cada solicitud HTTP(S) debe tener el formato correcto y llevar una firma digital válida.

Los SDK de AWS construyen las solicitudes a la API de bajo nivel de DynamoDB automáticamente y procesan las respuestas de DynamoDB. Esto le permite centrarse en la lógica de la aplicación, en lugar de en los detalles de bajo nivel. Sin embargo, le resultará útil conocer algunos conceptos básicos del funcionamiento de la API de bajo nivel de DynamoDB.

Para obtener más información sobre la API de DynamoDB de bajo nivel, consulteReferencia de la API de Amazon DynamoDB.

nota

DynamoDB Streams tiene su propio API de bajo nivel, que es independiente de la de DynamoDB y totalmente compatible con los SDK de AWS.

Para obtener más información, consulte Captura de datos de cambios para DynamoDB Streams. Para la API de DynamoDB Streams de bajo nivel, consulte la. Referencia de la API de Amazon DynamoDB Streams.

La API de bajo nivel de DynamoDB utiliza la notación de objetos de JavaScript (JSON, JavaScript Object Notation) como formato de protocolo de conexión. JSON presenta los datos de forma jerárquica para transmitir simultáneamente sus valores y su estructura. Los pares de nombre-valor se definen con el formato name:value. La jerarquía de datos se define mediante llaves anidadas de pares de nombre-valor.

DynamoDB usa JSON como protocolo de transporte únicamente, no como formato de almacenamiento. Los SDK de AWS usan JSON para enviar datos a DynamoDB y DynamoDB responde con JSON. DynamoDB no almacena datos de forma persistente en formato JSON.

nota

Para obtener más información acerca de JSON, consulte Introducing JSON en el sitio web JSON.org.

Formato de solicitudes

La API de bajo nivel de DynamoDB acepta solicitudes POST de HTTP(S) como información de entrada. Los SDK de AWS construyen estas solicitudes automáticamente.

Supongamos que dispone de una tabla denominada Pets, con un esquema de claves que consta de AnimalType (clave de partición) y Name (clave de ordenación). Ambos atributos son de tipo string. Para recuperar un elemento de Pets, el SDK de AWS construye la siguiente solicitud.

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

Tenga en cuenta lo siguiente en relación con esta solicitud:

• El encabezado Authorization contiene la información necesaria para que DynamoDB autentique la solicitud. Para obtener más información, consulte Firma de solicitudes de API AWS y Proceso de firma de Signature Version 4 en la Referencia general de Amazon Web Services.

• El encabezado X-Amz-Target contiene el nombre de una operación de DynamoDB, GetItem. Además, va acompañada de la versión del API de bajo nivel, en este caso, 20120810.

• La carga (cuerpo) de la solicitud contiene los parámetros de la operación, en formato JSON. En la operación GetItem, los parámetros son TableName y Key.

Formato de respuesta

Una vez que recibe la solicitud, DynamoDB la procesa y devuelve una respuesta. Para la solicitud mostrada anteriormente, la carga de la respuesta HTTP(S) contiene los resultados de la operación, como se muestra en el siguiente ejemplo.

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

En este momento, el SDK de AWS devuelve los datos de respuesta a la aplicación para continuar procesándolos.

nota

Si DynamoDB no puede procesar una solicitud, devuelve un código de error HTTP y un mensaje. El SDK de AWS los propaga a su aplicación, en forma de excepciones. Para obtener más información, consulte Control de errores con DynamoDB.

Descriptores de tipos de datos

El protocolo de la API de bajo nivel de DynamoDB requiere que cada atributo vaya acompañado de un descriptor del tipo de datos. Los descriptores de tipos de datos son tokens que indican a DynamoDB cómo interpretar cada atributo.

En las secciones Formato de solicitudes y Formato de respuesta encontrará ejemplos de cómo se usan los descriptores de tipos de datos. En la solicitud GetItem se especifica S para los atributos del esquema de claves de Pets (AnimalType y Name), que son de tipo string. La respuesta GetItem contiene un elemento Pets con atributos de tipo string (S), number (N), map (M) y list (L).

A continuación se muestra una lista completa de descriptores de tipos de datos de 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 obtener descripciones detalladas de los tipos de datos de DynamoDB, consulte Tipos de datos.

Datos numéricos

Los distintos lenguajes de programación ofrecen diferentes niveles de compatibilidad con JSON. En algunos casos, es posible que prefiera usar una biblioteca de terceros para validar y analizar los documentos JSON.

Algunas bibliotecas de terceros se basan en el tipo Number de JSON y proporcionan sus propios tipos, tales como int, long o double. Sin embargo, el tipo de datos Number nativo de DynamoDB no se mapea exactamente a estos otros tipos de datos, por lo que estas diferencias entre los tipos pueden provocar conflictos. Además, muchas bibliotecas JSON no controlan los valores numéricos con una precisión fija y deducen automáticamente que el tipo de datos de las secuencias que contienen una coma decimal es double.

Para resolver estos problemas, DynamoDB proporciona un único tipo numérico sin pérdida de datos. Para evitar conversiones implícitas no deseadas a un valor de tipo double, DynamoDB utiliza cadenas para efectuar la transferencia de datos de valores numéricos. Este enfoque proporciona flexibilidad para actualizar los valores de los atributos y, al mismo tiempo, mantener una semántica de ordenación adecuada; por ejemplo, colocar los valores "01", "2" y "03" en la secuencia correcta.

Si la precisión del número es importante para la aplicación, debe convertir los valores numéricos en cadenas antes de pasárselos a DynamoDB.

Datos binarios

DynamoDB es compatible con los atributos binarios. Sin embargo, JSON no presenta compatibilidad nativa con la codificación de datos binarios. Para enviar datos binarios en una solicitud, es preciso codificarlos en formato base64. Al recibir la solicitud, DynamoDB decodifica los datos base64 para que vuelvan a ser binarios.

El esquema de codificación base64 que se utiliza en DynamoDB se describe en RFC 4648 en el sitio web de IETF (Internet Engineering Task Force).