Organizzazione dei dati

I dati sono strutturati all'interno di Azure confidential ledger in due modi principali: ID transazione e ID raccolta (o ID subledger). Ogni operazione di scrittura genera un ID transazione univoco, che è possibile usare per recuperare voci, ottenere ricevute o eseguire altre operazioni. Gli ID raccolta sono chiavi specificate dall'utente (facoltative) che consentono di raggruppare le voci correlate, consentendo un recupero e una gestione dei dati più efficienti. Questo articolo illustra esempi che mostrano come creare registrazioni del libro mastro, recuperare voci in base all'ID transazione e elencare le voci all'interno di un intervallo o di una raccolta.

È anche possibile organizzare ed eseguire query sui registri pubblici usando tag. I tag migliorano la gestione dei dati all'interno delle raccolte fungendo da chiavi secondarie.

IT transazione

Ogni scrittura registrata nel libro mastro genera un ID transazione, che viene restituito nella risposta dall'endpoint di scrittura. L'esempio seguente è simile al seguente:

sample_entry = {"contents": "Hello world!"}
append_result = ledger_client.create_ledger_entry(entry=sample_entry)
print(f"Transaction ID: {append_result['transactionId']}")

Risposta:

Transaction ID: 2.10

Il contenuto di un movimento contabile è limitato in dimensioni. Per il limite attuale, vedere Limiti di Azure Confidential Ledger.

L'ID transazione nella risposta può essere usato per recuperare la voce o eseguire altre operazioni, ad esempio il recupero della ricevuta. È anche possibile ottenere un elenco di voci fornendo un intervallo di parametri ID transazione simili all'esempio seguente.

# Get the latest transaction to the ledger default/global table
get_result = ledger_client.get_current_ledger_entry()

# Get one transaction
get_result = ledger_client.get_ledger_entry(transaction_id="2.10")

# Get a list of transactions within a range
list_result = ledger_client.list_ledger_entries(from_transaction_id="2.1", to_transaction_id="2.50")

ID raccolta

Un ID raccolta (denominato anche ID libro mastro secondario) in Azure Ledger si riferisce a una chiave facoltativa specificata dall'utente per le voci registrate nel libro mastro. Fornisce un modo per aggiungere una chiave o un marcatore ai dati scritti che possono quindi essere usati per recuperare i dati in un secondo momento.

Gli ID raccolta sono stringhe con lunghezza limitata. Per i limiti attuali, vedere limiti di Azure Confidential Ledger.

Usare gli ID di raccolta per raggruppare le voci correlate. Poiché il numero di raccolte in un registro è limitato, non creare un ID raccolta univoco per ogni voce. Per identificare una singola voce, usare il relativo ID transazione. Se non si specifica un ID raccolta, i dati vengono scritti nella raccolta predefinita (subledger:0).

Per specificare un ID raccolta, l'utente deve specificare il parametro collectionID durante la richiesta di scrittura.

sample_entry = {"contents": "Secret recipe ingredients...!"}
append_result = ledger_client.create_ledger_entry(entry=sample_entry, collection_id="icecream-flavors")

La transazione può quindi essere recuperata specificando collection ID e transaction ID durante un'operazione di lettura o specificando solo l'ID raccolta nelle list operazioni.

# Get the latest transaction in a collection
get_result = ledger_client.get_current_ledger_entry(collection_id="icecream-flavors")

# Get one specific entry in a collection
get_result = ledger_client.get_ledger_entry(transaction_id="2.68", collection_id="icecream-flavors")

# Get all entries in a collection
list_result = ledger_client.list_ledger_entries(collection_id="icecream-flavors")
for entry in list_result:
    print(f"Transaction ID: {entry['transactionId']}")
    print(f"Contents: {entry['contents']}")

È anche possibile ottenere un elenco di voci all'interno di una raccolta specificando sia l'ID raccolta che un intervallo di parametri ID transazione.

list_result = ledger_client.list_ledger_entries(from_transaction_id="2.1", to_transaction_id="2.50", collection_id="icecream-flavors")

Tag

Per usare i tag, usare la versione 2026-02-23 o successiva dell'API REST.

Inoltre, questa funzionalità è limitata ai ledgers riservati che sono del tipo di libro mastro pubblico . Il tipo di libro mastro privato non è supportato.

I tag migliorano la gestione dei dati all'interno di una raccolta fungendo da chiavi secondarie in una raccolta di dati. I tag hanno limiti sulla loro lunghezza, i caratteri che possono contenere, il numero di tag per scrittura e il numero di tag in un ledger. Per i limiti correnti, vedere Limiti dei tag per scrittura e limiti dei dati del registro mastro.

Per usare i tag all'interno di una raccolta, è necessario specificare il parametro tags.

# multiple tags can be specified using commas.
append_result = ledger_client.create_ledger_entry(entry=sample_entry, collection_id="icecream-flavors", tags="chocolate,vanilla")

È possibile recuperare le voci come prima:

# Get all entries in a collection which has a specified tag. Only one tag is supported per query during a Read operation. Only list/ranged operations are supported with tags.  
list_result = ledger_client.list_ledger_entries(collection_id="icecream-flavors", tag="chocolate")
for entry in list_result:
    print(f"Transaction ID: {entry['transactionId']}")
    print(f"Contents: {entry['contents']}")

Scenari di esempio

Gli scenari seguenti consentono di decidere quando usare gli ID raccolta rispetto ai tag.

Se l'obiettivo principale è la flessibilità delle query, inizia con i tag e aggiungi altri ID delle raccolte solo quando sono necessari limiti di isolamento chiari.

Tenere presente che il numero di raccolte e tag in un libro mastro è limitato. Per altre informazioni, vedere Azure confidential ledger limits.

Passaggi successivi

• Panoramica del libro mastro riservato di Microsoft Azure
• Programmazione lato server in Azure Confidential Ledger
• documentazione di riferimento dell'API