検索

第12章 Kafka Bridge

download PDF

本章では、Red Hat Enterprise Linux 上の AMQ Streams Kafka Bridge の概要を紹介し、その REST API を使用して AMQ Streams と対話する方法を説明します。ローカル環境で Kafka Bridge を試すには、本章で後述する 「Kafka Bridge クイックスタート」 を参照してください。

その他のリソース

12.1. Kafka Bridge の概要

Kafka Bridge では、HTTP ベースのクライアントと Kafka クラスターとの対話を可能にする RESTful インターフェースが提供されます。また、クライアントアプリケーションによる Kafka プロトコルの変換は必要なく、Web API コネクションの利点が AMQ Streams に提供されます。

API には主に 2 つの resources-consumerstopics-- があります。これは、Kafka クラスターでコンシューマーおよびプロデューサーと対話するためにエンドポイント経由で公開され、アクセスが可能になります。リソースと関係があるのは Kafka ブリッジのみで、Kafka に直接接続されたコンシューマーやプロデューサーとは関係はありません。

HTTP リクエスト

Kafka Bridge は、以下の方法で Kafka クラスターへの HTTP リクエストをサポートします。

  • トピックにメッセージを送信する。
  • トピックからメッセージを取得する。
  • トピックのパーティションリストを取得する。
  • コンシューマーを作成および削除する。
  • コンシューマーをトピックにサブスクライブし、このようなトピックからメッセージを受信できるようにする。
  • コンシューマーがサブスクライブしているトピックの一覧を取得する。
  • トピックからコンシューマーのサブスクライブを解除する。
  • パーティションをコンシューマーに割り当てる。
  • コンシューマーオフセットの一覧をコミットする。
  • パーティションで検索して、コンシューマーが最初または最後のオフセットの位置、または指定のオフセットの位置からメッセージを受信できるようにする。

上記の方法で、JSON 応答と HTTP 応答コードのエラー処理を行います。メッセージは JSON またはバイナリー形式で送信できます。

クライアントは、ネイティブの Kafka プロトコルを使用する必要なくメッセージを生成して使用できます。

AMQ Streams インストールと同様に、Red Hat Enterprise Linux にインストールする Kafka Bridge ファイルをダウンロードできます。「Kafka Bridge アーカイブのダウンロード」 を参照してください。

KafkaBridge リソースのホストおよびポートの設定に関する詳細は、「Kafka Bridge プロパティーの設定」 を参照してください。

12.1.1. 認証および暗号化

HTTP クライアントと Kafka Bridge 間の認証と暗号化はまだサポートされていません。そのため、クライアントから Kafka Bridge に送信されるリクエストは以下のようになります。

  • 暗号化されず、HTTPS ではなく HTTP を使用する必要がある。
  • 認証なしで送信される。

Kafka Bridge と Kafka クラスターとの間で TLS または SASL ベースの認証を設定できます

プロパティーファイルを介して認証用に Kafka Bridge を設定します。

12.1.2. Kafka Bridge へのリクエスト

データ形式と HTTP ヘッダーを指定し、有効なリクエストが Kafka Bridge に送信されるようにします。

API リクエストおよびレスポンス本文は、常に JSON としてエンコードされます。

12.1.2.1. コンテンツタイプヘッダー

すべてのリクエストについて Content-Type ヘッダーを提出する必要があります。唯一の例外は、POST リクエストボディーが空で、Content-Type ヘッダーを追加するとリクエストが失敗します。

コンシューマー操作(/consumers エンドポイント)およびプロデューサー操作(エンドポイント)には異なる/topics ヘッダーが必要です。Content-Type

コンシューマー操作の Content-Type ヘッダー

埋め込みデータ形式に関係なく、リクエストボディーにデータが含まれる場合に、コンシューマー操作のPOST リクエストは以下の Content-Type ヘッダーを提供する必要があります。

Content-Type: application/vnd.kafka.v2+json

プロデューサー操作の Content-Type ヘッダー

プロデューサー操作の実行時に、POST リクエストは、生成されたメッセージの 埋め込みデータ形式 を指定する Content-Type ヘッダーを提供する必要があります。これは、json または binary のいずれかになります。

表12.1 データ形式のコンテンツタイプヘッダー
埋め込みデータ形式Content-Type ヘッダー

JSON

Content-Type: application/vnd.kafka.json.v2+json

バイナリー

Content-Type: application/vnd.kafka.binary.v2+json

次のセクションで説明どおり、埋め込みデータ形式はコンシューマーごとに設定されます。

POST リクエストに空のボディーがある場合は、Content-Type を設定しないでください。空のボディーを使用して、デフォルト値のコンシューマーを作成できます。

12.1.2.2. 埋め込みデータ形式

埋め込みデータ形式は、Kafka メッセージが Kafka Bridge によりプロデューサーからコンシューマーに HTTP で送信される際の形式です。サポートされる埋め込みデータ形式には、JSON またはバイナリーの 2 つがサポートされます。

/consumers/groupid エンドポイントを使用してコンシューマーを作成する場合、POST リクエスト本文で JSON またはバイナリーいずれかの埋め込みデータ形式を指定する必要があります。これは、要求ボディーの format フィールドに指定されます。以下に例を示します。

{
  "name": "my-consumer",
  "format": "binary", 1
...
}
1
バイナリー埋め込みデータ形式。

コンシューマーの埋め込みデータ形式が指定されていない場合は、バイナリー形式が設定されます。

コンシューマーの作成時に指定する埋め込みデータ形式は、コンシューマーが消費する Kafka メッセージのデータ形式と一致する必要があります。

バイナリー埋め込みデータ形式を指定する場合は、以降のプロデューサーリクエストで、リクエスト本文にバイナリーデータが Base64 でエンコードされた文字列として含まれる必要があります。たとえば、POST 要求を /topics/topicname エンドポイントに指定してメッセージを送信する場合は、value を Base64 でエンコードする必要があります。

{
  "records": [
    {
      "key": "my-key",
      "value": "ZWR3YXJkdGhldGhyZWVsZWdnZWRjYXQ="
    },
  ]
}

プロデューサーリクエストは、埋め込みデータ形式に対応する Content-Type ヘッダーも提供する必要があります (例: Content-Type: application/vnd.kafka.binary.v2+json)。

12.1.2.3. メッセージの形式

/topics エンドポイントを使用してメッセージを送信する場合は、records パラメーターでリクエストボディーにメッセージペイロードを入力します。

records パラメーターには、以下のオプションフィールドを含めることができます。

  • メッセージの key
  • メッセージの value
  • 宛先の partition
  • メッセージの headers

トピックへの POST リクエストの例

curl -X POST \
  http://localhost:8080/topics/my-topic \
  -H 'content-type: application/vnd.kafka.json.v2+json' \
  -d '{
    "records": [
        {
            "key": "my-key",
            "value": "sales-lead-0001"
            "partition": 2
            "headers": [
              {
                "key": "key1",
                "value": "QXBhY2hlIEthZmthIGlzIHRoZSBib21iIQ==" 1
              }
            ]
        },
    ]
}'

1
バイナリー形式のヘッダー値。Base64 としてエンコードされます。

12.1.2.4. Accept ヘッダー

コンシューマーを作成したら、以降のすべての GET リクエストには Accept ヘッダーが以下のような形式で含まれる必要があります。

Accept: application/vnd.kafka.embedded-data-format.v2+json

embedded-data-format は、json または binary のいずれかです。

たとえば、サブスクライブされたコンシューマーのレコードを JSON 埋め込みデータ形式で取得する場合、この Accept ヘッダーが含まれるようにします。

Accept: application/vnd.kafka.json.v2+json

12.1.3. Kafka Bridge のロガーの設定

AMQ Streams Kafka ブリッジでは、関連する OpenAPI 仕様によって定義される操作ごとに異なるログレベルを設定できます。

それぞれの操作には、ブリッジが HTTP クライアントから要求を受信する対応する API エンドポイントがあります。各エンドポイントのログレベルを変更すると、受信および送信 HTTP 要求に関する詳細なログ情報を生成することができます。

ロガーは log4j.properties ファイルで定義されます。このファイルには healthy および ready エンドポイントの以下のデフォルト設定が含まれています。

log4j.logger.http.openapi.operation.healthy=WARN, out
log4j.additivity.http.openapi.operation.healthy=false
log4j.logger.http.openapi.operation.ready=WARN, out
log4j.additivity.http.openapi.operation.ready=false

その他すべての操作のログレベルは、デフォルトで INFO に設定されます。ロガーは以下のようにフォーマットされます。

log4j.logger.http.openapi.operation.<operation-id>

ここで、<operation-id> は特定の操作の識別子です。以下は、OpenAPI 仕様によって定義される操作の一覧です。

  • createConsumer
  • deleteConsumer
  • subscribe
  • unsubscribe
  • poll
  • assign
  • commit
  • send
  • sendToPartition
  • seekToBeginning
  • seekToEnd
  • seek
  • healthy
  • ready
  • openapi

12.1.4. Kafka Bridge API リソース

リクエストやレスポンスの例などを含む REST API エンドポイントおよび説明の完全リストは、「Kafka Bridge API reference」を参照してください。

12.1.5. Kafka Bridge アーカイブのダウンロード

AMQ Streams Kafka Bridge の zip 形式のディストリビューションは、Red Hat の Web サイトからダウンロードできます。

12.1.6. Kafka Bridge プロパティーの設定

この手順では、AMQ Streams Kafka Bridge によって使用される Kafka および HTTP 接続プロパティーを設定する方法を説明します。

Kafka 関連のプロパティーの適切な接頭辞を使用して、他の Kafka クライアントとして Kafka Bridge を設定します。

  • kafka. サーバー接続やセキュリティーなどのプロデューサーとコンシューマーに適用される一般的な設定。
  • kafka.consumer. コンシューマーのみに渡されるコンシューマー固有の設定。
  • kafka.producer. プロデューサー固有の設定では、プロデューサーのみに渡されます。

HTTP プロパティーは、Kafka クラスターへの HTTP アクセスを有効にする他に、CPRS (Cross-Origin Resource Sharing) により Kafka Bridge のアクセス制御を有効化または定義する機能を提供します。CORS は、複数のオリジンから指定のリソースにブラウザーでアクセスできるようにする HTTP メカニズムです。CORS を設定するには、許可されるリソースオリジンのリストと、それらにアクセスする HTTP メソッドを定義します。リクエストの追加の HTTP ヘッダーには Kafka クラスターへのアクセスが許可されるオリジンが記述 されています。

手順

  1. AMQ Streams Kafka Bridge インストールアーカイブで提供される application.properties ファイルを編集します。

    プロパティーファイルを使用して Kafka および HTTP 関連のプロパティーを指定し、分散トレーシングを有効にします。

    1. Kafka コンシューマーやプロデューサー固有のプロパティーなど、標準の Kafka 関連のプロパティーを設定します。

      以下を使用します。

    2. HTTP 関連のプロパティーを設定し、Kafka クラスターへの HTTP アクセスを有効にします。

      以下に例を示します。

      http.enabled=true
      http.host=0.0.0.0
      http.port=8080 1
      http.cors.enabled=true 2
      http.cors.allowedOrigins=https://strimzi.io 3
      http.cors.allowedMethods=GET,POST,PUT,DELETE,OPTIONS,PATCH 4
      1
      8080 番ポートで Kafka Bridge をリッスンするデフォルトの HTTP 設定。
      2
      CORS を有効にするには true に設定します。
      3
      許可される CORS オリジンのコンマ区切りリスト。URL または Java 正規表現を使用できます。
      4
      CORS で許可される HTTP メソッドのコンマ区切りリスト。
    3. 分散トレースを有効または無効にします。

      bridge.tracing=jaeger

      プロパティーからコードコメントを削除して、分散トレースを有効にします。

12.1.7. Kafka Bridge のインストール

以下の手順に従って、Red Hat Enterprise Linux に AMQ Streams Kafka Bridge をインストールします。

手順

  1. まだ設定していない場合は、AMQ Streams Kafka Bridge インストールアーカイブを任意のディレクトリーに展開します。
  2. 設定プロパティーをパラメーターとして使用して、Kafka Bridge スクリプトを実行します。

    以下に例を示します。

    ./bin/kafka_bridge_run.sh --config-file=_path_/configfile.properties
  3. ログインでインストールが正常に行われたことを確認します。

    HTTP-Kafka Bridge started and listening on port 8080
    HTTP-Kafka Bridge bootstrap servers localhost:9092
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.