API DynamoDB di basso livello

L'API di basso livello di Amazon DynamoDB è l'interfaccia a livello di protocollo per DynamoDB. A questo livello, ogni richiesta HTTP(S) deve essere formattata correttamente e contenere una firma digitale valida.

Gli AWS SDK creano richieste API DynamoDB di basso livello per tuo conto ed elaborano le risposte di DynamoDB. Ciò ti consente di concentrarti sulla logica dell'applicazione, anziché sui dettagli di basso livello. Tuttavia, può essere comunque utile sapere in grandi linee come funziona l'API di livello basso di DynamoDB.

Per ulteriori informazioni sull'API DynamoDB di basso livello, consultaDocumentazione di riferimento dell'API Amazon DynamoDB.

Nota

DynamoDB Streams dispone di una propria API di basso livello, separata da quella di DynamoDB e completamente supportata dagli SDK. AWS

Per ulteriori informazioni, consulta Acquisizione dei dati di modifica per DynamoDB Streams. Per informazioni sull'API DynamoDB Streams di basso livello, consulta la documentazioneRiferimento API Amazon DynamoDB Streams.

L'API DynamoDB di basso livello JavaScript utilizza Object Notation (JSON) come formato di protocollo wire. Con il formato JSON, i dati vengono presentati secondo una gerarchia che consente di trasmettere simultaneamente i valori dei dati e la struttura corrispondente. Le coppie nome-valore sono definite nel formato name:value. La gerarchia dei dati viene definita tramite parentesi annidate di coppie nome-valore.

DynamoDB usa JSON solo come protocollo di trasporto e non come formato di archiviazione. Gli AWS SDK utilizzano JSON per inviare dati a DynamoDB e DynamoDB risponde con JSON. DynamoDB non memorizza i dati in modo persistente in formato JSON.

Nota

Per ulteriori informazioni su JSON, consulta Presentazione di JSON nel sito Web JSON.org.

Formato della richiesta

L'API di basso livello di DynamoDB accetta le richieste HTTP(S) POST come input. Gli SDK AWS costruiscono queste richieste automaticamente.

Supponiamo di avere una tabella denominata Pets con uno schema di chiave costituito da AnimalType (chiave di partizione) e Name (chiave di ordinamento). Entrambi questi attributi sono di tipo string. Per recuperare un elemento da, l'SDK costruisce la seguente Pets richiesta. AWS

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

Tieni presente le seguenti considerazioni sulla richiesta:

• L'intestazione Authorization contiene le informazioni necessarie per l'autenticazione della richiesta da parte di DynamoDB. Per ulteriori informazioni, consulta Signing AWS API request e Signature Version 4 Procedura di firma in. Riferimenti generali di Amazon Web Services

• L'intestazione X-Amz-Target contiene il nome di un'operazione DynamoDB: GetItem. Il nome è accompagnato dalla versione API di basso livello, in questo caso 20120810.

• Il payload (corpo) della richiesta contiene i parametri per l'operazione in formato JSON. Per l'operazione GetItem, i parametri sono TableName e Key.

Formato della risposta

Al ricevimento della richiesta, DynamoDB la elabora e restituisce una risposta. Per la richiesta mostrata in precedenza, il payload della risposta HTTP(S) contiene i risultati dell'operazione, come mostrato nell'esempio seguente:

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

A questo punto, l' AWS SDK restituisce i dati di risposta all'applicazione per un'ulteriore elaborazione.

Nota

Se l'esecuzione della richiesta non riesce, DynamoDB restituisce un codice di errore HTTP e un messaggio di errore. L'SDK AWS propaga la risposta all'applicazione sotto forma di eccezione. Per ulteriori informazioni, consulta Gestione degli errori con DynamoDB.

Descrittori del tipo di dati

Il protocollo API di basso livello di DynamoDB richiede che ogni attributo sia accompagnato da un descrittore del tipo di dati. I descrittori del tipo di dati sono token che indicano a DynamoDB come interpretare ogni attributo.

Gli esempi in Formato della richiesta e Formato della risposta mostrano come vengono usati i descrittori del tipo di dati. La richiesta GetItem specifica S per gli attributi dello schema della chiave Pets (AnimalType e Name) che sono di tipo string. La risposta GetItem contiene un item Pets con attributi di tipo string (S), number (N), map (M) e list (L).

Di seguito è riportato un elenco completo dei descrittori del tipo di dati di DynamoDB:

• S: String

• N: Number

• B: binario

• BOOL: Boolean

• NULL: null

• M: Map

• L: list

• SS: set string

• NS: set numerico

• BS: set binario

Nota

Per una descrizione dettagliata dei tipi di dati di DynamoDB, consulta Tipi di dati.

Dati numerici

I vari linguaggi di programmazione offrono diversi livelli di supporto per JSON. In alcuni casi, potresti decidere di utilizzare una libreria di terze parti per convalidare e analizzare i documenti JSON.

Alcune librerie di terze parti si basano sul tipo di numero JSON, fornendo i propri tipi come int, long o double. Tuttavia, dal momento che il tipo di dati numerico nativo in DynamoDB non viene esattamente mappato a questi altri tipi di dati, pertanto queste distinzioni tra tipi possono causare conflitti. Inoltre, molte librerie JSON non gestiscono valori numerici a precisione fissa e deducono automaticamente un doppio tipo di dati per le sequenze di cifre che contengono una virgola decimale.

Per risolvere questi problemi, DynamoDB fornisce un singolo tipo numerico senza perdita di dati. Per evitare conversioni implicite indesiderate a un valore double, DynamoDB usa le stringhe per il trasferimento dei dati di valori numerici. Questo approccio fornisce flessibilità per l'aggiornamento dei valori degli attributi pur mantenendo una corretta semantica di ordinamento, ad esempio mettendo i valori "01", "2" e "03" nella sequenza corretta.

Se la precisione del numero è importante per l'applicazione, sarà necessario convertire i valori numerici in stringhe prima di passarli a DynamoDB.

Dati binari

supporta gli attributi binari. Tuttavia, JSON non supporta in modo nativo la codifica dei dati binari. Per inviare dati binari in una richiesta, è necessario codificarli nel formato Base64. Dopo aver ricevuto la richiesta, DynamoDB decodifica i dati Base64 nuovamente in binario.

Lo schema di codifica base64 utilizzato da DynamoDB è descritto in RFC 4648 sul sito Web Internet Engineering Task Force (IETF).