Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Formati di input Amazon S3 per articoli messi in blocco

DynamoDB bulk put items legge i dati di input da Amazon S3 in due formati: DynamoDB JSON e Amazon Ion. Puoi fornire un singolo oggetto Amazon S3 o più oggetti nello stesso Prefisso chiave Amazon S3.

Ogni file di input può contenere facoltativamente espressioni di condizione per elemento che controllano se gli elementi vengono scritti nella tabella. Le sezioni seguenti descrivono i formati supportati, le opzioni di compressione e il modello di espressione delle condizioni.

Formati e compressione supportati

Specifica il formato di input quando chiami StartBulkPutItems impostando InputFormat campo in Configurazione degli ingressi 3, il parametro di richiesta che descrive dove è archiviato l'input in Amazon S3 e come è formattato. Per tutti i parametri della richiesta, consulta Avvio di un'operazione di inserimento in blocco degli elementi.

Imposta il InputCompressionType campo per indicare come vengono compressi i tuoi oggetti Amazon S3.

DynamoDB JSON

Un file in formato JSON DynamoDB è costituito da un oggetto JSON per riga (Linee JSON formato). Ogni riga contiene un Item campo in JSON marshalled di DynamoDB e campi di condizione opzionali. Non utilizzare le nuove righe all'interno di un singolo record. Per informazioni sul funzionamento dei campi relativi alle condizioni, consulta Per-item espressioni di condizione.

Put incondizionato (comportamento predefinito)

Quando si omettono i campi delle condizioni, ogni elemento sovrascrive qualsiasi elemento esistente con la stessa chiave primaria:

{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}}}
{"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}}}
{"Item":{"id":{"S":"item-3"},"name":{"S":"Widget C"},"price":{"N":"4.99"}}}

Condizione semplice: solo inserimento

Inserisci attribute_not_exists(pk) per evitare sovrascritture. Sostituisci pk con il nome dell'attributo della chiave di partizione:

{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}},"ConditionExpression":"attribute_not_exists(id)"}
{"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}},"ConditionExpression":"attribute_not_exists(id)"}

Espressione denominata con token di sostituzione

Usa ExpressionAttributeNames e ExpressionAttributeValues quando la condizione fa riferimento a parole riservate o sostituisce i valori degli attributi:

{"Item":{"id":{"S":"item-2"},"status":{"S":"ACTIVE"},"version":{"N":"3"}},"ConditionExpression":"#s = :v","ExpressionAttributeNames":{"#s":"status"},"ExpressionAttributeValues":{":v":{"S":"ACTIVE"}}}
{"Item":{"id":{"S":"item-5"},"status":{"S":"PENDING"},"version":{"N":"2"}},"ConditionExpression":"#ver < :newver","ExpressionAttributeNames":{"#ver":"version"},"ExpressionAttributeValues":{":newver":{"N":"2"}}}

Nel primo record, l'elemento viene scritto solo se l'elemento esistente status l'attributo è uguale ACTIVE. Nel secondo record, l'elemento viene scritto solo se l'elemento esistente version è inferiore a 2.

Condizioni miste in un unico file

Record diversi nello stesso file possono presentare condizioni diverse o nessuna condizione:

{"Item":{"id":{"S":"new-1"},"data":{"S":"hello"}},"ConditionExpression":"attribute_not_exists(id)"}
{"Item":{"id":{"S":"existing-1"},"data":{"S":"updated"}},"ConditionExpression":"#v = :expected","ExpressionAttributeNames":{"#v":"version"},"ExpressionAttributeValues":{":expected":{"N":"5"}}}
{"Item":{"id":{"S":"overwrite-1"},"data":{"S":"replaced"}}}

In questo esempio, il primo record utilizza una semantica di solo inserimento. Il secondo record utilizza una protezione della versione. Il terzo record viene sovrascritto incondizionatamente perché non presenta alcuna condizione.

Amazon Ion

Amazon Ion è un formato di serializzazione dei dati gerarchico, altamente tipizzato e autodescrittivo. Quando si utilizza il formato Ion per gli elementi messi in blocco, i tipi di dati Ion vengono mappati ai tipi di dati DynamoDB nella tabella di destinazione.

Ogni record è una struttura Ion contenente un Item campo e campi condizionali opzionali, delimitati da nuove righe. Ogni riga inizia con un indicatore di versione Ion.

Put incondizionato

$ion_1_0
{
  Item:{
    id:"order-001",
    amount:99.95,
    status:"PENDING"
  }
}
$ion_1_0
{
  Item:{
    id:"order-002",
    amount:149.00,
    status:"SHIPPED"
  }
}

Con espressione di condizione per elemento

$ion_1_0
{
  Item:{
    id:"order-001",
    amount:99.95,
    status:"PENDING"
  },
  ConditionExpression:"attribute_not_exists(id)"
}
$ion_1_0
{
  Item:{
    id:"order-002",
    amount:149.00,
    status:"SHIPPED"
  },
  ConditionExpression:"#s = :v",
  ExpressionAttributeNames:{"#s":"status"},
  ExpressionAttributeValues:{":v":"ACTIVE"}
}

La tabella seguente mostra come i tipi di dati Ion vengono mappati ai tipi di dati DynamoDB.

Layout dei dati di origine in Amazon S3

Puoi fornire il tuo input come singolo oggetto Amazon S3 o come più oggetti archiviati con lo stesso prefisso di chiave S3. Quando imposti S3KeyPrefix campo in InputS3Configuration, DynamoDB legge tutti gli oggetti con quel prefisso chiave S3. Per indicazioni su come suddividere l'input, consulta Le migliori pratiche per la messa in blocco di articoli in DynamoDB.

Per-item espressioni di condizione

Le espressioni di condizione per gli articoli messi in blocco sono specificate per articolo, all'interno del file di input. Usano la stessa sintassi delle espressioni di condizione per PutItem operazione. Per la sintassi completa, vedere Esempio di CLI di espressione condizionale in DynamoDB. Per gli operatori e le funzioni supportati, vedere Espressioni, operatori e funzioni di condizione e di filtro in DynamoDB.

Ogni record nel file di input contiene i seguenti campi:

Comportamento di valutazione delle condizioni

La tabella seguente descrive come DynamoDB valuta le espressioni delle condizioni durante un'operazione di inserimento in blocco di elementi.

Per ottenere una semantica che preveda solo l'inserimento di nuovi elementi

Poiché le condizioni sono per elemento, è necessario includere un ConditionExpression su ogni record se desideri un comportamento put-if-not-exists nell'intero file. L'esempio seguente mostra un file di input JSON di DynamoDB in cui ogni record contiene attribute_not_exists(id) per evitare le sovrascritture:

{"Item":{"id":{"S":"order-001"},"amount":{"N":"99.95"},"status":{"S":"PENDING"}},"ConditionExpression":"attribute_not_exists(id)"}
{"Item":{"id":{"S":"order-002"},"amount":{"N":"149.00"},"status":{"S":"SHIPPED"}},"ConditionExpression":"attribute_not_exists(id)"}
{"Item":{"id":{"S":"order-003"},"amount":{"N":"25.50"},"status":{"S":"DELIVERED"}},"ConditionExpression":"attribute_not_exists(id)"}

Se generi file di input da una pipeline ETL, aggiungi ConditionExpression campo al modello di record. Se avete file esistenti senza condizioni, rielaborateli per iniettare la condizione prima di iniziare l'operazione.

Segnalazione di eventuali errori

Quando configuri la posizione di output di Amazon S3, includi CONDITION_CHECK_FAILURE nel OutputType elenco. DynamoDB invia i record degli elementi che non soddisfano la loro espressione di condizione nel bucket Amazon S3 di output. Puoi analizzare questi file di output per identificare quali elementi sono stati ignorati e intraprendere azioni correttive. Quando l'input utilizza espressioni condizionali, richiedi CONDITION_CHECK_FAILURE quindi gli elementi saltati vengono segnalati, perché senza di essi DynamoDB non ne conserva alcuna registrazione o conteggio.

Un'operazione ritentata o ripresa può segnalare un conflitto di controllo delle condizioni per un elemento che l'operazione stessa ha scritto in precedenza. Per distinguerlo da un conflitto con dati preesistenti, confronta l'immagine esistente nel rapporto con l'articolo fornito. Se sono uguali, l'operazione ha scritto quell'elemento e il conflitto è previsto.

Gli elementi qui riportati non sono stati scritti nel tentativo che ha prodotto il record. Vengono comunque fatturati. Per ulteriori informazioni, consulta Fatturazione dei report e degli articoli non riusciti. Per riconciliare i risultati di un'operazione di invio in blocco di articoli, utilizza i file di output di Amazon S3 insieme a DescribeBulkOperation conta. Per il flusso di lavoro completo, vedi Riconciliazione dei risultati.

Errori di convalida che bloccano un oggetto

Alcuni errori impediscono a DynamoDB di individuare il limite del record successivo. Questi errori includono JSON o Ion non valido o troncato, una struttura di record non valida, un elemento mancante o duplicato Item campo, un campo di primo livello sconosciuto, valori DynamoDB non validi, non validi UTF-8, input che raggiunge il limite di annidamento del parser, un record che supera il limite di lettura del parser, errori di decompressione, una mancata corrispondenza di compressione e alcuni errori di lettura degli oggetti di Amazon S3. Un record può contenere solo questi campi di primo livello: Item, ConditionExpression, ExpressionAttributeNames, e ExpressionAttributeValues.

Quando si verifica uno di questi errori, DynamoDB produce un risultato di errore e interrompe la lettura dell'oggetto Amazon S3. Altri oggetti di input possono continuare. Se lo hai richiesto ERROR output, la riga del rapporto contiene itemLocation.inputSourceArn e errorMessages, ma non contiene itemLocation.itemIndex. Un errore di convalida che si applica a un record completo include itemIndex e non arresta il resto dell'oggetto.

Il manifesto di completamento contrassegna l'oggetto PARTIALLY_PROCESSED ed elenca i record completati in processedRanges. Se DynamoDB non è in grado di confermare di aver letto tutti i byte di input memorizzati, l'operazione termina FAILED con codice di errore ValidationException. Se DynamoDB legge tutti i byte memorizzati prima di rilevare l'errore, l'operazione può terminare COMPLETED_WITH_ERRORS con ProcessedInputBytes pari a TotalInputBytes. Usa lo stato finale, ERROR rapporto e manifesto di completamento insieme per identificare i record da correggere o inviare nuovamente. DynamoDB non fattura i record che la convalida rifiuta durante la scrittura della tabella. Per ulteriori informazioni, consulta Fatturazione dei report e degli articoli non riusciti.