# スキーマレジストリの開始方法
以下のセクションでは、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