# AWS Glue スキーマレジストリ
**注記**
AWS Glue スキーマレジストリは、中東 (UAE) リージョンの AWS Glue コンソールではサポートされていません。
AWS Glue スキーマレジストリを使用すると、データストリームスキーマを一元的に検出、制御、展開できます。*スキーマ* は、データレコードの構造と形式を定義します。AWS Glue のスキーマレジストリを使用すると、Apache Kafka、[Amazon Managed Streaming for Apache Kafka](https://aws.amazon.com/msk/)、[Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/)、[Amazon Managed Service for Apache Flink](https://aws.amazon.com/kinesis/data-analytics/)、[AWS Lambda](https://aws.amazon.com/lambda/) と便利な統合を使用するデータストリームアプリケーションでスキーマを管理して実施することができます。
スキーマレジストリは、AVRO (v1.11.4) データ形式、[Everit ライブラリ](https://github.com/everit-org/json-schema)を使用した JSON スキーマ検証を含むスキーマ用 (Draft-04、Draft-06、Draft-07 仕様) の [JSON スキーマ形式](https://json-schema.org/)の JSON データ形式、`extensions` または `groups` のサポートが含まれないプロトコルバッファ (Protobuf) バージョンの proto2 および proto3、Java 言語対応をサポートしており、今後は他のデータ形式や言語にも対応していきます。サポートされている機能には、互換性、メタデータを介したスキーマのソーシング、スキーマの自動登録、IAM 互換性、ストレージとデータ転送を削減する ZLIB 圧縮のオプションがあります。スキーマレジストリはサーバーレスで無料で使用できます。
プロデューサとコンシューマの間のデータ形式契約としてスキーマを使用すると、データガバナンスおよびデータ品質の向上につながります。さらにデータのコンシューマは、上流で行われる互換性に関する変更に対する復旧力を得ることができます。
スキーマレジストリを使用すると、異なるシステムでシリアル化と非シリアル化用のスキーマを共有できます。例えば、データのプロデューサーとコンシューマーを考えてみます。データの公開時、プロデューサーはスキーマを把握しています。スキーマレジストリは、Amazon MSK や Apache Kafka などの特定のシステム用に、シリアル化と非シリアル化の機能を提供します。
詳しくは、「[スキーマレジストリの仕組み](schema-registry-works.md) 」を参照してください。
**Topics**
+ [スキーマ](#schema-registry-schemas)
+ [レジストリ](#schema-registry-registries)
+ [スキーマのバージョニングと互換性](#schema-registry-compatibility)
+ [オープンソース Serde ライブラリ](#schema-registry-serde-libraries)
+ [スキーマレジストリのクォータ](#schema-registry-quotas)
+ [スキーマレジストリの仕組み](schema-registry-works.md)
+ [スキーマレジストリの開始方法](schema-registry-gs.md)
## スキーマ
*スキーマ* は、データレコードの構造と形式を定義します。スキーマは、信頼性の高いデータの公開、利用、または保存のための仕様をバージョニングしたものです。
この例の Avro のスキーマでは、形式と構造はレイアウトとフィールド名によって定義され、フィールド名の形式はデータ型 (例:`string`、`int`) により定義されています
```
{
"type": "record",
"namespace": "ABC_Organization",
"name": "Employee",
"fields": [
{
"name": "Name",
"type": "string"
},
{
"name": "Age",
"type": "int"
},
{
"name": "address",
"type": {
"type": "record",
"name": "addressRecord",
"fields": [
{
"name": "street",
"type": "string"
},
{
"name": "zipcode",
"type": "int"
}
]
}
}
]
}
```
この例の JSON 用の JSON スキーマ draft-07 では、形式を [JSON スキーマ組織](https://json-schema.org/)が定義しています。
```
{
"$id": "https://example.com/person.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The person's first name."
},
"lastName": {
"type": "string",
"description": "The person's last name."
},
"age": {
"description": "Age in years which must be equal to or greater than zero.",
"type": "integer",
"minimum": 0
}
}
}
```
この例の Protobuf では、データ形式を [Protocol Buffers l言語のバージョン 2 (proto2)](https://developers.google.com/protocol-buffers/docs/reference/proto2-spec) で定義しています。
```
syntax = "proto2";
package tutorial;
option java_multiple_files = true;
option java_package = "com.example.tutorial.protos";
option java_outer_classname = "AddressBookProtos";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
optional string number = 1;
optional PhoneType type = 2 [default = HOME];
}
repeated PhoneNumber phones = 4;
}
message AddressBook {
repeated Person people = 1;
}
```
## レジストリ
*レジストリ* は、スキーマの論理コンテナです。レジストリを使用すると、スキーマを整理したり、アプリケーションのアクセス制御を管理したりできます。レジストリは Amazon リソースネーム (ARN) を持っており、これにより、レジストリ内のスキーマ操作に対するさまざまなアクセス許可の整理と設定を可能にしています。
レジストリはデフォルトのまま使用することも可能ですが、必要な数の新しいレジストリを作成することもできます。
**AWS Glue スキーマレジストリでの階層**
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/schema-registry.html) |
## スキーマのバージョニングと互換性
各スキーマは、複数のバージョン作成することができます。バージョニングは、スキーマに適用される互換性ルールによって制御されます。新しいスキーマバージョンの登録に関するリクエストについては、この規則に対するチェックがスキーマレジストリにより行われ後で処理が続行されます。
チェックポイントとしてマークされたスキーマバージョンは、スキーマの新しいバージョンを登録する際の互換性判断のために使用されます。スキーマが最初に作成されると、最初のバージョンがデフォルトのチェックポイントになります。スキーマのバージョンが増加した場合には、CLI/SDK により、一連の制約に従う `UpdateSchema` APIを使用しながら、チェックポイントに使用するスキーマのバージョンを変更できます。デフォルトでは、コンソールでスキーマの定義または互換モードを編集することで、チェックポイントが最新バージョンに変更されます。
互換モードを使用すると、スキーマを時間の経過とともにどのように増加させるか、あるいは増加させないかを制御できます。これらのモードは、データのプロデューサおよびコンシューマである、アプリケーション間の契約を形成します。スキーマの新しいバージョンがレジストリに送信されると、そのスキーマ名に適用されている互換性規則を使用して、新しいバージョンの受け付が可能かどうかが判断されます。互換モードには、NONE、DISABLED、BACKWARD、BACKWARD\$1ALL、FORWARD、FORWARD\$1ALL、FULL、FULL\$1ALL の 8 種類があります
Avro データ形式では、フィールドはオプションまたは必須の両方の場合があります。フィールドがオプションの場合、`Type` には null が含まれます。必須フィールドでは、`Type` は null に設定されません。
Protobuf のデータ形式の場合、 proto2 構文ではフィールドを (繰り返しを含み) オプションまたは必須にすることができます。一方、proto3 構文ではすべてのフィールドが (繰り返しを含み) オプションとなります。すべての互換性ルールは、Protocol Buffers の仕様と、[Google の Protocol Buffers ドキュメント](https://developers.google.com/protocol-buffers/docs/overview#updating)を詳細に把握した上で定義されています。
+ *NONE*: 互換モードは適用されません。このモードは、開発向けのシナリオか、スキーマに適用する互換モードがわからない場合に使用できます。新しいバージョンが追加されたとき、互換性チェックを受けずに受け入れられます。
+ *DISABLED*: 互換性についてこの選択をすると、特定のスキーマのバージョン管理が不要になります。新しいバージョンを追加することはできません。
+ *BACKWARD*: これは推奨の互換性モードで、コンシューマは、現在および過去のスキーマバージョンの両方からの読み取りが可能です。このモードを使用すると、フィールドの削除や任意のフィールドの追加を行う際に、以前のスキーマバージョンとの互換性をチェックできます。アプリケーションが最新のスキーマ用に作成された場合などが、BACKWARD の一般的なユースケースです。
**AVRO**
例えば、名前 (必須)、姓 (必須)、E メール (必須)、電話番号 (オプション) で定義されているスキーマがあるとします。
次のスキーマバージョンで、必須である E メールフィールドが削除されたとしても、これは正常に登録されます。後方互換性のために、コンシューマは、現在および 1 つ前のスキーマバージョンを読み取れることが必要です。古いメッセージの余分な E メールフィールドが無視されるため、コンシューマーは新しいスキーマを読み取ることができます。
仮に、郵便番号などのフィールドを必須として追加する新しいスキーマバージョンが提案された場合、BACKWARD の互換モードでは正常に登録されません。新しいバージョンのコンシューマーは、必須な郵便番号フィールドを含まない、スキーマが変更される前の古いメッセージを読み取ることができないためです。ただし、新しいスキーマで郵便番号フィールドがオプションとして設定されていれば、提案されたバージョンは正常に登録されます。郵便番号フィールドはオプションなので、コンシューマーはこのフィールドなしでも古いスキーマを読み取れるためです。
**JSON**
例えば、あるスキーマバージョンが、名 (オプション)、姓 (オプション)、E メール (オプション)、電話番号 (オプション)で定義されているとします。
仮に、次に続くスキーマバージョンで電話番号プロパティがオプションとして追加された場合でも、元のスキーマバージョンで `additionalProperties` フィールドを false に設定しプロパティの追加を禁止しているのであれば、この新しいバージョンは正しく登録されます。後方互換性のために、コンシューマは、現在および 1 つ前のスキーマバージョンを読み取れることが必要です。コンシューマは、電話番号プロパティが存在しない元のスキーマで生成されたデータを読み取ることができます。
BACKWARD の互換モードで、オプションの電話番号プロパティを追加する新しいスキーマバージョンが提案された際に、元のスキーマバージョンで `additionalProperties` フィールドを true に設定し任意のプロパティの追加を許可していると、このバージョンは正しく登録されません。新しいバージョンのコンシューマは、スキーマが変更される前の古いメッセージを読み取ることができません。これは、別の型 (数ではなく文字列など) で記述された電話番号プロパティデータを、読み取ることができないためです。
**PROTOBUF**
例えば、`first name` (必須)、`last name` (必須)、`email` (必須) `phone number` (オプション) フィールドを持つ、proto2 構文の Message `Person` で定義されているスキーマバージョンを考えます。
AVRO での場合と同様に、次に続くスキーマバージョンで、必須である `email` フィールドが削除されたとしても、これは正常に登録されます。後方互換性のために、コンシューマは、現在および 1 つ前のスキーマバージョンを読み取れることが必要です。古いメッセージでは、余分な `email` フィールドが無視されるため、コンシューマーは新しいスキーマを読み取ることができます。
BACKWARD の互換モードでは、仮に `zip code` などのフィールドを必須として追加する新しいスキーマバージョンが提案された場合、これは正常に登録されません。スキーマが変更される前の古いメッセージには、必須な `zip code` フィールドが含まていないため、新しいバージョンのコンシューマーは、そのメッセージを読み取ることができないためです。ただし、新しいスキーマで `zip code` フィールドがオプションとして設定されていれば、提案されたバージョンは正常に登録されます。`zip code` フィールドはオプションなので、コンシューマーはこのフィールドなしでも古いスキーマを読み取れます。
gRPC ユースケースの場合、新しい RPC サービスまたは RPC メソッドを追加することで、後方互換性が変更されます。例えば、2 つの RPC メソッド `Foo` および `Bar` を使用する RPC サービス `MyService` で定義されている、スキーマバージョンがあるとします。
次に続くスキーマバージョンで、`Baz` という新しい RPC メソッドが追加された場合、これは正常に登録されます。新しく追加された RPC メソッド `Baz` はオプションのため、コンシューマーは元のスキーマで生成されたデータを、BACKWARD 互換性に従って読み取ることができます。
提案された新しいスキーマバージョンで、既存の RPC メソッド `Foo` を削除する場合、BACKWARD 互換性では正常に登録されません。新しいバージョンのコンシューマーは、スキーマが変更される前の古いメッセージを読み取ることができません。これは、gRPC アプリケーション内に RPC メソッド `Foo` が存在せず、データを理解して読み取れないためです。
+ *BACKWARD\$1ALL*: この互換モードでは、コンシューマは現在および過去のすべてのスキーマバージョンの読み取りが可能です。このモードを使用すると、フィールドを削除したり任意のフィールドを追加する際に、以前のすべてのスキーマバージョンとの互換性をチェックできます。
+ *FORWARD*: この互換モードにより、コンシューマは現在とその次のスキーマバージョンの両方を読み取ることができますが、それより後に続くバージョンを必ずしも読み取れる訳ではありません。このオプションを使用すると、フィールドを追加したり、任意のフィールドを削除したりする際に、最新のスキーマバージョンとの互換性をチェックできます。過去のスキーマ用に作成されたアプリケーションが、より新しいスキーマを処理できる必要がある場合などが、FORWARD の一般的なユースケースです。
**AVRO**
例えば、あるスキーマバージョンが、名 (必須)、姓 (必須)、E メール (オプション) で定義されているとします。
この場合、電話番号などのフィールドを必須として追加する新しいスキーマバージョンは正常に登録されます。FORWARD 互換モードでは、新しいスキーマで生成されたデータを、コンシューマーが以前のバージョンを使用して読み取れることが必要です。
必須である名 (ファーストネーム) のフィールドを削除するスキーマバージョンが提案されとしても、FORWARD 互換モードでは正常に登録されません。名の必須フィールドがないので、以前のバージョンのコンシューマーが提案されたスキーマを読み取ることができなくなるためです。しかし、名 (ファーストネーム) のフィールドが本来オプションであれば、オプションの名のフィールドを持たない新しいスキーマに基づいたデータをコンシューマーが読み取りできるため、提案された新しいスキーマは正常に登録されます。
**JSON**
例えば、あるスキーマバージョンが、名 (オプション)、姓 (オプション)、E メール (オプション)、電話番号 (オプション)で定義されているとします。
オプションの電話番号プロパティを削除する新しいスキーマバージョンの場合、このスキーマバージョンで `additionalProperties` フィールドを false に設定しプロパティの追加を禁止しているのであれば、正しく登録されます。FORWARD 互換モードでは、新しいスキーマで生成されたデータを、コンシューマーが以前のバージョンを使用して読み取れることが必要です。
オプションの電話番号プロパティを削除するスキーマバージョンが提案された際に、この新しいスキーマバージョンで `additionalProperties` フィールドを true に設定し任意のプロパティの追加を許可していると、FORWARD の互換モードでは正しく登録されません。提案されたスキーマが、異なる型 (数ではなく文字列など) の電話番号プロパティを持つ場合には、以前のバージョンを使用するコンシューマで、このスキーマの読み取りが不可能になるためです。
**PROTOBUF**
例えば、`first name` (必須)、`last name` (必須)、`email` (オプション) のフィールドを持つ、proto2 構文の Message `Person` で定義されているスキーマバージョンを考えます。
AVRO の場合と同様に、`phone number` などの必須フィールドを追加する新しいスキーマバージョンの場合、これは正常に登録されます。FORWARD 互換モードでは、新しいスキーマで生成されたデータを、コンシューマーが以前のバージョンを使用して読み取れることが必要です。
必須である名 `first name` フィールドを削除するスキーマバージョンが提案されとしても、FORWARD 互換モードでは正常に登録されません。必須である `first name` フィールドがないので、以前のバージョンのコンシューマーは、提案されたスキーマを読み取ることができなくなるためです。しかし、`first name` フィールドが本来オプションであれば、新しいスキーマに `first name` フィールドがないとしてもこれはオプションであるため、コンシューマーはこのスキーマ基づいたデータを読み取ることが可能であり、したがって提案された新しいスキーマは正常に登録されます。
gRPC ユースケースの場合、RPC サービスまたは RPC メソッドを削除すると、前方互換性が変更されます。例えば、2 つの RPC メソッド `Foo` および `Bar` を使用する RPC サービス `MyService` で定義されている、スキーマバージョンがあるとします。
次に続くスキーマバージョンが、`Foo` という名前の既存の RPC メソッドを削除する場合も、これは FORWARD 互換性に従って正常に登録されます。コンシューマーは、新しいスキーマで生成されたデータを、以前のバージョンを使用して読み取ることが可能です。RPC メソッド `Baz` を追加するスキーマバージョンが提案され場合、これは FORWARD 互換モードでは正常に登録されません。RPC メソッド `Baz` がないので、以前のバージョンのコンシューマーは、この提案されたスキーマを読み取ることができないためです。
+ *FORWARD\$1ALL*: この互換モードでは、任意の新しい登録済みスキーマのプロデューサーによって書き込まれたデータを読み取ることを、コンシューマに許可します。この選択は、フィールドを追加したり、オプションフィールドを削除したり、以前のすべてのスキーマバージョンとの互換性を確認したりする必要がある場合に使用できます。
+ *FULL*: この互換モードにより、コンシューマーは、1 つ前または次のバージョンのスキーマを使用するプロデューサーによって書き込まれたデータを読み取ることができますが、それ以前またはそれ以降のバージョンについては読み取れません。このモードでは、任意のフィールドを追加または削除する際に、最新のスキーマバージョンとの互換性をチェックできます。
+ *FULL\$1ALL*: この互換モードにより、コンシューマーは、過去の任意のスキーマバージョンを使用するプロデューサーによって書き込まれたデータを読み取ることができます。このモードは、オプションのフィールドを追加または削除する際に、過去のすべてのスキーマバージョンとの互換性をチェックするために使用できます。
## オープンソース Serde ライブラリ
AWS では、データをシリアル化および非シリアル化するためのフレームワークとして、オープンソースの Serde ライブラリが用意されています。このオープンソースなライブラリ設計により、一般的なオープンソースのアプリケーションやフレームワークが、それぞれのプロジェクトでこれらのライブラリをサポートできるようにしています。
Serde ライブラリの仕組みの詳細については、「[スキーマレジストリの仕組み](schema-registry-works.md)」を参照してください。
## スキーマレジストリのクォータ
AWS のクォータ (制限とも呼ばれます) は、AWS アカウントのリソース、アクション、および制限の最大値です。以下に、AWS Glue のスキーマレジストリにおけるソフト制限を示します。
**スキーマバージョンのメタデータでのキー値ペアの数。**
AWS リージョンごとの各 SchemaVersion において、最大 10 個のキーと値のペアを使用できます。
メタデータでのキーと値のペアは、[QuerySchemaVersionMetadata アクション (Python: query\$1schema\$1version\$1metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-QuerySchemaVersionMetadata) または [PutSchemaVersionMetadata アクション (Python: put\$1schema\$1version\$1metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-PutSchemaVersionMetadata) APIを使用して表示または設定できます。
AWS Glue のスキーマレジストリでのハード制限は次のとおりです。
**レジストリ**
このアカウントでは、AWS リージョンごとに最大 100 のレジストリを使用できます。
**SchemaVersion**
このアカウントでは、AWS リージョンごとに最大 10000 のスキーマバージョンを使用できます。
各新しいスキーマは新しいスキーマバージョンを作成します。したがって、各スキーマに 1 つのバージョンしかない場合、リージョンごとの各アカウントには理論的に最大 10000 のスキーマを使用できます。
**スキーマペイロード**
スキーマペイロードには、170 KB のサイズ制限があります。
# スキーマレジストリの仕組み
このセクションでは、スキーマレジストリでシリアル化および非シリアル化のプロセスの仕組みについて説明します。
1. スキーマの登録: スキーマがレジストリにまだ存在しない場合、スキーマを保存先の名前と同じスキーマ名で登録することができます (test\$1topic、test\$1stream、prod\$1firehose など)。あるいは、プロデューサーがスキーマのカスタム名を指定することも可能です。プロデューサーは、source: msk\$1kafka\$1topic\$1A などのメタデータとしてスキーマにキーと値のペアを追加したり、スキーマ作成時に AWS タグをそのスキーマに追加したりできます。スキーマが登録されると、Schema Registry はスキーマのバージョン ID をシリアライザに返します。スキーマが存在するものの、シリアライザが存在しない新しいバージョンを使用している場合、それを新しいバージョンとして登録する前に、Schema Registry はスキーマ参照で互換性ルールを確認して、新しいバージョンに関する互換性を確保します。
スキーマの登録には、手動登録と自動登録の 2 つの方法があります。スキーマを手動で登録するには、AWS Glue コンソールまたは CLI/SDK を使用します。
シリアライザ設定で自動登録が有効化されている場合は、スキーマの自動登録が実行されます。プロデューサ設定で `REGISTRY_NAME` が指定されていない場合、自動登録はデフォルトのレジストリ (default-registry) の下に新しいスキーマバージョンを登録します。自動登録プロパティの指定については、「[SerDe ライブラリのインストール](schema-registry-gs-serde.md)」を参照してください。
1. シリアライザがスキーマに関してデータレコードを検証: データを生成するアプリケーションがそのスキーマを登録した場合、Schema Registry のシリアライザは、アプリケーションによって生成されるレコードが、登録されたスキーマに一致するフィールドとデータ型で構造化されていることを検証します。レコードのスキーマが登録されたスキーマと一致しない場合、シリアライザは例外を出力し、アプリケーションは、そのレコードを送信先にデリバリすることに失敗します。
スキーマが存在せず、プロデューサー設定を介してスキーマ名が指定されてもいない場合は、スキーマがトピック名 (Apache Kafka または Amazon MSK の場合) あるいはストリーム名 (Kinesis Data Streams の場合) と同じ名前で作成されます。
すべてのレコードは、スキーマ定義とデータを含みます。スキーマ定義は、Schema Registry 内の既存のスキーマおよびバージョンに関して照会されます。
デフォルトでは、プロデューサは、登録済みスキーマのスキーマ定義とスキーマバージョン ID をキャッシュします。レコードのスキーマバージョン定義がキャッシュ内に保存されたものと一致しない場合、プロデューサーは Schema Registry を使用してスキーマの検証を試みます。スキーマのバージョンが有効と認められた場合、そのバージョン ID と定義はプロデューサにローカルにキャッシュされます。
[SerDe ライブラリのインストール](schema-registry-gs-serde.md) のステップ 3 のように、オプションのプロデューサプロパティにより、デフォルトのキャッシュ期間 (24 時間) を調整することが可能です。
1. レコードのシリアル化と配信: レコードがスキーマに準拠している場合、シリアライザは各レコードをスキーマのバージョン ID で装飾し、選択したデータ形式 (AVRO、JSON、Protobuf 他の形式は追加予定) に基づいてシリアル化した上で、そのレコードを (プロデューサーのオプション設定により) 圧縮し送信先に送ります。
1. コンシューマーがデータを非シリアル化: このデータを読み取るコンシューマーは、レコードペイロードからのスキーマバージョン ID を解析する、Schema Registry のデシリアライザ用ライブラリを使用します。
1. デシリアライザが Schema Registry からのスキーマをリクエスト: デシリアライザが特定のスキーマバージョン ID を持つレコードを初めて認識すると、そのデシリアライザは、スキーマバージョン ID を使用してスキーマレジストリからスキーマを要求します。その後、そのスキーマをコンシューマ上でローカルにキャッシュします。Schema Registry でレコードの非シリアル化が不可能な場合、コンシューマはレコードからのデータをログに記録し、処理を続行するかアプリケーションを停止できます。
1. デシリアライザがスキーマを使用してレコードを非シリアル化: デシリアライザは、Schema Registry からスキーマバージョン ID を取得する際に (プロデューサーによって送信されたレコードが圧縮されている場合は) レコードを解凍し、スキーマを使用してレコードを非シリアル化します。これで、アプリケーションはレコードを処理できます。
**注記**
暗号化: クライアントは、HTTPS 上での TLS 暗号化を使用して転送中のデータを暗号化する API 呼び出しを介して Schema Registry と通信します。Schema Registry に保存されているスキーマは、サービス管理のAWS Key Management Service(AWS KMS) キーにより常に暗号化されます。
**注記**
ユーザー認可: Schema Registry は、アイデンティティベースの IAM ポリシーをサポートします。
# スキーマレジストリの開始方法
以下のセクションでは、Schema Registry のセットアップと使用に関する概要とチュートリアルを示します。スキーマレジストリの概念および各コンポーネントの詳細については、「[AWS Glue スキーマレジストリ](schema-registry.md)」を参照してください。
**Topics**
+ [SerDe ライブラリのインストール](schema-registry-gs-serde.md)
+ [AWS Glue Schema Registry との統合](schema-registry-integrations.md)
+ [サードパーティー製のスキーマレジストリから AWS Glue Schema Registry への移行](schema-registry-integrations-migration.md)
# SerDe ライブラリのインストール
SerDe ライブラリは、データのシリアル化と非シリアル化のためのフレームワークを提供します。
データを生成するアプリケーション (総称してシリアライザ) 用の、オープンソースのシリアライザをインストールします。シリアライザは、シリアル化、圧縮、および Schema Registry とのやり取りを処理します。シリアライザは、Schema Registry 対応の送信先 (Amazon MSK など) に書き込まれるレコードから、スキーマを自動的に抽出します。同様に、データを利用するアプリケーションには、オープンソースのデシリアライザをインストールします。
# Java 実装
**注記**
前提条件: 次のステップを実行する前に、Amazon Managed Streaming for Apache Kafka (Amazon MSK) または Apache Kafka クラスターを起動しておく必要があります。使用するプロデューサーとコンシューマーは、Java 8 以上で実行する必要があります。
プロデューサとコンシューマにライブラリをインストールするには
1. プロデューサとコンシューマ両方の pom.xml ファイルの中で、以下のコードにより依存関係を追加します。
```
software.amazon.glue
schema-registry-serde
1.1.5
```
または、[AWS Glue Schema Registry GitHub リポジトリ](https://github.com/awslabs/aws-glue-schema-registry)からクローンを作成することもできます。
1. 次の必須プロパティを使用してプロデューサをセットアップします。
```
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName()); // Can replace StringSerializer.class.getName()) with any other key serializer that you may use
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, GlueSchemaRegistryKafkaSerializer.class.getName());
props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2");
properties.put(AWSSchemaRegistryConstants.DATA_FORMAT, "JSON"); // OR "AVRO"
```
既存のスキーマがない場合は、自動登録を有効にします (次のステップ)。適用できるスキーマがある場合は、「my-schema」をそのスキーマ名に置き換えます。また、スキーマの自動登録が無効になっている場合は、「registry-name」を指定する必要もあります。スキーマが「default-registry」の下に作成されている場合は、レジストリ名を省略できます。
1. (オプション) これらのオプションのプロデューサープロパティのいずれかを設定します。プロパティの詳細については、[ReadMe ファイル](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md) を参照してください。
```
props.put(AWSSchemaRegistryConstants.SCHEMA_AUTO_REGISTRATION_SETTING, "true"); // If not passed, uses "false"
props.put(AWSSchemaRegistryConstants.SCHEMA_NAME, "my-schema"); // If not passed, uses transport name (topic name in case of Kafka, or stream name in case of Kinesis Data Streams)
props.put(AWSSchemaRegistryConstants.REGISTRY_NAME, "my-registry"); // If not passed, uses "default-registry"
props.put(AWSSchemaRegistryConstants.CACHE_TIME_TO_LIVE_MILLIS, "86400000"); // If not passed, uses 86400000 (24 Hours)
props.put(AWSSchemaRegistryConstants.CACHE_SIZE, "10"); // default value is 200
props.put(AWSSchemaRegistryConstants.COMPATIBILITY_SETTING, Compatibility.FULL); // Pass a compatibility mode. If not passed, uses Compatibility.BACKWARD
props.put(AWSSchemaRegistryConstants.DESCRIPTION, "This registry is used for several purposes."); // If not passed, constructs a description
props.put(AWSSchemaRegistryConstants.COMPRESSION_TYPE, AWSSchemaRegistryConstants.COMPRESSION.ZLIB); // If not passed, records are sent uncompressed
```
自動登録では、スキーマのバージョンがデフォルトのレジストリ (default-registry) に登録されます。`SCHEMA_NAME` が前のステップで指定されていない場合、トピック名は `SCHEMA_NAME` として推定されます。
互換モードの詳細については、[スキーマのバージョニングと互換性](schema-registry.md#schema-registry-compatibility) を参照してください。
1. 以下の必須プロパティを使用してコンシューマを設定します。
```
props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, GlueSchemaRegistryKafkaDeserializer.class.getName());
props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2"); // Pass an AWS リージョン
props.put(AWSSchemaRegistryConstants.AVRO_RECORD_TYPE, AvroRecordType.GENERIC_RECORD.getName()); // Only required for AVRO data format
```
1. (オプション) これらのオプションのコンシューマプロパティを設定します。プロパティの詳細については、[ReadMe ファイル](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md) を参照してください。
```
properties.put(AWSSchemaRegistryConstants.CACHE_TIME_TO_LIVE_MILLIS, "86400000"); // If not passed, uses 86400000
props.put(AWSSchemaRegistryConstants.CACHE_SIZE, "10"); // default value is 200
props.put(AWSSchemaRegistryConstants.SECONDARY_DESERIALIZER, "com.amazonaws.services.schemaregistry.deserializers.external.ThirdPartyDeserializer"); // For migration fall back scenario
```
# C\$1 実装
**注記**
前提条件: 次のステップを実行する前に、Amazon Managed Streaming for Apache Kafka (Amazon MSK) または Apache Kafka クラスターを起動しておく必要があります。使用するプロデューサーとコンシューマーは、.NET 8.0 以上で実行する必要があります。
## インストール
C\$1 アプリケーションの場合は、次のいずれかの方法を使用して AWS Glue Schema Registry SerDe NuGet パッケージをインストールします。
**.NET CLI:**
パッケージをインストールするには、次のコマンドを使用します。
```
dotnet add package Aws.Glue.SchemaRegistry --version 1.0.0-
```
ここで、`` は `1.0.0-linux-x64`、`1.0.0-linux-musl-x64` または `1.0.0-linux-arm64` です。
**PackageReference (.csproj ファイル内):**
プロジェクトファイルに次の内容を追加します。
```
```
ここで、`` は `1.0.0-linux-x64`、`1.0.0-linux-musl-x64` または `1.0.0-linux-arm64` です。
## 設定ファイルのセットアップ
必要な設定で設定プロパティファイル (`gsr-config.properties` など) を作成します。
**最小限の設定:**
以下に最小限の設定例を示します。
```
region=us-east-1
registry.name=default-registry
dataFormat=AVRO
schemaAutoRegistrationEnabled=true
```
## Kafka SerDes 用の C\$1 Glue スキーマクライアントライブラリの使用
**シリアライザーの使用例:**
次の例は、シリアライザーの使用方法を示しています。
```
private static readonly string PROTOBUF_CONFIG_PATH = "";
var protobufSerializer = new GlueSchemaRegistryKafkaSerializer(PROTOBUF_CONFIG_PATH);
var serialized = protobufSerializer.Serialize(message, message.Descriptor.FullName);
// send serialized bytes to Kafka using producer.Produce(serialized)
```
**デシリアライザーの使用例:**
次の例は、デシリアライザーの使用方法を示しています。
```
private static readonly string PROTOBUF_CONFIG_PATH = "";
var dataConfig = new GlueSchemaRegistryDataFormatConfiguration(
new Dictionary
{
{
GlueSchemaRegistryConstants.ProtobufMessageDescriptor, message.Descriptor
}
}
);
var protobufDeserializer = new GlueSchemaRegistryKafkaDeserializer(PROTOBUF_CONFIG_PATH, dataConfig);
// read message from Kafka using serialized = consumer.Consume()
var deserializedObject = protobufDeserializer.Deserialize(message.Descriptor.FullName, serialized);
```
## SerDes 用の KafkaFlow での C\$1 Glue スキーマクライアントライブラリの使用
**シリアライザーの使用例:**
次の例は、シリアライザーを使用して KafkaFlow を設定する方法を示しています。
```
services.AddKafka(kafka => kafka
.UseConsoleLog()
.AddCluster(cluster => cluster
.WithBrokers(new[] { "localhost:9092" })
.AddProducer(producer => producer
.DefaultTopic("customer-events")
.AddMiddlewares(m => m
.AddSerializer>(
() => new GlueSchemaRegistryKafkaFlowProtobufSerializer("config/gsr-config.properties")
)
)
)
)
);
```
**デシリアライザーの使用例:**
次の例は、デシリアライザーを使用して KafkaFlow を設定する方法を示しています。
```
.AddConsumer(consumer => consumer
.Topic("customer-events")
.WithGroupId("customer-group")
.WithBufferSize(100)
.WithWorkersCount(10)
.AddMiddlewares(middlewares => middlewares
.AddDeserializer>(
() => new GlueSchemaRegistryKafkaFlowProtobufDeserializer("config/gsr-config.properties")
)
.AddTypedHandlers(h => h.AddHandler())
)
)
```
## オプションのプロデューサープロパティ
追加のオプションプロパティを使用して、設定ファイルを拡張できます。
```
# Auto-registration (if not passed, uses "false")
schemaAutoRegistrationEnabled=true
# Schema name (if not passed, uses topic name)
schema.name=my-schema
# Registry name (if not passed, uses "default-registry")
registry.name=my-registry
# Cache settings
cacheTimeToLiveMillis=86400000
cacheSize=200
# Compatibility mode (if not passed, uses BACKWARD)
compatibility=FULL
# Registry description
description=This registry is used for several purposes.
# Compression (if not passed, records are sent uncompressed)
compressionType=ZLIB
```
## サポートされている日付書式
Java と C\$1 の両方の実装は、同じデータ形式をサポートしています。
+ *AVRO*: Apache Avro バイナリ形式
+ *JSON*: JSON スキーマ形式
+ *PROTOBUF*: プロトコルバッファ形式
## 注意事項
+ ライブラリの使用を開始するには、[https://www.nuget.org/packages/AWS.Glue.SchemaRegistry](https://www.nuget.org/packages/AWS.Glue.SchemaRegistry) にアクセスしてください
+ ソースコードは、[https://github.com/awslabs/aws-glue-schema-registry](https://github.com/awslabs/aws-glue-schema-registry) で入手できます
# レジストリを作成する
AWS Glue API または AWS Glue コンソールを使用して、デフォルトのレジストリを使用することも、必要な数の新しいレジストリを作成することもできます。
**AWS Glue API**
ここでの手順により、AWS Glue API を使用しながら対象のタスクを実行できます。
AWS Glue Schema Registry API で AWS CLI を使用するには、最新バージョンの AWS CLI 使用する必要が有ります。
新しいレジストリを追加するには、[CreateRegistry アクション (Python: create\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-CreateRegistry) APIを使用します。`RegistryName` では、作成するレジストリの名前を指定します。この文字数は最大 255 までで、文字、数字、ハイフン、アンダースコア、ドル記号、およびハッシュ記号のみ使用できます。
2,048 バイト以下で「[URI アドレスの複数行の文字列パターン](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-common.html#aws-glue-api-common-_string-patterns)」に一致する文字列として `Description` を指定します。
オプションで、キーと値のペアのマップ配列として、1 つ以上の `Tags` をレジストリに指定します。
```
aws glue create-registry --registry-name registryName1 --description description
```
作成されたレジストリには、Amazon リソースネーム (ARN) が割り当てられます。これは、`RegistryArn` API 応答により表示することが可能です。この段階でレジストリ作成が完了しているので、そのレジストリのために 1 つ以上のスキーマを作成します。
**AWS Glue コンソール**
AWS Glue コンソールで新しいレジストリを追加するには
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schema registries**] (スキーマレジストリ) をクリックします。
1. [**Add registry**] (レジストリを追加) をクリックします。
1. [**Registry name**] (レジストリ名) に、文字、数字、ハイフン、アンダースコアを含むレジストリの名前を入力します。この名前は変更できません。
1. レジストリの [**Description**] (説明) を入力します (オプション)。
1. オプションで、1 つ以上のタグをレジストリに適用します。[**Add new tag**] (新しいタグを追加) を選択し、[**Tag key**] (タグキー) とオプションの [**Tag value**] (タグ値) を指定します。
1. [**Add registry**] (レジストリを追加) をクリックします。
![\[レジストリの作成例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/schema_reg_create_registry.png)
作成されたレジストリには、Amazon リソースネーム (ARN) が割り当てられます。これは、[**Schema registries**] (スキーマレジストリ) のリストから選択して表示することが可能です。この段階でレジストリ作成が完了しているので、そのレジストリのために 1 つ以上のスキーマを作成します。
# JSON の特定のレコード (JAVA POJO) 処理する
従来の単純な Java オブジェクト (POJO) を使用して、オブジェクトをレコードとして渡すことができます。これは、AVRO における特定のレコードの概念と類似しています。[mbknor-jackson-jsonschema](https://github.com/mbknor/mbknor-jackson-jsonSchema) により、渡された POJO の JSON スキーマを生成できます。また、このライブラリでは、JSON スキーマに追加情報を挿入することもできます。
AWS Glue Schema Registry ライブラリは、スキーマに注入された「className」フィールドを使用して、完全に分類されたクラス名を提供します。「className」フィールドは、そのクラスのオブジェクト内での非シリアル化のために、デシリアライザによって使用されます。
```
Example class :
@JsonSchemaDescription("This is a car")
@JsonSchemaTitle("Simple Car Schema")
@Builder
@AllArgsConstructor
@EqualsAndHashCode
// Fully qualified class name to be added to an additionally injected property
// called className for deserializer to determine which class to deserialize
// the bytes into
@JsonSchemaInject(
strings = {@JsonSchemaString(path = "className",
value = "com.amazonaws.services.schemaregistry.integrationtests.generators.Car")}
)
// List of annotations to help infer JSON Schema are defined by https://github.com/mbknor/mbknor-jackson-jsonSchema
public class Car {
@JsonProperty(required = true)
private String make;
@JsonProperty(required = true)
private String model;
@JsonSchemaDefault("true")
@JsonProperty
public boolean used;
@JsonSchemaInject(ints = {@JsonSchemaInt(path = "multipleOf", value = 1000)})
@Max(200000)
@JsonProperty
private int miles;
@Min(2000)
@JsonProperty
private int year;
@JsonProperty
private Date purchaseDate;
@JsonProperty
@JsonFormat(shape = JsonFormat.Shape.NUMBER)
private Date listedDate;
@JsonProperty
private String[] owners;
@JsonProperty
private Collection serviceChecks;
// Empty constructor is required by Jackson to deserialize bytes
// into an Object of this class
public Car() {}
}
```
# スキーマの作成
スキーマは、AWS Glue API または AWS Glue コンソールを使用して作成できます。
**AWS Glue API**
ここでの手順により、AWS Glue API を使用しながら対象のタスクを実行できます。
新しいスキーマを追加するには [CreateSchema アクション (Python: create\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-CreateSchema) API を使用します。
`RegistryId` 構造体を使用して、スキーマのレジストリを指定します。または、`RegistryId` を省略すると、デフォルトのレジストリが使用されます。
文字、数字、ハイフン、アンダースコアを使用し、`DataFormat` として **AVRO** または **JSON** を設定しながら `SchemaName` を指定します。一度スキーマに設定された `DataFormat` は変更できません。
`Compatibility` モードを指定する。
+ *Backward (推奨)* – コンシューマは、現在のバージョンと 1 つ前のバージョンの両方を読み取ることができます。
+ *Backward all* – コンシューマは、現在のバージョンと過去のすべてのバージョンを読み取ることができます。
+ *Forward* – コンシューマは、現在のバージョンと次に続くバージョンの両方を読み取ることができます。
+ *Forward all* – コンシューマは、現在のバージョンと後続のすべてのバージョンの両方を読み取ることができます。
+ *Full* – Backward all と Forward all を組み合わせたモードです。
+ *Full all* – Backward all と Forward all を組み合わせたモードです。
+ *None* – 互換性チェックは実行されません。
+ *Disabled* – このスキーマのバージョニングを抑止します。
オプションで、スキーマに `Tags` を指定します。
`SchemaDefinition` を指定することで、スキーマのデータ形式を Avro、JSON、もしくは Protobuf として定義します。例を参照してください。
Avro データ形式の場合:
```
aws glue create-schema --registry-id RegistryName="registryName1" --schema-name testschema --compatibility NONE --data-format AVRO --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}"
```
```
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1" --schema-name testschema --compatibility NONE --data-format AVRO --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}"
```
JSON データ形式の場合:
```
aws glue create-schema --registry-id RegistryName="registryName" --schema-name testSchemaJson --compatibility NONE --data-format JSON --schema-definition "{\"$schema\": \"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}"
```
```
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName" --schema-name testSchemaJson --compatibility NONE --data-format JSON --schema-definition "{\"$schema\": \"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}"
```
Protobuf データ形式の場合:
```
aws glue create-schema --registry-id RegistryName="registryName" --schema-name testSchemaProtobuf --compatibility NONE --data-format PROTOBUF --schema-definition "syntax = \"proto2\";package org.test;message Basic { optional int32 basic = 1;}"
```
```
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName" --schema-name testSchemaProtobuf --compatibility NONE --data-format PROTOBUF --schema-definition "syntax = \"proto2\";package org.test;message Basic { optional int32 basic = 1;}"
```
**AWS Glue コンソール**
AWS Glue コンソールを使用して新しいスキーマを追加するには
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schemas**] (スキーマ) をクリックします。
1. [**Add schema**] (スキーマを追加) をクリックします。
1. [**Schema name**] (スキーマ名) に、文字、数字、ハイフン、アンダースコア、ドル記号、ハッシュマークで構成された名前を入力します。この名前は変更できません。
1. [**Registry**] (レジストリ) ドロップダウンメニューから、スキーマの保存先となるレジストリを選択します。作成後は、親レジストリを変更することはできません。
1. [**Data format**] (データ形式) は、「*Apache Avro*」または「*JSON*」のままにしておきます。この形式は、このスキーマのすべてのバージョンに適用されます。
1. [**Compatibility mode**] (互換モード) をクリックします。
+ *Backward (推奨)* – レシーバーは、現在のバージョンと 1 つ前のバージョンの両方を読み取ることができます。
+ *Backward All* – レシーバーは、現在および過去のすべてのバージョンを読み取ることができます。
+ *Forward* – センダーは、現在のバージョンと 1 つ前のバージョンの両方に書き込むことができます。
+ *Forward All* – センダーは、現在のバージョンと過去のすべてのバージョンに書き込むことができます。
+ *Full* – Backward と Forward を組み合わせたモードです。
+ *Full All* – Backward All と Forward All を組み合わせたモードです。
+ *None* – 互換性チェックは実行されません。
+ *Disabled* – このスキーマのバージョニングを抑止します。
1. [**Description**] (説明) に、レジストリのための説明 (オプション) を、最大 250 文字で入力します。
![\[スキーマの作成例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/schema_reg_create_schema.png)
1. オプションで、1 つ以上のタグをスキーマに適用します。[**Add new tag**] (新しいタグを追加) を選択し、[**Tag key**] (タグキー) とオプションの [**Tag value**] (タグ値) を指定します。
1. [**First schema バージョニング**] (最初のスキーマバージョン) ボックスに、初期スキーマを入力するか貼り付けます。
Avro 形式については「[Avro データ形式での作業](#schema-registry-avro)」を参照
JSON 形式については「[JSON データ形式での操作](#schema-registry-json)」を参照
1. 必要に応じて、[**Add metadata**] (メタデータを追加) をクリックして、スキーマバージョンの注釈付けや分類を行うためのバージョンメタデータを追加します。
1. [**Create schema and version**] (スキーマとバージョンを作成する) をクリックします。
![\[スキーマの作成例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/schema_reg_create_schema2.png)
スキーマが作成され、[**Schemas**] (スキーマ) の下に一覧表示されます。
## Avro データ形式での作業
Avro では、データのシリアル化とデータ交換サービスが利用できます。Avro は、可読性と解釈しやすさのために、データ定義が JSON 形式で格納されます。データ自体はバイナリ形式で保存されます。
Apache Avro スキーマの定義については、「[Apache Avro specification](http://avro.apache.org/docs/current/spec.html)」を参照してください。
## JSON データ形式での操作
JSON 形式では、データをシリアル化できます。JSON スキーマ形式の標準は、「[JSON Schema format](https://json-schema.org/)」で定義されています。
# スキーマまたはレジストリの更新
作成したスキーマ、スキーマバージョン、またはレジストリは、編集することができます。
## レジストリの更新
レジストリは、AWS Glue API または AWS Glue コンソールを使用して更新できます。既存のレジストリの名前は変更できません。レジストリの説明は編集が可能です。
**AWS Glue API**
既存のレジストリを更新するには、[UpdateRegistry アクション (Python: update\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-UpdateRegistry) API を使用します。
`RegistryId` 構造体を使用して、更新するレジストリを指定します。レジストリの説明を変更するには、`Description` を渡します。
```
aws glue update-registry --description updatedDescription --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1"
```
**AWS Glue コンソール**
AWS Glue コンソールを使用してレジストリを更新するには
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schema registries**] (スキーマレジストリ) をクリックします。
1. レジストリの一覧から、そのチェックボックスをオンにして、レジストリを選択します。
1. [**Action**] (アクション) メニューで、[**Edit registry**] (レジストリの編集) を選択します。
# スキーマの更新
スキーマでは、説明または互換性設定の更新が行えます。
既存のスキーマを更新するには、[UpdateSchema アクション (Python: update\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-UpdateSchema) API を使用します。
`SchemaId` 構造体を使用して、更新するスキーマを指定します。`VersionNumber` または `Compatibility` のいずれかを指定する必要があります。
コード例 11:
```
aws glue update-schema --description testDescription --schema-id SchemaName="testSchema1",RegistryName="registryName1" --schema-version-number LatestVersion=true --compatibility NONE
```
```
aws glue update-schema --description testDescription --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/registryName1/testSchema1" --schema-version-number LatestVersion=true --compatibility NONE
```
# スキーマバージョンの追加。
スキーマバージョンを追加する際は、そのバージョンを比較して、新しいスキーマが受け入れられることを確認する必要があります。
既存のスキーマに新しいバージョンを追加するには、[RegisterSchemaVersion アクション (Python: register\$1schema\$1version)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-RegisterSchemaVersion) API を使用します。
`SchemaId` 構造体を使用して、バージョンを追加するスキーマを指定し、`SchemaDefinition` によりスキーマを定義します。
コード例 12:
```
aws glue register-schema-version --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}" --schema-id SchemaArn="arn:aws:glue:us-east-1:901234567890:schema/registryName/testschema"
```
```
aws glue register-schema-version --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}" --schema-id SchemaName="testschema",RegistryName="testregistry"
```
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schemas**] (スキーマ) をクリックします。
1. チェックボックスをオンにして、スキーマのリストからスキーマを選択します。
1. チェックボックスをクリックして、リストから 1 つ以上のスキーマを選択します。
1. [**Action**] (アクションメニュー) から、[**Register new version**] (新しいバージョンを登録) を選択します。
1. [**New version**] (新しいバージョン) ボックスに、新しいスキーマを入力または貼り付けます。
1. **[Compare with previous version]** (過去のバージョンと比較) をクリックして、以前のスキーマのバージョンとの違いを確認します。
1. 必要に応じて、[**Add metadata**] (メタデータを追加) をクリックして、スキーマバージョンの注釈付けや分類を行うためのバージョンメタデータを追加します。[**Key**] (キー) および (オプションの) [**Value**] (値) を入力します。
1. [**Register version**] (バージョンの登録) をクリックします。
![\[スキーマバージョンの追加。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/schema_reg_add_schema_version.png)
バージョンの一覧の中に、スキーマのバージョンが表示されます。バージョンで互換モードが変更された場合、そのバージョンはチェックポイントとしてマークされます。
## スキーマのバージョン比較の例。
[**Compare with previous version**] (過去のバージョンと比較) をクリックすると、以前のバージョンと新しいバージョンが一緒に表示されます。変更された情報は、次のように強調表示されます。
+ *黄色*: 変更された情報を示します。
+ *緑*: 最新バージョンで追加されたコンテンツを示します。
+ *赤*: 最新バージョンで削除されたコンテンツを示します。
より古いバージョンと比較することも可能です。
![\[スキーマのバージョン比較の例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/schema_reg_version_comparison.png)
# スキーマまたはレジストリの削除
スキーマ、スキーマバージョン、またはレジストリの削除は永続的な操作であり、元に戻すことはできません。
## スキーマの削除
レジストリ内で使用する必要がなくなったスキーマは、AWS マネジメントコンソール または [DeleteSchema アクション (Python: delete\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchema) API を使用して削除することができます。。
1 つ以上のスキーマを削除することは永続的なアクションであり、元に戻すことはできません。(1 つあるいは複数の) スキーマが不要になったことを確認します。
レジストリからスキーマを削除するには、`SchemaId` 構造体により対象のスキーマを特定しながら [DeleteSchema アクション (Python: delete\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchema) API を呼び出します。
例:
```
aws glue delete-schema --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/registryName1/schemaname"
```
```
aws glue delete-schema --schema-id SchemaName="TestSchema6-deleteschemabyname",RegistryName="default-registry"
```
**AWS Glue コンソール**
AWS Glue コンソールからスキーマを削除するには
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schema registries**] (スキーマレジストリ) をクリックします。
1. レジストリのリストから、自分のスキーマを含むレジストリを選択します。
1. チェックボックスをクリックして、リストから 1 つ以上のスキーマを選択します。
1. [**Action**] (アクション) メニューで、[**Delete schema**] (スキーマの削除) をクリックします。
1. フィールドに「**Delete**」というテキストを入力して、削除を確定します。
1. **[削除]** を選択します。
指定した (1 つ以上の) スキーマがレジストリから削除されます。
## スキーマバージョンの削除
スキーマはレジストリに蓄積されるので、不要なスキーマバージョンは、AWS マネジメントコンソール または [DeleteSchemaVersions アクション (Python: delete\$1schema\$1versions)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchemaVersions) API を使用して削除できます。1 つ以上のスキーマバージョンを削除することは永続的なアクションであり、元に戻すことはできません。そのスキーマバージョンが不要であることを確認します。
スキーマのバージョンを削除する場合は、以下の制約に注意してください。
+ チェックポイントとなっているバージョンを削除することはできません。
+ 25 を超えて連続するバージョンの範囲を削除することはできません。
+ 最新のスキーマバージョンが保留状態にある場合は、削除は行えません。
`SchemaId` 構造体を使用してスキーマを指定し、削除するバージョンの範囲を `Versions` で指定します。バージョンまたはバージョンの範囲の指定の詳細については、「[DeleteRegistry アクション (Python: delete\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteRegistry)」を参照してください。指定したスキーマバージョンがレジストリから削除されます。
この呼び出しの後に [ListSchemaVersions アクション (Python: list\$1schema\$1versions)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-ListSchemaVersions) API を呼び出すと、削除されたバージョンのステータスが一覧表示されます。
例:
```
aws glue delete-schema-versions --schema-id SchemaName="TestSchema6",RegistryName="default-registry" --versions "1-1"
```
```
aws glue delete-schema-versions --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/default-registry/TestSchema6-NON-Existent" --versions "1-1"
```
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schema registries**] (スキーマレジストリ) をクリックします。
1. レジストリのリストから、自分のスキーマを含むレジストリを選択します。
1. チェックボックスをクリックして、リストから 1 つ以上のスキーマを選択します。
1. [**Action**] (アクション) メニューで、[**Delete schema**] (スキーマの削除) をクリックします。
1. フィールドに「**Delete**」というテキストを入力して、削除を確定します。
1. **[削除]** を選択します。
指定したスキーマバージョンがレジストリから削除されます。
# レジストリの削除
レジストリに含まれるスキーマの整理の必要性がなくなった場合は、そのレジストリを削除することができます。これらのスキーマは、別のレジストリに再割り当てする必要があります。
1 つ以上のレジストリを削除することは永続的なアクションであり、元に戻すことはできません。(1 つもしくは複数の) レジストリが不要であることを確認します。
デフォルトのレジストリは、AWS CLI を使用して削除できます。
**AWS Glue API**
レジストリ全体を、登録されたスキーマとそのすべてのバージョンとともに削除するには、[DeleteRegistry アクション (Python: delete\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteRegistry) API を呼び出します。`RegistryId` 構造体を使用し、レジストリを特定します。
例:
```
aws glue delete-registry --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1"
```
```
aws glue delete-registry --registry-id RegistryName="TestRegistry-deletebyname"
```
削除オペレーションのステータスを取得するには、非同期呼び出し後に `GetRegistry` API を呼び出します。
**AWS Glue コンソール**
AWS Glue コンソールからレジストリの削除を行うには
1. AWS マネジメントコンソールにサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\)) を開きます。
1. ナビゲーションペインの [**Data catalog**] (データカタログ) で、[**Schema registries**] (スキーマレジストリ) をクリックします。
1. チェックボックスをオンにして、リストからレジストリを選択します。
1. [**Action**] (アクション) メニューで、[**Delete registry**] (レジストリの削除) を選択します。
1. フィールドに「**Delete**」というテキストを入力して、削除を確定します。
1. **[削除]** を選択します。
選択したレジストリが AWS Glue から削除されます。
## シリアライザ用の IAM の例
**注記**
AWS 管理ポリシーは、一般的ユースケースに必要なアクセス許可を付与します。管理ポリシーを使用してスキーマのレジストリを管理する方法については、「[AWS Glue の AWS マネージド (事前定義) ポリシー](security-iam-awsmanpol.md#access-policy-examples-aws-managed)」を参照してください。
シリアライザの場合、以下と同様の最小限のポリシーを作成して、特定のスキーマ定義のために `schemaVersionId` を検索できるようにします。レジストリ内のスキーマを読み取るには、そのレジストリに対する読み取り許可が必要であることに注意してください。読み取り可能なレジストリは、`Resource` 句を使用して制限できます。
コード例 13:
```
{
"Sid" : "GetSchemaByDefinition",
"Effect" : "Allow",
"Action" :
[
"glue:GetSchemaByDefinition"
],
"Resource" : ["arn:aws:glue:us-east-2:012345678:registry/registryname-1",
"arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-1",
"arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-2"
]
}
```
さらに、以下の新しいメソッドを追加して、プロデューサに対し新しいスキーマとバージョンの作成を許可することもできます。レジストリ内でスキーマを追加/削除/拡大させるためには、そのレジストリを調査できることが必要です。調査することが可能なレジストリは、`Resource` 句を使用して制限できます。
コード例 14:
```
{
"Sid" : "RegisterSchemaWithMetadata",
"Effect" : "Allow",
"Action" :
[
"glue:GetSchemaByDefinition",
"glue:CreateSchema",
"glue:RegisterSchemaVersion",
"glue:PutSchemaVersionMetadata",
],
"Resource" : ["arn:aws:glue:aws-region:123456789012:registry/registryname-1",
"arn:aws:glue:aws-region:123456789012:schema/registryname-1/schemaname-1",
"arn:aws:glue:aws-region:123456789012:schema/registryname-1/schemaname-2"
]
}
```
## デシリアライザー用の IAM の例
デシリアライザ (コンシューマ側) の場合、以下のようなポリシーを作成する必要があります。これにより、非シリアル化のために Schema Registry からスキーマを取得することを、デシリアライザに対し許可します。レジストリ内のスキーマを取得するためには、そのレジストリを調査することが許可されている必要があります。
コード例 15:
```
{
"Sid" : "GetSchemaVersion",
"Effect" : "Allow",
"Action" :
[
"glue:GetSchemaVersion"
],
"Resource" : ["*"]
}
```
## AWS PrivateLink を使用したプライベート接続
AWS Glue でインターフェイス VPC エンドポイントを定義しながら AWS PrivateLinkを使用すると、データのプロデユーサの VPC を AWS Glue に接続することができます。VPC インターフェイスエンドポイントにより、AWS ネットワーク内全体で VPC と AWS Glue 間の通信を処理します。詳細については、「[Using AWS Glue with VPC Endpoints](https://docs.aws.amazon.com/glue/latest/dg/vpc-endpoint.html)」を参照してください。
# Amazon CloudWatch メトリクスへのアクセス
Amazon CloudWatch メトリクスは、CloudWatch の無料利用枠の一部として利用できます。これらのメトリクスは CloudWatch コンソールでアクセスできます。APIレベルのメトリクスとしては、CreateSchema (Success および Latency)、GetSchemaByDefinition (Success および Latency)、GetSchemaVersion (Success および Latency)、RegisterSchemaVersion (Success および Latency)、PutSchemaVersionMetadata (Success および Latency) があります。リソースレベルのメトリクスには、Registry.ThrottledByLimit、SchemaVersion.ThrottledByLimit、SchemaVersion.Size があります。
# スキーマレジストリの CloudFormation テンプレート例
以下に、CloudFormation で Schema Registry リソースを作成するためのテンプレート例を示します。アカウントにこのスタックを作成するには、上記のテンプレートを `SampleTemplate.yaml` ファイルにコピーした上で、次のコマンドを実行します。
```
aws cloudformation create-stack --stack-name ABCSchemaRegistryStack --template-body "'cat SampleTemplate.yaml'"
```
この例では、レジストリを作成するために `AWS::Glue::Registry` を、スキーマを作成するために `AWS::Glue::Schema` を、スキーマバージョンを作成するために `AWS::Glue::SchemaVersion` を使用し、`AWS::Glue::SchemaVersionMetadata` によりスキーマバージョンのメタデータを記述しています。
```
Description: "A sample CloudFormation template for creating Schema Registry resources."
Resources:
ABCRegistry:
Type: "AWS::Glue::Registry"
Properties:
Name: "ABCSchemaRegistry"
Description: "ABC Corp. Schema Registry"
Tags:
Project: "Foo"
ABCSchema:
Type: "AWS::Glue::Schema"
Properties:
Registry:
Arn: !Ref ABCRegistry
Name: "TestSchema"
Compatibility: "NONE"
DataFormat: "AVRO"
SchemaDefinition: >
{"namespace":"foo.avro","type":"record","name":"user","fields":[{"name":"name","type":"string"},{"name":"favorite_number","type":"int"}]}
Tags:
Project: "Foo"
SecondSchemaVersion:
Type: "AWS::Glue::SchemaVersion"
Properties:
Schema:
SchemaArn: !Ref ABCSchema
SchemaDefinition: >
{"namespace":"foo.avro","type":"record","name":"user","fields":[{"name":"status","type":"string", "default":"ON"}, {"name":"name","type":"string"},{"name":"favorite_number","type":"int"}]}
FirstSchemaVersionMetadata:
Type: "AWS::Glue::SchemaVersionMetadata"
Properties:
SchemaVersionId: !GetAtt ABCSchema.InitialSchemaVersionId
Key: "Application"
Value: "Kinesis"
SecondSchemaVersionMetadata:
Type: "AWS::Glue::SchemaVersionMetadata"
Properties:
SchemaVersionId: !Ref SecondSchemaVersion
Key: "Application"
Value: "Kinesis"
```
# AWS Glue Schema Registry との統合
これらのセクションでは、AWS Glue スキーマレジストリとの統合について説明します。このセクションの例では、AVRO データ形式のスキーマを使用します。JSON データ形式のスキーマなど、その他の例については、「[AWS Glue Schema Registry open source repository](https://github.com/awslabs/aws-glue-schema-registry)」で、統合テストと ReadMe に関する情報をご覧ください。
**Topics**
+ [ユースケース: Schema Registry を Amazon MSK または Apache Kafka に接続する](#schema-registry-integrations-amazon-msk)
+ [ユースケース: Amazon Kinesis Data Streams と AWS Glue Schema Registry との統合](#schema-registry-integrations-kds)
+ [Amazon Managed Service for Apache Flink のユースケース](#schema-registry-integrations-kinesis-data-analytics-apache-flink)
+ [ユースケース: AWS Lambda との統合](#schema-registry-integrations-aws-lambda)
+ [ユースケース: AWS Glue Data Catalog](#schema-registry-integrations-aws-glue-data-catalog)
+ [ユースケース: AWS Glue ストリーミング](#schema-registry-integrations-aws-glue-streaming)
+ [ユースケース: Apache Kafka ストリーム](#schema-registry-integrations-apache-kafka-streams)
## ユースケース: Schema Registry を Amazon MSK または Apache Kafka に接続する
Apache Kafka トピックにデータを書き込む場合には、以下の手順に従い作業を開始します。
1. Amazon Managed Streaming for Apache Kafka(Amazon MSK) または Apache Kafka のクラスターを作成し、少なくとも 1 つのトピックを含めます。Amazon MSK クラスターを作成する場合は、AWS マネジメントコンソール を使用します。「*Amazon Managed Streaming for Apache Kafka デベロッパーガイド*」の「[Getting Started Using Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/getting-started.html)」にある手順に従います。
1. 上記の [SerDe ライブラリのインストール](schema-registry-gs-serde.md) ステップを実行します。
1. スキーマのレジストリ、スキーマ、またはスキーマバージョンを作成するには、このドキュメントにある [スキーマレジストリの開始方法](schema-registry-gs.md) セクションの手順に従います。
1. Amazon MSK または Apache Kafka のトピックとの間で、レコードの書き込みや読み取りを行うために、Schema Registry を使用してプロデューサとコンシューマを起動します。プロデューサとコンシューマのコード例は、Serdeライブラリの [ReadMe ファイル](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md)から入手できます。プロデューサの Schema Registry ライブラリは、レコードを自動的にシリアル化し、スキーマバージョン ID でそのレコードを修飾します。
1. このレコードにスキーマが入力済みの場合、または自動登録が有効になっている場合には、スキーマが Schema Registry に登録されます。
1. AWS Glue Schema Registry ライブラリを使用して、Amazon MSK または Apache Kafka のトピックからスキーマの読み取りを行うコンシューマは、自動的に Schema Registry からスキーマを検索します。
## ユースケース: Amazon Kinesis Data Streams と AWS Glue Schema Registry との統合
この統合には、既存の Amazon Kinesis データストリーム が必要です。詳細については、「*Amazon Kinesis Data Streams デベロッパーガイド*」の「[Getting Started with Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/getting-started.html)」を参照してください。
Kinesis データストリームでは、データの操作用に以下の 2 つの方法があります。
+ Java の Kinesis Producer Library (KPL) および Kinesis Client Library (KCL) ライブラリを使用します。多言語サポートは提供されていません。
+ AWS SDK for Java に用意されている `PutRecords`、`PutRecord`、および `GetRecords` Kinesis Data Streams API を使用します。
現在、KPL/KCL ライブラリを使用中であれば、そのメソッドを引き続き使用することをお勧めします。ここでの例に示すように、Schema Registry が統合済みの、更新された KCL および KPL バージョンを使用できます。それ以外で、KDS API を直接使用している場合には、サンプルコードを通じて AWS Glue Schema Registry を利用します。
Schema Registry との統合は、KPL v0.14.2 以降と KCL v2.3 以降でのみ使用できます。JSON データ形式による Schema Registry との統合は、KPL v0.14.8 以降および KCL v2.3.6 以降で使用できます。
### Kinesis SDK V2 を使用したデータの操作
このセクションでは、Kinesis SDK V2 による Kinesis の操作について説明します。
```
// Example JSON Record, you can construct a AVRO record also
private static final JsonDataWithSchema record = JsonDataWithSchema.builder(schemaString, payloadString);
private static final DataFormat dataFormat = DataFormat.JSON;
//Configurations for Schema Registry
GlueSchemaRegistryConfiguration gsrConfig = new GlueSchemaRegistryConfiguration("us-east-1");
GlueSchemaRegistrySerializer glueSchemaRegistrySerializer =
new GlueSchemaRegistrySerializerImpl(awsCredentialsProvider, gsrConfig);
GlueSchemaRegistryDataFormatSerializer dataFormatSerializer =
new GlueSchemaRegistrySerializerFactory().getInstance(dataFormat, gsrConfig);
Schema gsrSchema =
new Schema(dataFormatSerializer.getSchemaDefinition(record), dataFormat.name(), "MySchema");
byte[] serializedBytes = dataFormatSerializer.serialize(record);
byte[] gsrEncodedBytes = glueSchemaRegistrySerializer.encode(streamName, gsrSchema, serializedBytes);
PutRecordRequest putRecordRequest = PutRecordRequest.builder()
.streamName(streamName)
.partitionKey("partitionKey")
.data(SdkBytes.fromByteArray(gsrEncodedBytes))
.build();
shardId = kinesisClient.putRecord(putRecordRequest)
.get()
.shardId();
GlueSchemaRegistryDeserializer glueSchemaRegistryDeserializer = new GlueSchemaRegistryDeserializerImpl(awsCredentialsProvider, gsrConfig);
GlueSchemaRegistryDataFormatDeserializer gsrDataFormatDeserializer =
glueSchemaRegistryDeserializerFactory.getInstance(dataFormat, gsrConfig);
GetShardIteratorRequest getShardIteratorRequest = GetShardIteratorRequest.builder()
.streamName(streamName)
.shardId(shardId)
.shardIteratorType(ShardIteratorType.TRIM_HORIZON)
.build();
String shardIterator = kinesisClient.getShardIterator(getShardIteratorRequest)
.get()
.shardIterator();
GetRecordsRequest getRecordRequest = GetRecordsRequest.builder()
.shardIterator(shardIterator)
.build();
GetRecordsResponse recordsResponse = kinesisClient.getRecords(getRecordRequest)
.get();
List