1.2. Service Registry のスキーマと API アーティファクト
イベントスキーマや API 設計などの Service Registry に保存される項目は、レジストリーアーティファクトと呼ばれます。以下は、単純な株価アプリケーションの JSON 形式の Apache Avro スキーマアーティファクトの例を示しています。
Avro スキーマの例
{
"type": "record",
"name": "price",
"namespace": "com.example",
"fields": [
{
"name": "symbol",
"type": "string"
},
{
"name": "price",
"type": "string"
}
]
}
スキーマまたは API 設計がレジストリーのアーティファクトとして追加されると、クライアントアプリケーションはそのスキーマまたは API デザインを使用して、実行時にクライアントメッセージが正しいデータ構造に準拠することを確認できます。
Service Registry は、標準のイベントスキーマおよび API 仕様の幅広いメッセージペイロード形式をサポートしています。たとえば、サポートされている形式には、Apache Avro、Google Protobuf、GraphQL、AsyncAPI、OpenAPI などがあります。
スキーマと API のグループ
アーティファクトグループ は、スキーマまたは API アーティファクトのオプションの名前付きコレクションです。各グループには、論理的に関連したスキーマまたは API 設計のセットが含まれており、通常、特定のアプリケーションまたは組織に属する単一のエンティティーにより管理されます。
スキーマと API 設計を追加するときに、オプションのアーティファクトグループを作成して、Service Registry でそれらを整理できます。たとえば、development および production アプリケーション環境、あるいは sales および engineering 組織に一致するグループを作成できます。
スキーマおよび API グループには複数のアーティファクトタイプを含めることができます。たとえば、Protobuf、Avro、JSON スキーマ、OpenAPI、または AsyncAPI アーティファクトをすべて同じグループに含めることができます。
Service Registry Web コンソール、コア REST API、コマンドライン、Maven プラグイン、または Java クライアントアプリケーションを使用して、スキーマと API アーティファクトおよびグループを作成できます。次の簡単な例は、レジストリーコア REST API の使用を示しています。
$ curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
-H "X-Registry-ArtifactId: share-price" \
--data '{"type":"record","name":"price","namespace":"com.example", \
"fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts
この例では、my-group という名前のアーティファクトグループを作成し、アーティファクト ID が share-price の Avro スキーマを追加します。
Service Registry Web コンソールを使用する場合にグループの指定は任意です。この場合、default グループが自動的に作成されます。REST API または Maven プラグインを使用し、一意のグループを作成したくない場合は API パスで default グループを指定します。
関連情報
- スキーマおよびグループの詳細は、Cloud Native Computing Foundation (CNCF) Schema Registry API を参照してください。
- Service Registry コア REST API の詳細は、Apicurio Registry REST API のドキュメント を参照してください。
他のスキーマと API への参照
一部の Service Registry アーティファクトタイプには、別のアーティファクトファイルへの アーティファクト参照 を含めることができます。再利用可能なスキーマまたは API コンポーネントを定義し、それらを複数の場所から参照して効率を高めることができます。たとえば、$ref ステートメントを使用して JSON スキーマまたは OpenAPI で参照を指定したり、import ステートメントを使用して Google protobuf で参照を指定したり、ネストされた名前空間を使用して Apache Avro で参照を指定したりできます。
次の例は、ネストされた名前空間を使用して Exchange という名前の別のスキーマへの参照を含む、TradeKey という名前の単純な Avro スキーマを示しています。
ネストされた Exchange スキーマを持つ TradeKey スキーマ
{
"namespace": "com.kubetrade.schema.trade",
"type": "record",
"name": "TradeKey",
"fields": [
{
"name": "exchange",
"type": "com.kubetrade.schema.common.Exchange"
},
{
"name": "key",
"type": "string"
}
]
}
交換スキーマ
{
"namespace": "com.kubetrade.schema.common",
"type": "enum",
"name": "Exchange",
"symbols" : ["GEMINI"]
}
アーティファクト参照は、アーティファクトタイプ固有の参照から内部 Service Registry 参照にマップされるアーティファクトメタデータのコレクションとしてService Registry に格納されます。Service Registry の各アーティファクト参照は、以下で構成されます。
- グループ ID
- アーティファクト ID
- アーティファクトのバージョン
- アーティファクト参照名
Service Registry コア REST API、Maven プラグイン、および Java シリアライザー/デシリアライザー (SerDes) を使用して、アーティファクト参照を管理できます。Service Registry は、アーティファクトコンテンツとともにアーティファクト参照を保存します。Service Registry は、すべてのアーティファクトリーファレンスのコレクションも保持しているため、コレクションを検索したり、特定のアーティファクトのすべてのリファレンスを一覧表示したりできます。
サポートされているアーティファクトタイプ
Service Registry は現在、次のアーティファクトタイプのアーティファクトリーファレンスのみをサポートしています。
- Avro
- Protobuf
- JSON スキーマ
関連情報
アーティファクト参照の管理の詳細は、以下を参照してください。
- Java コードの例については、Apicurio Registry SerDes with references を参照してください。