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à.
Annotazione degli oggetti
Usa le annotazioni per allegare payload di dati denominati ai tuoi oggetti Amazon S3. Ogni annotazione è un payload di metadati personalizzato di dimensioni comprese tra 1 byte e 1 MiB che puoi creare, recuperare, elencare ed eliminare senza modificare l'oggetto stesso.
È possibile associare fino a 1.000 annotazioni a una versione dell'oggetto. Ogni annotazione ha un nome univoco e può memorizzare dati strutturati come AI-generated etichette, contesto del documento, risultati di elaborazione o record di conformità.
I casi d'uso più comuni includono l'archiviazione dei risultati di inferenza dell'apprendimento automatico, gli AI-generated incorporamenti, le etichette di moderazione dei contenuti, l'output della classificazione dei documenti, la derivazione dei dati e gli audit trail, le etichette di conformità come i flag PII o le politiche di conservazione, i metadati di imaging medico, le informazioni sui diritti degli asset digitali e lo stato della pipeline ETL insieme all'oggetto di origine.
Le annotazioni vengono gestite utilizzando operazioni API dedicate, quindi non è necessario caricare nuovamente l'oggetto per aggiungere o aggiornare i metadati.
Puoi abilitare una tabella di annotazioni come parte della configurazione dei metadati S3 per interrogare i dati di annotazione su larga scala utilizzando Athena e altri servizi di analisi. S3 Metadata archivia i dati di annotazione in Apache Iceberg tabelle completamente gestite che Amazon S3 aggiorna automaticamente. Per ulteriori informazioni, consulta Individuazione dei dati con le tabelle di S3 Metadata.
Le annotazioni sono disponibili in tutte le AWS regioni commerciali e nelle regioni della Cina (Pechino e Ningxia). Le annotazioni non sono disponibili nelle regioni del Medio Oriente (Emirati Arabi Uniti) e del Medio Oriente (Bahrein). Le tabelle di annotazione dei metadati S3 sono disponibili in tutte le regioni in cui sono disponibili i metadati S3.
Quando utilizzare le annotazioni rispetto ai tag degli oggetti
Utilizzate il seguente confronto per determinare se le annotazioni o i tag degli oggetti sono la soluzione migliore per il vostro caso d'uso.
| Caratteristica | Tag dell'oggetto | Annotazioni |
|---|---|---|
| Massimo per oggetto | 10 per versione dell'oggetto | 1.000 per versione dell'oggetto |
| Dimensione massima | 128 caratteri (chiave) + 256 caratteri (valore) | 512 byte (nome) + 1 MiB (payload) |
| Formato dei dati | Key-value coppie di stringhe | Qualsiasi UTF-8 testo (JSON, XML, YAML, ecc.) |
| Mutabilità | Sì (PutObjectTagging) | Sì (PutObjectAnnotation) |
| Impostato durante il caricamento | Sì (PutObject, POST) | No (PutObjectAnnotation solo dopo il caricamento) |
Scegli le annotazioni quando devi archiviare dati strutturati (come JSON o XML), payload di dimensioni superiori a 256 caratteri o più di 10 voci di metadati per oggetto. Scegli i tag degli oggetti quando hai bisogno dell'integrazione delle policy IAM, del filtraggio delle regole del ciclo di vita di Amazon S3 o del report sull'allocazione dei costi.
Operazioni API per le annotazioni
Amazon S3 supporta le seguenti operazioni API per lavorare con le annotazioni:
-
PutObjectAnnotation— Crea o sovrascrive un'annotazione su un oggetto. Specificate il nome e il payload dell'annotazione nella richiesta.
-
GetObjectAnnotation— Restituisce il payload di un'annotazione specifica per nome.
-
ListObjectAnnotations— Restituisce l'elenco delle annotazioni su un oggetto. La risposta include il nome, la dimensione, l'ETag e la data dell'ultima modifica di ciascuna annotazione.
-
DeleteObjectAnnotation— Rimuove un'annotazione specifica per nome.
Amazon S3 supporta anche le annotazioni nelle seguenti operazioni API:
-
CopyObject— Copia le annotazioni dall'oggetto sorgente per impostazione predefinita. È possibile specificare l'
x-amz-annotation-directiveintestazione per controllare se le annotazioni vengono copiate (COPY) o escluse ().EXCLUDE -
UpdateBucketMetadataAnnotationTableConfiguration— Abilita o disabilita la tabella delle annotazioni nella configurazione dei metadati di S3.
-
CreateBucketMetadataConfiguration— Accetta un nuovo
AnnotationTableConfigurationparametro per abilitare le tabelle di annotazione quando crei una configurazione di metadati S3. -
GetBucketMetadataConfiguration— Restituisce
AnnotationTableConfigurationResultla risposta, che indica lo stato corrente della tabella di annotazioni.
Limiti di annotazione
Ogni versione dell'oggetto supporta fino a 1.000 annotazioni. Le annotazioni associate a una versione dell'oggetto devono avere nomi di annotazione univoci. Si applicano i seguenti limiti:
-
Il nome di un'annotazione può avere una lunghezza massima di 512 byte (UTF-8), in base alle regole di denominazione riportate di seguito.
-
Un payload di annotazione deve avere una dimensione compresa tra 1 byte e 1 MiB.
-
Lo spazio di archiviazione totale delle annotazioni per oggetto può essere fino a 1 GiB (1.000 annotazioni da 1 MiB ciascuna).
-
Algoritmi di checksum supportati: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Regole di denominazione delle annotazioni
I nomi delle annotazioni devono soddisfare i seguenti requisiti:
-
La lunghezza deve essere compresa tra 1 e 512 byte.
-
Può contenere solo i seguenti caratteri: lettere (qualsiasi lingua), cifre (0-9), trattino basso (), punto (
_) e trattino (.).- -
Non può iniziare con
awsos3(senza distinzione tra maiuscole e minuscole). Ad esempio,,awsAWSs3, eS3sono tutti prefissi riservati. -
Non deve essere vuoto o essere composto solo da spazi bianchi.
Encryption (Crittografia)
Le annotazioni vengono crittografate automaticamente quando sono inattive utilizzando la stessa configurazione di crittografia dell'oggetto principale. Il tipo di crittografia viene ereditato dall'oggetto principale, non dal bucket predefinito.
-
SSE-S3— Se l'oggetto principale utilizza la crittografia lato server con chiavi gestite di Amazon S3 SSE-S3 (), le annotazioni vengono crittografate con. SSE-S3 Se per l'oggetto principale non è configurata alcuna crittografia lato server, per impostazione predefinita le annotazioni vengono crittografate con. SSE-S3
-
SSE-KMS— Se l'oggetto principale utilizza la crittografia lato server con AWS KMS chiavi (SSE-KMS), le annotazioni vengono crittografate con la stessa chiave KMS. Questo vale sia per le chiavi gestite dal cliente che per le chiavi gestite. AWS Le chiavi S3 Bucket sono supportate.
-
DSSE-KMS— Se l'oggetto principale utilizza la crittografia lato server a doppio livello con AWS KMS chiavi (DSSE-KMS), le annotazioni vengono crittografate utilizzando la stessa chiave. DSSE-KMS
-
SSE-C— Server-side la crittografia con chiavi fornite dal cliente () SSE-C non è supportata per le annotazioni. Se tenti di aggiungere un'annotazione a un oggetto crittografato con SSE-C, Amazon S3 restituisce un errore.
Somme di controllo
Quando carichi un'annotazione utilizzandoPutObjectAnnotation, puoi fornire un checksum per verificare l'integrità dei dati. L'algoritmo di checksum per un'annotazione è indipendente dall'algoritmo di checksum dell'oggetto principale.
Quando copi un oggetto utilizzandoCopyObject, Amazon S3 conserva i valori del checksum delle annotazioni dall'origine. Se specifichi un algoritmo di checksum diverso nella richiesta di copia, il nuovo algoritmo si applica sia all'oggetto che alle sue annotazioni.
Algoritmi supportati: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Se l'annotazione non ha un algoritmo di checksum o un valore di checksum specificato, Amazon S3 utilizza l' CRC-64/NVME algoritmo per calcolare il valore di checksum per l'annotazione.
Comportamento del controllo delle versioni
Le annotazioni sono allegate a una versione specifica dell'oggetto.
Le annotazioni di una versione dell'oggetto sono indipendenti dalle annotazioni su altre versioni dello stesso oggetto. La creazione di una nuova versione non comporta la copia delle annotazioni dalla versione precedente. L'eliminazione o l'aggiunta di un'annotazione su una versione non influisce sulle annotazioni sulle altre versioni. La sovrascrittura di un oggetto sostituisce le relative annotazioni con le annotazioni presenti nella nuova versione (se nessuna, le elimina di fatto).
L'aggiunta, l'aggiornamento o la rimozione di un'annotazione non modifica l'ETag dell'oggetto principale.
In un bucket senza versione, se si elimina o si sovrascrive l'oggetto, anche le annotazioni vengono eliminate.
In un bucket con versione, si applica il seguente comportamento:
-
Una semplice richiesta DELETE (senza specificare un ID di versione) crea un marker di eliminazione ma conserva le annotazioni sulla versione sottostante.
-
L'eliminazione di un ID di versione specifico elimina quella versione e tutte le annotazioni associate.
-
Le annotazioni non hanno versioni indipendenti. Quando sovrascrivi un'annotazione con lo stesso nome, Amazon S3 sostituisce il valore precedente senza creare una nuova versione dell'oggetto.
Importante
L'eliminazione delle annotazioni è permanente e irreversibile, anche in un bucket con versioni diverse. A differenza degli oggetti nei bucket con versione, le annotazioni non hanno marcatori di eliminazione o cronologia delle versioni. Una volta eliminata, un'annotazione non può essere recuperata.
Comportamento e coerenza delle copie
Quando copi un oggetto utilizzando l'CopyObjectAPI (per oggetti di dimensioni inferiori a 5 GiB), Amazon S3 copia le annotazioni insieme all'oggetto in un'unica operazione.
Quando copi oggetti utilizzando il caricamento in più parti (ad esempio, quando gli AWS CLI AWS SDK utilizzano Transfer Manager per oggetti di dimensioni superiori a circa 8 MB), le annotazioni non vengono copiate per impostazione predefinita. Per includere le annotazioni, specificate nella configurazione SDK AWS CLI o --copy-props all nella configurazione SDK equivalente. Con questo opt-in, l'SDK legge le annotazioni di origine, completa il caricamento in più parti e quindi scrive ogni annotazione nella destinazione. Tra il completamento del caricamento e l'ultima scrittura dell'annotazione, l'oggetto di destinazione esiste senza tutte le relative annotazioni.
Considerazioni
-
Non è possibile aggiungere annotazioni come parte di una richiesta di caricamento
PutObjecto di più parti. Per aggiungere annotazioni a un oggetto, chiamatePutObjectAnnotationdopo il caricamento dell'oggetto. Per copiare un oggetto esistente con le relative annotazioni in una nuova posizione, utilizzaloCopyObjectcon la direttiva di annotazione predefinita. -
Per aggiungere o aggiornare annotazioni su molti oggetti in blocco, usa Batch Operations per richiamare una funzione Lambda che chiama ogni oggetto.
PutObjectAnnotationPer ulteriori informazioni, consulta Invoke AWS Lambda funzione. -
Le annotazioni non sono supportate dalle seguenti funzionalità: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, S3 Express One Zone (directory bucket) e Amazon S3 Files.
-
Per assicurarti di scrivere annotazioni sulla versione corrente di un oggetto e non su una che è stata sovrascritta, usa l'intestazione condizionale con o.
x-amz-object-if-matchPutObjectAnnotationDeleteObjectAnnotationQuesta intestazione convalida l'ETag dell'oggetto genitore per confermare che l'oggetto non è stato sovrascritto dall'ultima volta che il chiamante lo ha letto. L'aggiunta di tag o annotazioni non modifica l'ETag. -
Non è possibile aggiungere un'annotazione in base alla presenza o all'assenza di un'altra annotazione. L'
x-amz-object-if-matchintestazione convalida solo l'ETag dell'oggetto principale, non lo stato di annotazione. -
I payload di annotazione devono essere testo codificato valido. UTF-8 Per memorizzare dati binari, codificate i dati con Base64 prima di scrivere l'annotazione.
-
Puoi chiamare le operazioni dell'API di annotazione (
PutObjectAnnotation,,GetObjectAnnotationListObjectAnnotations,DeleteObjectAnnotation) sugli oggetti in qualsiasi classe di storage, inclusi S3 Glacier e S3 Glacier Deep Archive, senza prima ripristinare l'oggetto.
Configurazioni aggiuntive
Questa sezione spiega come le annotazioni si relazionano con altre configurazioni.
Replica
Se hai configurato S3 Replication sul tuo bucket, Amazon S3 replica automaticamente le annotazioni. Ogni annotazione viene replicata in modo indipendente. Per ulteriori informazioni, consulta Cosa replica Amazon S3?.
Per replicare le annotazioni, aggiungi s3:GetObjectVersionAnnotationForReplication al bucket di origine le autorizzazioni nel tuo ruolo IAM di replica. Per ulteriori informazioni, consulta Configurazione delle autorizzazioni per la replica in tempo reale.
Per impedire la replica delle annotazioni e consentire al contempo la replica degli oggetti, aggiungi una dichiarazione di negazione nella policy relativa al ruolo di replica. s3:ReplicateObjectAnnotation La replica degli oggetti continua ad avere successo; viene bloccata solo la replica delle annotazioni.
Notifiche degli eventi
Amazon S3 può inviare notifiche di eventi quando le annotazioni vengono create, aggiornate o eliminate. Puoi configurare i seguenti tipi di eventi:
-
s3:ObjectAnnotation:Put— Inviato quando viene creata o aggiornata un'annotazione. -
s3:ObjectAnnotation:Delete— Inviato quando viene eliminata un'annotazione.
Per ulteriori informazioni, consulta Tipi di notifiche eventi e destinazioni.
