1. Home
  2. Cloud
  3. Confluent Cloud でのスキーマの操作

重要

このページの日本語コンテンツは古くなっている可能性があります。最新の英語版コンテンツをご覧になるには、こちらをクリックしてください。

Confluent Cloud でのスキーマの管理

Looking for Confluent Platform Schema Management docs? You are currently viewing Confluent Cloud documentation. If you are looking for Confluent Platform docs, check out Schema Management on Confluent Platform.

ちなみに

組み込みの Confluent Cloud 対話型チュートリアルをお試しください。 すぐに試す場合は、このリンクを使用して Confluent Cloud にサインアップまたはサインイン し、Confluent Cloud でガイド付きワークフローを直接ご利用ください。

スキーマ管理 は Confluent Cloud で完全にサポートされており、環境ごとにホストされている スキーマレジストリ を使用します。また、ストリームガバナンスの概要 の重要な要素です。

スキーマの操作

Confluent Cloud でトピックのスキーマを管理できます。

これ以降のセクションでは、スキーマレジストリ が有効になっていることを想定しています。スキーマにまだ慣れていない場合は、まず「Confluent Cloud のスキーマ管理のクイックスタート」で スキーマレジストリ を有効にする方法を確認し、基本的なタスクのワークフロー例を試してみてください。

スキーマを表示する

特定のトピックのスキーマの詳細を表示します。

スキーマの検索

スキーマを探して表示するのにスキーマを検索することもできます。検索は環境とクラスターをまたいでグローバルに行われます。

  1. スキーマサブジェクト名、データレコード、またはデータフィールド名を上部の検索バーに入力します。入力が進むにつれ、トピックなどの他のエンティティも含めて結果が表示されます。

    ../_images/cloud-02a-search-schema.png

  2. Enter を押して、スキーマなどのエンティティを選択します。

    ../_images/cloud-02b-search-schema.png

詳細については、「データとスキーマの検索」を参照してください。

環境ビューでのスキーマ検索

  1. 環境に移動します。

  2. View and manage schemas をクリックして、環境にあるすべてのスキーマをリスト表示します。

    ../_images/cloud-02c-view-manage-schemas.png

  3. 表示するスキーマを選択します。

    ../_images/cloud-02d-view-schemas-list.png

ツリービューとコードビュー

スキーマの表示には 2 種類のビューを使用できます。

  • ツリービュー
  • 編集可能なコードビュー

ビューを切り替えるには、スキーマレベルの検索ボックスの左にあるボックスをクリックします。

../_images/cloud-sr-schema-tree-toggle-icon-captions.ja.png

デフォルトで、スキーマはツリービュー形式で表示されます。このビューでは、スキーマの構造の把握や、要素と下位要素からなる階層の移動ができます。

../_images/cloud-sr-schema-tree-view.png

ツリービューでは以下の操作ができます。

  • 展開と下位要素の表示。要素の左側にある矢印を使用します。
  • 利用可能なタグの適用と管理。タグについては「データとスキーマのタグ付け」で説明しています。

編集モード（"コードビュー"）では、スキーマの作成と編集を実行できます。これについては、以下のセクションで説明します。

../_images/cloud-sr-schema-code-view.png

トピックのスキーマを作成する

キースキーマと値スキーマを作成します。通常、値スキーマはキースキーマよりも高い頻度で作成されます。

ベストプラクティス:

  • 後方互換性を容易にするために、フィールドにはデフォルト値を指定します（スキーマが関係する場合）。
  • スキーマの内容を人間が理解できるように、少なくとも不明瞭なフィールドに関する説明を記入します。

ちなみに

また、統合 Confluent CLI からスキーマを作成することもできます。この方法については、クイックスタートの「スキーマを作成する」セクションに記載されています。こちら に便利なコマンドリファレンスがあります。

トピックの値スキーマを作成する

  1. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します（または新規作成します）。

  2. Schema タブをクリックします。

    ../_images/cloud-03-set-msg-value-schema.png

  3. Set a schema をクリックします。スキーマエディターが表示されます。

    ../_images/cloud-04-schema-value-editor.png

  4. スキーマのタイプを JSON、Avro、Protobuf から選択します（デフォルトは Avro です）。

  5. スキーマ の基本構造があらかじめ入力された状態でエディターに表示されます。これをベースに作業を進めます。スキーマをエディターに入力します。

    • name: サブジェクトの命名方法によって決定されるデフォルトのスキーマ名を変更する場合は、名前を入力します。デフォルトは、schema_type_topic_name です。これは必須です。

    • type: record、enum、union、array、map、または fixed のいずれか。（type に record を選択する場合はスキーマのトップレベルで指定され、データ型が異なる複数のフィールドを含めることができます。）これは必須です。

    • namespace: スキーマの命名の競合を防止するための完全修飾名。スキーマの name を修飾する文字列です。これは省略可能ですが、推奨されています。

    • fields: 1 つのレコードの 1 つ以上のフィールドをリストした JSON 配列。これは必須です。

      各フィールドには、以下の属性を指定できます。

      • name: フィールドの名前。これは必須です。
      • type: フィールドのデータ型。これは必須です。
      • doc: フィールドのメタデータ。これは省略可能ですが、推奨されています。
      • default: フィールドのデフォルト値。これは省略可能ですが、推奨されています。
      • order: フィールドのソート順序。有効な値は、ascending、descending、または ignore のいずれかです。デフォルト: Ascending。これは省略可能です。
      • aliases: フィールドの別名。これは省略可能です。

    たとえば、以下のシンプルなスキーマを追加できます。

    {
  "type": "record",
  "name": "value_my_new_widget",
  "fields": [
    {
      "name": "name",
      "type": "string"
    }
  ]
}

    これは、Confluent Cloud では以下のように表示されます。

    ../_images/cloud-05-entered-schema.png

    編集モードでは、次のオプションがあります。

    • Validate では、スキーマの作成前に、スキーマの構文と構造を検証できます。
    • Add schema references では、ガイド付きウィザードでスキーマ参照を追加できます。

  6. Create をクリックします。

    • 入力したスキーマが有効な場合は、スキーマが正常に保存され、Schema updated というメッセージが短時間バナー領域に表示されます。スキーマが保存され、ツリービュー形式で表示されています。

      ../_images/cloud-06-schema-updated.png

    • 入力したスキーマが無効な場合は、エディターで解析エラーが強調表示されます（この例では、中かっこが不足しています）。解析エラーが自動的に強調表示されない場合は、警告バナーの See error messages リンクをクリックすると有効になります。

      ../_images/cloud-schema-invalid-avro-warning-banner.png
      ../_images/cloud-07-schema-invalid-avro.png

必要に応じて、トピックのキースキーマ についても、この手順を繰り返します。

スキーマ参照の操作

ウィザードを使用して、使用可能なスキーマとバージョンを指定し、別のスキーマへの参照を追加することができます。

../_images/cloud-05a-schema-references.png

Reference name フィールドに入力する参照名は、使用しているスキーマフォーマットのガイドラインに従って、ターゲットスキーマと一致している必要があります。

  • JSON スキーマでは、名前は参照先スキーマの $ref フィールドの値です。
  • Avro では、名前は参照先スキーマのフルネームです。これは、参照先スキーマの name フィールドの値です。
  • Protobuf では、名前は参照先スキーマの Import ステートメントの値です。

まず、参照するスキーマを見つけて、それに対応する参照名を取得します。

エディターで現在のスキーマにスキーマ参照を追加する

  1. Add reference をクリックします。
  2. 上記のルールに従って参照名を入力します。
  3. Subject のリストからスキーマを選択します。
  4. Version で、使用するスキーマのバージョンを選択します。
  5. Validate をクリックして、正常に参照できることを確認します。
  6. Save をクリックして、参照を保存します。

たとえば、widget スキーマから employees トピックのスキーマ（Employee）への参照を作成するには、次のように Employee への参照を構成できます。

../_images/cloud-05b-schema-references.png

詳細については、Confluent Platform ドキュメントの「スキーマ参照」を参照してください。

トピックのスキーマ参照を表示、編集、または削除する

既存のスキーマ参照は、その参照が構成されているスキーマの編集可能なバージョンに表示されます。

  1. トピックを開きます。たとえば、前の例では、widget-value スキーマが widget トピックと関連付けられていました。

  2. スキーマを編集するときと同じように、エディターをクリックします。

    このスキーマで他のスキーマへの参照が構成されている場合、エディターの下の Schema references のリストに表示されます。

    このビューから、このスキーマに参照を追加すること、既存の参照を編集すること、参照を削除することもできます。

トピックのキースキーマを作成する

  1. Key オプションをクリックします。メッセージのキースキーマを設定するよう求められます。

    ../_images/cloud-08-set-msg-key-schema.png

  2. Set a schema をクリックします。

  3. Avro フォーマットを選択します。または、サンプルフォーマットを削除し、文字列の UUID を貼り付けます。

  4. スキーマをエディターに入力し、Save をクリックします。

    以下は、キー値に適したスキーマの例です。

    {
  "namespace": "io.confluent.examples.clients.basicavro",
  "name": "key_widget",
  "type": "string"
}

キー値のベストプラクティスと誤り

Kafka のメッセージは、キー/値ペアです。メッセージのキーとメッセージの値は、別々にシリアライズすることができます。例えば、値では Avro record を使用し、キーではプリミティブ（string や integer など）を使用することもできます。通常、メッセージのキー（使用されている場合）はプリミティブです。どのようにキーを設定するかは、お客様と、お客様の実装の要件によって異なります。

ベストプラクティスとして、キー値のスキーマは、複雑さを最小限に留めることをお勧めします。シンプルでシリアル化されないデータ型（string の UUID、long の ID など）を使用するか、またはマップや配列をフィールドとして使用しない Avro レコードを使用します（以下の例を参照）。Protobuf メッセージや JSON オブジェクトはキー値に使用しないでください。Avro では、マップや配列に対する決定的なシリアル化が保証されません。また、Protobuf と JSON Schema フォーマットでは、あらゆるオブジェクトに対する決定的なシリアル化が保証されません。これらのフォーマットをキー値に使用すると、トピックのパーティショニングに支障をきたします。詳細については、Confluent Community フォーラムの「Partitioning gotchas」を参照してください。

キーと値のスキーマの詳細な例については、スキーマレジストリ のドキュメントの「スキーマ形式、シリアライザー、逆シリアライザー」を参照してください。

スキーマの編集

トピックの既存のスキーマを編集します。

  1. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します。

  2. Schema タブをクリックします。

  3. スキーマで Key または Value オプションを選択します。

  4. デフォルトでツリービューが表示されます。

    ../_images/cloud-schema-tree-view.png

  5. Evolve Schema をクリックします。

    ../_images/cloud-schema-code-view.png

  6. スキーマエディターで変更を行います。

    たとえば、region という名前の新しいフィールドを追加して既存のスキーマを編集することができます。

    {
  "fields": [
    {
      "name": "name",
      "type": "string"
    },
    {
      "name": "region",
      "type": "string",
      "default": ""
    }
  ],
  "name": "value_widgets",
  "type": "record"
}

    編集モードでは、次のオプションがあります。

    ちなみに

    互換モードが 後方互換 に設定されている場合は、新しいフィールドにデフォルトを指定する必要があります。そうすると、コンシューマーアプリケーションが、Version 1 のスキーマに従って書き込まれた古いメッセージ（name フィールドのみのもの）と Version 2 のスキーマに従って構成された新しいメッセージ（name フィールドと region フィールドを含むもの）の両方を読み取れるようになります。Version 1 のスキーマと一致し、name の値のみが含まれているメッセージの場合、region は空になります。詳細については、Confluent Cloud スキーマレジストリ チュートリアルの「互換性チェックでの合格」を参照してください。

  7. Save をクリックします。

    • スキーマのアップデートが有効であり、前のバージョンとの互換性がある場合は（後方互換モードを想定）、スキーマがアップデートされ、バージョンのカウントが増えます。スキーマを バージョン間で比較 することができます。

      ../_images/cloud-09-schema-version-updated.png

    • スキーマの更新が無効な場合や、スキーマの前のバージョンとの互換性がない場合は、エディターで解析エラーが強調表示されます。解析エラーが自動的に強調表示されない場合は、警告バナーの See error messages リンクをクリックすると有効になります。

      たとえば、前の手順で説明したように、新しいフィールドを追加するときにデフォルト値を指定しなかった場合は、互換性がないことを示すエラーが表示されます。この場合は、"region" にデフォルト値を追加することで解決できます。

      ../_images/cloud-schema-invalid-avro-warning-banner.png
      ../_images/cloud-10-schema-incompatible.png

スキーマのバージョンの比較

スキーマのバージョンを比較して、その進化の違いを表示します。

  1. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します。

  2. Schema タブをクリックします。

  3. スキーマで Key または Value オプションを選択します。（デフォルトでは、Value が表示されます。）

    ../_images/cloud-11a-schema-version-newest.png

  4. Compare version をクリックします。

    スキーマの現在のバージョン番号がバージョンメニューに示されています。

    ../_images/cloud-11b-schema-version-history-choose.png

  5. Turn on version diff チェックボックスをオンにします。

  6. 比較するバージョンを、各バージョンメニューから選択します。比較の差異が強調表示されます。

    ../_images/cloud-12-schema-compare.png

スキーマのサブジェクトレベル（トピックごと）の互換性モードの変更

デフォルトの互換モードは Backward です。トピックのスキーマのモードはすべて、必要に応じて変更することができます。

注意

既に本稼働環境で使用されている既存のスキーマの互換性モードを変更すると、アプリケーションの互換性が失われる可能性があるのでご注意ください。

このセクションでは、サブジェクトレベルの互換性モードを変更する方法を説明します。環境内のすべてのスキーマにグローバルに互換性を設定する こともできます。ただし、そのようなグローバルの設定は、以下で説明するサブジェクトレベルの互換性の設定でオーバーライドされます。

  1. 環境を選択します。

  2. クラスターを選択します。

  3. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します。

  4. トピックの Schema タブをクリックします。

  5. スキーマで Key または Value オプションを選択します。

  6. 右上の省略符号（3 つの点）をクリックしてメニューを表示し、Compatibility settings を選択します。

    ../_images/cloud-13a-schema-compat-mode-menu.png

    Compatibility settings が表示されます。

    ../_images/cloud-13a-schema-compat-update.png

  7. モードのオプションを選択します。

    説明には、各オプションの互換性の動作が示されています。各オプションで許可される変更などの詳細については、「スキーマの進化と互換性」を参照してください。

  8. Save をクリックします。

スキーマとフィールドの検索

Confluent Cloud では、スキーマや関連メタデータなど、さまざまな種類のエンティティを、複数の環境やクラスターをまたいでグローバルに検索できます。詳細については、「ストリームカタログ」の「データとスキーマの検索」を参照してください。

スキーマとフィールドのタグ付け

Confluent Cloud には、カスタムタグ名と一般的に使われているタグ名の両方に基づいてデータを整理およびカタログ化する手段として、スキーマ内のバージョンとフィールドをタグ付けする機能が用意されています。タグ付けの詳細については、「ストリームカタログ」の「データとスキーマのタグ付け」を参照してください。

Confluent Cloud からのスキーマの削除

  1. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します。

  2. Schema タブをクリックします。

  3. スキーマで Key または Value オプションを選択します。

  4. 右上の省略符号（3 つの点）をクリックしてメニューを表示し、Delete を選択します。

    ../_images/cloud-14-schema-delete-menu.png

  5. ダイアログで、スキーマの特定のバージョンのみ、またはサブジェクト全体（すべてのバージョン）のどちらを削除するかを選択します。

    ../_images/cloud-14-schema-delete-dialog.png

  6. Delete を選択すると、処理が実行されます。

スキーマの削除の詳細については、「スキーマ削除のガイドライン」を参照してください。

ブローカー側のスキーマ検証の使用

トピックごとにスキーマ検証を有効にすると、該当するトピックに対して生成されたデータが有効なスキーマ ID を使用しているかどうかをブローカー側で確認できます。スキーマ検証は Confluent Cloud の専用クラスターでのみ使用できます。スキーマ検証向けにトピックを構成する方法を確認し、チュートリアルを試す場合は、「Confluent Cloud でのブローカー側のスキーマ検証の使用」のガイド全体を参照してください。

Schema Linking

Confluent Cloud は、スキーマレジストリ クラスター全体でスキーマを同期したままにしておくための Schema Linking に対応するようになりました。その仕組みを確認し、ウォークスルーの例を試してみるには、「Confluent Cloud の Schema Linking」のガイド全体を参照してください。

Confluent Cloud からのスキーマのダウンロード

  1. ナビゲーションメニューで Topics をクリックしてから、トピックをクリックして選択します。

  2. Schema タブをクリックします。

  3. スキーマで Key または Value オプションを選択します。

  4. 右上の省略符号（3 つの点）をクリックしてメニューを表示し、Download を選択します。

    ../_images/cloud-15-schema-download-menu.png

    トピックのスキーマの JSON ファイルは、Downloads ディレクトリにダウンロードされます。

    たとえば、クイックスタートから employees トピックのスキーマ のバージョン 1 をダウンロードした場合、schema-employees-value-v1.avsc という名前のファイルを入手でき、次の内容が含まれます。

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

ちなみに

ファイル拡張子は、スキーマの形式 を示しています。Avro スキーマの場合のファイル拡張子は .avsc、Protobuf スキーマの場合は .proto、JSON スキーマの場合は .json です。

Confluent Cloud 環境のスキーマの管理

スキーマレジストリ 自体は環境レベルでホストされ、1 つの環境内のすべてのクラスターに対してサービスを提供します。そのため、スキーマに関連する複数のタスクが、このレベルのレジストリで管理されます。

Confluent Cloud 環境の スキーマレジストリ を表示し、管理するには、以下の手順に従います。

  1. Home ページで環境を選択します（右上のメニューから環境のリストを表示できます）。

  2. Schema Registry タブをクリックします。

    Schema Registry 設定のスクリーンショット

以下の方法については、Confluent Cloud クイックスタートの「環境のスキーマを構成および管理する」を参照してください。

Confluent Cloud Schema Registry でサポートされている機能と制限

  • スキーマレジストリ は、環境ごとに 1 つ使用できます。
  • スキーマレジストリ へのアクセス制御は、API キーとシークレットに基づきます。
  • スキーマレジストリ を有効にするには、各環境に Apache Kafka® クラスターが少なくとも 1 つ必要です。
  • VPC から Confluent Cloud Schema Registry のパブリックインターネットエンドポイントに通信できなければなりません。詳細については、VPC ピアリング環境での Confluent Cloud Schema Registry の使用 を参照してください。
  • 米国、欧州、APAC のクラウドプロバイダー地域のアマゾンウェブサービス（AWS）、Azure（Microsoft Azure）、GCP（Google Cloud Platform）で利用可能です。クラウドプロバイダーごとに、各地域が内部的に特定のリージョンにマップされています（「Confluent Cloud で スキーマレジストリ を有効化する を参照」）。
  • API 要求数のレート制限は、API キーごとに 1 秒あたり 25 個です。
  • 高可用性（HA）は、各ノードを別々のアベイラビリティゾーン（AZ）で実行して、クラスター内部で常に複数のノードを稼働状態することで実現されます。