Organizacja danych

Dane są ustrukturyzowane w usłudze Azure Confidential Ledger na dwa podstawowe sposoby: identyfikator transakcji i identyfikator kolekcji (lub identyfikator podledgera). Każda operacja zapisu generuje unikatowy identyfikator transakcji, którego można użyć do pobierania wpisów, uzyskiwania potwierdzeń lub wykonywania innych operacji. Identyfikatory kolekcji to klucze określone przez użytkownika (opcjonalnie), które ułatwiają grupowanie powiązanych wpisów, co pozwala na bardziej wydajne pobieranie i zarządzanie danymi. W tym artykule przedstawiono przykłady pokazujące, jak tworzyć wpisy rejestru, pobierać wpisy według identyfikatora transakcji oraz listować wpisy w danym zakresie lub kolekcji.

Możesz również organizować i wykonywać zapytania dotyczące danych w publicznych rejestrach przy użyciu tagów. Tagi usprawniają zarządzanie danymi w kolekcjach, działając jako klucze pomocnicze.

Identyfikator transakcji

Każdy zapis zapisywany w rejestrze generuje identyfikator transakcji, który jest zwracany w odpowiedzi z punktu końcowego zapisu. Wygląda to jak w poniższym przykładzie:

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

Reakcja:

Transaction ID: 2.10

Zawartość wpisu rejestru ma ograniczony rozmiar. Aby uzyskać bieżący limit, zobacz limity usługi Azure Confidential Ledger.

Identyfikator transakcji w odpowiedzi może służyć do pobierania wpisu lub wykonywania innych operacji, takich jak pobieranie potwierdzenia. Można również uzyskać listę wpisów, podając zakres parametrów identyfikatora transakcji, jak w poniższym przykładzie.

# 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")

Note

Odczyt wpisów historycznych może powodować wyświetlenie stanu Loading, gdy rejestr je ładuje. Zapytania zakresowe mogą zwracać odnośnik nextLink do następnej strony wyników. Wyślij ponowną próbę lub żądanie kolejnej strony w ciągu jednej minuty. W przeciwnym razie księga odrzuca załadowane dane, a żądanie zwraca ponownie Loading.

Identyfikator kolekcji

Identyfikator kolekcji (znany również jako Subledger ID) w rejestrze Azure odnosi się do opcjonalnego klucza określonego przez użytkownika dla wpisów w rejestrze. Zapewnia on sposób dodawania klucza lub znacznika do zapisywanych danych, które następnie mogą służyć do pobierania danych później.

Identyfikatory kolekcji to ciągi o ograniczonej długości. Aby zapoznać się z bieżącymi limitami, zobacz limity usługi Azure Confidential Ledger.

Użyj identyfikatorów kolekcji do grupowania powiązanych wpisów. Ponieważ liczba kolekcji w rejestrze jest ograniczona, nie twórz unikatowego identyfikatora kolekcji dla każdego wpisu. Aby zidentyfikować pojedynczy wpis, użyj jego identyfikatora transakcji. Jeśli nie określisz identyfikatora kolekcji, dane są zapisywane w domyślnej kolekcji (subledger:0).

Aby określić identyfikator kolekcji, użytkownik musi określić parametr collectionID podczas żądania zapisu.

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

Następnie można pobrać transakcję, określając collection ID oraz transaction ID podczas odczytu lub podając tylko identyfikator kolekcji w operacjach list.

# 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']}")

Można również uzyskać listę wpisów w kolekcji, określając zarówno identyfikator kolekcji, jak i zakres parametrów identyfikatora transakcji.

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

Etykiety

Aby użyć tagów, użyj wersji interfejsu API REST 2026-02-23 lub nowszej.

Ponadto ta funkcja jest ograniczona do poufnych rejestrów, które są typu Rejestru publicznego . Prywatny Typ rejestru nie jest obsługiwany.

Tagi usprawniają zarządzanie danymi w kolekcji, działając jako klucze pomocnicze w kolekcji danych. Tagi mają limity długości, znaków, które mogą zawierać, liczby tagów na zapis i liczby tagów w księdze. Aby zapoznać się z bieżącymi limitami, zobacz Limity tagów na zapis i Limity danych rejestru.

Aby można było używać tagów wewnątrz kolekcji, należy określić parametr tagów.

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

Pobieranie wpisów można wykonać tak jak wcześniej:

# 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']}")

Przykładowe scenariusze

Poniższe scenariusze mogą pomóc w podjęciu decyzji, kiedy używać identyfikatorów kolekcji i tagów.

Scenario Zalecane podejście Dlaczego
Piszesz rekordy ogólne i najczęściej odczytujesz je według identyfikatora transakcji lub najnowszego wpisu. Użyj domyślnego identyfikatora kolekcji (subledger:0). Takie podejście zapewnia prostą organizację danych i pozwala uniknąć zarządzania wieloma identyfikatorami kolekcji.
Potrzebujesz ścisłego oddzielenia logicznego zestawów danych, takich jak izolacja przeznaczona dla najemcy lub specyficzna dla obciążenia. Użyj dedykowanych identyfikatorów kolekcji dla każdej grupy logicznej. Identyfikatory kolekcji na poziomie grupy ułatwiają izolowanie rekordów i wyświetlanie ich według granic.
Potrzebne są wyszukiwania zorientowane na zapytania w bardziej szczegółowy sposób, w tym kategoryzacja poszczególnych wpisów. Użyj tagów w kolekcji udostępnionej zamiast tworzyć unikatowy identyfikator kolekcji dla każdego wpisu. Możesz osiągnąć podobne wyniki zapytania bez tworzenia unikatowego identyfikatora kolekcji i zarządzania nim dla każdego wpisu.

Jeśli głównym celem jest elastyczność zapytań, zacznij od tagów i dodaj więcej identyfikatorów kolekcji tylko wtedy, gdy wymagane są jasne granice izolacji.

Należy pamiętać, że liczba kolekcji i tagów w rejestrze jest ograniczona. Aby uzyskać więcej informacji, zobacz limity usługi Azure Confidential Ledger.

Dalsze kroki