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
<a name="BulkPutItems.Format"></a>

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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html).

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.

**Topics**
+ [Formati e compressione supportati](#BulkPutItems.Format.Supported)
+ [DynamoDB JSON](#BulkPutItems.Format.DDBJson)
+ [Amazon Ion](#BulkPutItems.Format.Ion)
+ [Layout dei dati di origine in Amazon S3](#BulkPutItems.Format.SourceData)
+ [Per-item espressioni di condizione](#BulkPutItems.Format.Conditions)
+ [Segnalazione di eventuali errori](#BulkPutItems.Format.Reporting)
+ [Errori di convalida che bloccano un oggetto](#BulkPutItems.Format.ValidationErrors)

## Formati e compressione supportati
<a name="BulkPutItems.Format.Supported"></a>

Specifica il formato di input quando chiami [StartBulkPutItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html) impostando [InputFormat](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-InputFormat) campo in [Configurazione degli ingressi 3](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html), 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](BulkPutItems.Requesting.md#BulkPutItems.Requesting.Start).


| Formato | Description | 
| --- | --- | 
| `DYNAMODB_JSON` | DynamoDB ha eseguito il marshalling di JSON. Un oggetto JSON per riga ([Linee JSON](https://jsonlines.org/) formato). Ogni riga contiene un `Item` campo e campi di condizione opzionali. | 
| `ION` | Formato di testo Amazon Ion. Ogni record è una struttura Ion contenente un `Item` campo e campi condizionali opzionali, delimitati da nuove righe. | 

Imposta il [InputCompressionType](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-InputCompressionType) campo per indicare come vengono compressi i tuoi oggetti Amazon S3.


| Tipo di compressione | Description | 
| --- | --- | 
| `GZIP` | Gli oggetti sono GZIP-compressed. | 
| `ZSTD` | Gli oggetti sono Zstandard-compressed. | 
| `NONE` | Gli oggetti non sono compressi. | 

## DynamoDB JSON
<a name="BulkPutItems.Format.DDBJson"></a>

Un file in formato JSON DynamoDB è costituito da un oggetto JSON per riga ([Linee JSON](https://jsonlines.org/) 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](#BulkPutItems.Format.Conditions).

**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
<a name="BulkPutItems.Format.Ion"></a>

[Amazon Ion](https://amzn.github.io/ion-docs/) è 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**

**Nota**  
Nell'esempio seguente, gli elementi sono formattati su più righe per migliorare la leggibilità. Nei file di input effettivi, ogni record si trova su una singola riga.

```
$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.


| Tipo di dati Ion | Rappresentazione DynamoDB | 
| --- | --- | 
| `string` | `String (S)` | 
| `bool` | `Boolean (BOOL)` | 
| `decimal` | `Number (N)` | 
| `blob` | `Binary (B)` | 
| `list` (con annotazione `$dynamodb_SS`, `$dynamodb_NS`, o `$dynamodb_BS`) | `Set (SS, NS, BS)` | 
| `list` | `List (L)` | 
| `struct` | `Map (M)` | 

## Layout dei dati di origine in Amazon S3
<a name="BulkPutItems.Format.SourceData"></a>

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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-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](BulkPutItems.BestPractices.md).

**Nota**  
Tutti gli oggetti con il prefisso della chiave S3 specificato devono utilizzare lo stesso formato e lo stesso tipo di compressione. Non è possibile combinare oggetti JSON e Ion di DynamoDB o combinare oggetti compressi e non compressi in un'unica operazione di inserimento in blocco degli elementi.

## Per-item espressioni di condizione
<a name="BulkPutItems.Format.Conditions"></a>

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](Expressions.ConditionExpressions.md). Per gli operatori e le funzioni supportati, vedere [Espressioni, operatori e funzioni di condizione e di filtro in DynamoDB](Expressions.OperatorsAndFunctions.md).

Ogni record nel file di input contiene i seguenti campi:
+ `Item` (obbligatorio) — L'elemento da scrivere, in formato JSON o Ion con marshalling di DynamoDB.
+ `ConditionExpression` (opzionale) — Un'espressione condizionale che deve essere valutata come vera per l'elemento da scrivere.
+ `ExpressionAttributeNames` (opzionale) — Una mappa dei token di sostituzione per i nomi degli attributi nell'espressione della condizione.
+ `ExpressionAttributeValues` (opzionale) — Una mappa dei token di sostituzione per i valori degli attributi nell'espressione della condizione.

### Comportamento di valutazione delle condizioni
<a name="BulkPutItems.Format.Conditions.Behaviour"></a>

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


| Scenario | Comportamento | 
| --- | --- | 
| Nessuna condizione in un record | L'elemento viene scritto incondizionatamente, sovrascrivendo qualsiasi elemento esistente con la stessa chiave primaria. | 
| `attribute_not_exists({{pk}})` | Insert-only semantica per quel record. L'elemento viene scritto solo se nella tabella non esiste già alcun elemento con la stessa chiave primaria. | 
| Per-item protezione della versione | È possibile specificare una condizione che controlli un attributo di versione, ad esempio `#v = :expected`. Ciò consente casi d'uso sicuri per la migrazione interregionale e la sincronizzazione incrementale. Per scrivere sia articoli nuovi di zecca che versioni più recenti, usa `attribute_not_exists(#v) OR #v < :new`. | 
| Condizione non soddisfatta | L'articolo è stato saltato. DynamoDB segnala l'articolo saltato solo se richiedi `CONDITION_CHECK_FAILURE` tipo di output. Per ulteriori informazioni, consulta [Segnalazione di eventuali errori](#BulkPutItems.Format.Reporting). | 

**Importante**  
Gli articoli che non superano il controllo delle condizioni vengono comunque fatturati. Per informazioni dettagliate, vedi [Fatturazione dei report e degli articoli non riusciti](BulkPutItems.Output.md#BulkPutItems.Output.Billing).

### Per ottenere una semantica che preveda solo l'inserimento di nuovi elementi
<a name="BulkPutItems.Format.Conditions.InsertOnly"></a>

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
<a name="BulkPutItems.Format.Reporting"></a>

Quando configuri la posizione di output di Amazon S3, includi `CONDITION_CHECK_FAILURE` nel [OutputType](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_OutputS3Configuration.html#DDB-Type-OutputS3Configuration-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](BulkPutItems.Output.md#BulkPutItems.Output.Billing). Per riconciliare i risultati di un'operazione di invio in blocco di articoli, utilizza i file di output di Amazon S3 insieme a [DescribeBulkOperation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeBulkOperation.html) conta. Per il flusso di lavoro completo, vedi [Riconciliazione dei risultati](BulkPutItems.Output.md#BulkPutItems.Output.Reconciliation).

## Errori di convalida che bloccano un oggetto
<a name="BulkPutItems.Format.ValidationErrors"></a>

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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-ProcessedInputBytes) pari a [TotalInputBytes](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-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](BulkPutItems.Output.md#BulkPutItems.Output.Billing).