1.2. Service Registry のスキーマと API アーティファクト

イベントスキーマや API 設計などの Service Registry に保存される項目は、レジストリーアーティファクトと呼ばれます。以下は、単純な株価アプリケーションの JSON 形式の Apache Avro スキーマアーティファクトの例を示しています。

{
   "type": "record",
   "name": "price",
   "namespace": "com.example",
   "fields": [
       {
           "name": "symbol",
           "type": "string"
       },
       {
           "name": "price",
           "type": "string"
       }
   ]
}

{
   "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

$ 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 スキーマを追加します。

他のスキーマと API への参照

一部の Service Registry アーティファクトタイプには、別のアーティファクトファイルへの アーティファクト参照 を含めることができます。再利用可能なスキーマまたは API コンポーネントを定義し、それらを複数の場所から参照して効率を高めることができます。たとえば、$ref ステートメントを使用して JSON スキーマまたは OpenAPI で参照を指定したり、import ステートメントを使用して Google protobuf で参照を指定したり、ネストされた名前空間を使用して Apache Avro で参照を指定したりできます。

次の例は、ネストされた名前空間を使用して Exchange という名前の別のスキーマへの参照を含む、TradeKey という名前の単純な Avro スキーマを示しています。

{
 "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.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"]
}

{
 "namespace": "com.kubetrade.schema.common",
 "type": "enum",
 "name": "Exchange",
 "symbols" : ["GEMINI"]
}

アーティファクト参照は、アーティファクトタイプ固有の参照から内部 Service Registry 参照にマップされるアーティファクトメタデータのコレクションとしてService Registry に格納されます。Service Registry の各アーティファクト参照は、以下で構成されます。

Service Registry コア REST API、Maven プラグイン、および Java シリアライザー/デシリアライザー (SerDes) を使用して、アーティファクト参照を管理できます。Service Registry は、アーティファクトコンテンツとともにアーティファクト参照を保存します。Service Registry は、すべてのアーティファクトリーファレンスのコレクションも保持しているため、コレクションを検索したり、特定のアーティファクトのすべてのリファレンスを一覧表示したりできます。

サポートされているアーティファクトタイプ

Service Registry は現在、次のアーティファクトタイプのアーティファクトリーファレンスのみをサポートしています。