.NET 用 Azure Schema Registry Apache Avro クライアント ライブラリ - バージョン 1.0.0

  • [アーティクル]

Azure Schema Registry は、スキーマ ストレージ、バージョン管理、管理を提供する、Azure Event Hubsによってホストされるスキーマ リポジトリ サービスです。 このパッケージは、スキーマ レジストリ スキーマ識別子と Avro シリアル化されたデータを含むペイロードをシリアル化および逆シリアル化できる Avro シリアライザーを提供します。

作業の開始

パッケージをインストールする

NuGet を使用して.NET 用 Azure Schema Registry Apache Avro ライブラリをインストールします。

dotnet add package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro

前提条件

Event Hubs 名前空間を作成する必要がある場合は、Azure Portal または Azure PowerShellを使用できます。

Azure PowerShellを使用して、次のコマンドを使用して Event Hubs 名前空間を作成できます。

New-AzEventHubNamespace -ResourceGroupName myResourceGroup -NamespaceName namespace_name -Location eastus

クライアントを認証する

Azure Schema Registry サービスと対話するには、 スキーマ レジストリ クライアント クラスのインスタンスを作成する必要があります。 このクライアントを作成するには、Azure リソースの資格情報と Event Hubs 名前空間のホスト名が必要です。

資格情報の取得

認証された資格情報を取得し、Azure リソースとの対話を開始するには、 こちらのクイックスタート ガイドを参照してください。

Event Hubs 名前空間のホスト名を取得する

最も簡単な方法は、Azure portalを使用して Event Hubs 名前空間に移動することです。 [概要] タブに が表示されます Host name。 このフィールドから値をコピーします。

SchemaRegistryClient の作成

Azure リソースの資格情報と Event Hubs 名前空間のホスト名を取得したら、 SchemaRegistryClient を作成できます。 資格情報を作成するには 、Azure.Identity パッケージも必要です。

// Create a new SchemaRegistry client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
// For more information on Azure.Identity usage, see: https://github.com/Azure/azure-sdk-for-net/blob/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.0/sdk/identity/Azure.Identity/README.md
var schemaRegistryClient = new SchemaRegistryClient(fullyQualifiedNamespace: fullyQualifiedNamespace, credential: new DefaultAzureCredential());

主要な概念

シリアライザー

このライブラリは、イベントと対話するシリアライザー SchemaRegistryAvroSerializer を提供します EventData 。 SchemaRegistryAvroSerializer は、SchemaRegistryClient を利用して、データの EventData シリアル化に使用されるスキーマのスキーマ ID でイベントをエンリッチします。

このシリアライザーには Apache Avro ライブラリが必要です。 このシリアライザーで受け入れられるペイロードの種類には、 GenericRecord と ISpecificRecord が含まれます。

例

を使用して使用できる内容の例を次に SchemaRegistryAvroSerializer示します。 これらの操作には、同期メソッドと非同期メソッドの両方が使用できます。 これらの例では、このスキーマを使用して作成された生成された Apache Avro クラス Employee.cs を使用します。

{
   "type" : "record",
    "namespace" : "TestSchema",
    "name" : "Employee",
    "fields" : [
        { "name" : "Name" , "type" : "string" },
        { "name" : "Age", "type" : "int" }
    ]
}

Apache Avro ライブラリを使用したクラスの生成の詳細については、 Avro C# ドキュメントを参照してください。

Event Hub EventData モデルを使用してデータをシリアル化および逆シリアル化する

Avro 情報を使用してインスタンスを EventData シリアル化するには、次の操作を行います。

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = (EventData) await serializer.SerializeAsync(employee, messageType: typeof(EventData));

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

// construct a publisher and publish the events to our event hub
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();
await using var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
await producer.SendAsync(new EventData[] { eventData });

使用しているイベントを EventData 逆シリアル化するには:

// construct a consumer and consume the event from our event hub
await using var consumer = new EventHubConsumerClient(EventHubConsumerClient.DefaultConsumerGroupName, fullyQualifiedNamespace, eventHubName, credential);
await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync())
{
    Employee deserialized = (Employee) await serializer.DeserializeAsync(eventData, typeof(Employee));
    Console.WriteLine(deserialized.Age);
    Console.WriteLine(deserialized.Name);
    break;
}

ジェネリック メソッドを使用して、データをシリアル化および逆シリアル化することもできます。 これは、ジェネリックのウイルス性について心配する必要がないため、Avro シリアライザーの上にライブラリを構築していない場合に便利な場合があります。

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = await serializer.SerializeAsync<EventData, Employee>(employee);

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

同様に、逆シリアル化するには、次のようにします。

Employee deserialized = await serializer.DeserializeAsync<Employee>(eventData);
Console.WriteLine(deserialized.Age);
Console.WriteLine(deserialized.Name);

を直接使用してデータを MessageContent シリアル化および逆シリアル化する

を使用して MessageContentシリアル化および逆シリアル化することもできます。 で動作 MessageContentするメッセージング ライブラリと統合していない場合は、このオプションを使用します。

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });
MessageContent content = await serializer.SerializeAsync<MessageContent, Employee>(employee);

Employee deserializedEmployee = await serializer.DeserializeAsync<Employee>(content);

トラブルシューティング

スキーマ レジストリ サービスとの通信中にエラーが発生した場合、これらのエラーは RequestFailedException としてスローされます。 シリアライザーは、スキーマ (シリアル化時) またはスキーマ ID (逆シリアル化時) が初めて発生したときにのみサービスと通信します。 無効な Content-Types に関連するすべてのエラーは として FormatExceptionスローされます。 無効なスキーマに関連するエラーは として Exceptionスローされ、 InnerException プロパティには Apache Avro ライブラリからスローされた基になる例外が含まれます。 通常、この種類のエラーはテスト中にキャッチされ、コードでは処理しないでください。 互換性のないスキーマに関連するすべてのエラーは、 プロパティが InnerException Apache Avro ライブラリの基になる例外に設定された としてExceptionスローされます。

次のステップ

詳細については、「 Azure スキーマ レジストリ 」を参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数