Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
I dati sono strutturati all'interno dell'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 può essere usato per recuperare voci, ottenere ricevute o eseguire altre operazioni. Gli ID raccolta sono chiavi specificate dall'utente (facoltativo) che consentono di raggruppare o identificare in modo univoco le voci, consentendo un recupero e una gestione dei dati più efficienti. Questa pagina mostra esempi che illustrano come creare registrazioni contabili, recuperare voci in base all'ID transazione e elencare voci all'interno di un intervallo o di una raccolta.
Inoltre, i dati possono essere organizzati ed sottoposti a query tramite tag (in anteprima) che consentono una migliore 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
L'ID transazione nella risposta può essere usato per recuperare la voce o eseguire altre operazioni, ad esempio recuperare la ricevuta e così via. È 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 e non hanno attualmente limiti di dimensione. Ciò significa che la dimensione massima dipende dal limite di dimensioni delle richieste HTTP.
Possono essere utilizzati come chiavi univoche per ogni voce registrata nel libro mastro o per raggruppare un sottogruppo di voci.
Se non viene specificato alcun ID raccolta, i dati verranno scritti nella tabella predefinita (nota come 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_ledger_entry(collection_id="icecream-flavors")
# Get one specific in a collection
list_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 (anteprima)
L'aggiunta di tag a una raccolta è una caratteristica di anteprima disponibile con le versioni di anteprima più recenti del Ledger. Aggiorna alle versioni dell'SDK come indicato nel riferimento API REST 2024-12-09-preview o più recenti per l'accesso.
Inoltre, questa funzionalità è limitata ai ledgers riservati che sono del tipo di libro mastro pubblico . Il tipo di libro mastro privato non è supportato.
Consentono una migliore gestione dei dati all'interno di una raccolta fungendo da chiavi secondarie a una raccolta di dati. I tag sono limitati a 64 stringhe di caratteri. Ogni transazione può supportare fino a cinque tag. Se viene visualizzato un errore relativo al numero di tag supportati e è necessario un limite superiore, contattare il supporto tecnico.
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 di raccolta o i tag.
| Scenario | Approccio consigliato | Perché |
|---|---|---|
| Si scrivono record generali e per lo più letti in base all'ID transazione o alla voce più recente. | Usare l'ID raccolta predefinito (subledger-0). |
Questo approccio consente di semplificare l'organizzazione dei dati ed evitare di gestire molti ID raccolta. |
| È necessaria una rigorosa separazione logica dei set di dati, ad esempio l'isolamento specifico del tenant o specifico del carico di lavoro. | Usare gli ID di raccolta dedicati per ogni gruppo logico. | Gli ID di raccolta a livello di gruppo semplificano l'isolamento e l'elenco dei record in base ai confini. |
| Sono necessarie ricerche orientate alle query con una granularità più fine, inclusa la categorizzazione per singola voce. | Preferire i tag all'interno di una raccolta condivisa prima di creare un ID raccolta univoco per una voce. | È possibile ottenere risultati di query simili senza creare e gestire un ID raccolta univoco per ogni voce. |
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.