Biblioteka klienta usługi Azure Schema Registry dla języka Python — wersja 1.2.0

Artykuł
04/05/2023

Usługa Azure Schema Registry to usługa repozytorium schematów hostowana przez Azure Event Hubs, zapewniając magazyn schematów, przechowywanie wersji i zarządzanie nimi. Rejestr jest używane przez serializatory w celu zmniejszenia rozmiaru ładunku podczas opisywania struktury ładunku z identyfikatorami schematu, a nie pełnymi schematami.

Kod | źródłowy Pakiet (PyPi) | Dokumentacja referencyjna interfejsu | API Próbki | Changelog

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę klienta rejestru schematów platformy Azure dla języka Python za pomocą narzędzia pip:

pip install azure-schemaregistry

Wymagania wstępne:

Aby użyć tego pakietu, musisz mieć następujące elementy:

Subskrypcja platformy Azure — można utworzyć bezpłatne konto
Rejestr - schematów platformy Azure Oto przewodnik Szybki start dotyczący tworzenia grupy rejestru schematów przy użyciu Azure Portal.
Środowisko Python w wersji 3.7 lub nowszej — instalowanie języka Python

Uwierzytelnianie klienta

Interakcja z rejestrem schematów rozpoczyna się od wystąpienia klasy SchemaRegistryClient. Konstruktor klienta przyjmuje w pełni kwalifikowaną przestrzeń nazw i poświadczenia usługi Azure Active Directory:

W pełni kwalifikowana przestrzeń nazw wystąpienia rejestru schematów powinna mieć następujący format: <yournamespace>.servicebus.windows.net.
Do konstruktora należy przekazać poświadczenie usługi AAD, które implementuje protokół TokenCredential . Istnieją implementacje TokenCredential protokołu dostępnego w pakiecie azure-identity. Aby użyć typów poświadczeń dostarczonych przez azure-identityprogram , zainstaluj bibliotekę klienta tożsamości platformy Azure dla języka Python za pomocą narzędzia pip:

pip install azure-identity

Ponadto aby użyć interfejsu API asynchronicznego, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp:

pip install aiohttp

Utwórz klienta przy użyciu biblioteki azure-identity:

from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
# Namespace should be similar to: '<your-eventhub-namespace>.servicebus.windows.net/'
fully_qualified_namespace = '<< FULLY QUALIFIED NAMESPACE OF THE SCHEMA REGISTRY >>'
schema_registry_client = SchemaRegistryClient(fully_qualified_namespace, credential)

Kluczowe pojęcia

Schemat: Schemat to organizacja lub struktura danych. Więcej szczegółowych informacji można znaleźć tutaj.
Grupa schematów: logiczna grupa podobnych schematów na podstawie kryteriów biznesowych, które mogą zawierać wiele wersji schematu. Więcej szczegółowych informacji można znaleźć tutaj.
SchemaRegistryClient: SchemaRegistryClient udostępnia interfejs API do przechowywania i pobierania schematów w rejestrze schematów.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań rejestru schematów, w tym:

Rejestrowanie schematu
Pobieranie schematu według identyfikatora
Pobieranie schematu według wersji
Pobieranie identyfikatora schematu

Rejestrowanie schematu

Użyj SchemaRegistryClient.register_schema metody do zarejestrowania schematu.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ['SCHEMA_REGISTRY_GROUP']
name = "your-schema-name"
format = "Avro"
definition = """
{"namespace": "example.avro",
 "type": "record",
 "name": "User",
 "fields": [
     {"name": "name", "type": "string"},
     {"name": "favorite_number",  "type": ["int", "null"]},
     {"name": "favorite_color", "type": ["string", "null"]}
 ]
}
"""

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema_properties = schema_registry_client.register_schema(group_name, name, definition, format)
    id = schema_properties.id

Pobieranie schematu według identyfikatora

Pobierz definicję schematu i jej właściwości według identyfikatora schematu.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
schema_id = 'your-schema-id'

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema = schema_registry_client.get_schema(schema_id)
    definition = schema.definition
    properties = schema.properties

Pobieranie schematu według wersji

Pobierz definicję schematu i jej właściwości według wersji schematu.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ["SCHEMAREGISTRY_GROUP"]
name = "your-schema-name"
version = int("<your schema version>")

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema = schema_registry_client.get_schema(group_name=group_name, name=name, version=version)
    definition = schema.definition
    properties = schema.properties

Pobieranie identyfikatora schematu

Pobierz identyfikator schematu według definicji schematu i jego właściwości.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ['SCHEMA_REGISTRY_GROUP']
name = "your-schema-name"
format = "Avro"
definition = """
{"namespace": "example.avro",
 "type": "record",
 "name": "User",
 "fields": [
     {"name": "name", "type": "string"},
     {"name": "favorite_number",  "type": ["int", "null"]},
     {"name": "favorite_color", "type": ["string", "null"]}
 ]
}
"""

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema_properties = schema_registry_client.register_schema(group_name, name, definition, format)
    id = schema_properties.id

Rozwiązywanie problemów

Ogólne

Klienci rejestru schematów zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem logging_enable :

import sys
import logging
from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential

# Create a logger for the SDK
logger = logging.getLogger('azure.schemaregistry')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
schema_registry_client = SchemaRegistryClient("your_fully_qualified_namespace", credential, logging_enable=True)

logging_enable Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

schema_registry_client.get_schema(schema_id, logging_enable=True)

Następne kroki

Więcej przykładów kodu

Zapoznaj się z katalogiem samples , aby uzyskać szczegółowe przykłady użycia tej biblioteki do rejestrowania i pobierania schematu do/z rejestru schematów.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Udostępnij za pośrednictwem