1. Home
  2. Platform
  3. Confluent REST API

Confluent REST API

Confluent REST Proxy は Apache Kafka® クラスターへの RESTful インターフェイスを提供するため、ネイティブの Kafka プロトコルやクライアントを使用せずに、メッセージの生成や消費、クラスターのステートの表示、管理アクションの実行を簡単に行うことができます。

以下にユースケースの例をいくつか示します。

  • 公式の Confluent クライアント がサポートしていない言語で構築されたフロントエンドアプリから Kafka へのデータレポート
  • まだ Kafka をサポートしていないストリーム処理フレームワークへのメッセージの取り込み
  • 管理アクションのスクリプト化

Confluent REST Proxy には、着信リクエストの認証を支援し、認証されたプリンシパルを Kafka リクエストに伝播するプラグインがあります。これにより、Confluent REST Proxy クライアントは、Kafka ブローカーのマルチテナントセキュリティ機能を利用できるようになります。詳細については、「REST Proxy のセキュリティ」および「REST Proxy セキュリティプラグイン」を参照してください。

トピックの作成と管理、MDS の管理、トピックに対する生成と消費は、Admin REST APIs で行うことができます。Admin REST API は、次の形態で利用できます。

  • Confluent Server をデプロイすると、ブローカーに対しデフォルトで直接 Admin REST API が公開されます。Confluent Server は Confluent Enterprise に同梱されています。
  • スタンドアロンの REST Proxy ノードをデプロイすると、Produce API と Consume API に加え、API v3 時点の Admin REST API が提供されます。
  • Admin REST APIs は Confluent Cloud に段階的に追加されています。Confluent Cloud のドキュメントを参照してください。

詳細については、チュートリアル『Getting Started with Apache Kafka and Confluent REST Proxy』を参照してください。

機能

Confluent REST APIs では現在、次の機能が公開され、利用できるようになっています。

  • メタデータ - クラスターに関するほとんどのメタデータ（ブローカー、トピック、パーティション、および構成）は、対応する URL に対して GET リクエストを使用して読み取ることができます。
  • プロデューサー - API は、プロデューサーオブジェクトを公開する代わりに、特定のトピックまたはパーティションをターゲットにしたプロデューサーリクエストを受け入れ、それらをすべてプロデューサーの小さなプールにルーティングします。
    • プロデューサー構成 - プロデューサーのインスタンスは共有されるため、構成はリクエストごとに設定できません。ただし、REST Proxy 構成に新しいプロデューサー設定を渡すことで、設定をグローバルに調整できます。たとえば、compression.type オプションを渡してサイト全体の圧縮を有効にし、ストレージとネットワークのオーバーヘッドを削減できます。
  • コンシューマー - コンシューマーはステートフルであるため、特定の REST Proxy インスタンスに関連付けられています。オフセットコミットは、自動にするか、またはユーザーが明示的にリクエストできます。現在は 1 つのコンシューマーにつき 1 つのスレッドに制限されているため、スループットを向上させるには複数のコンシューマーを使用してください。REST Proxy は、上位レベルのコンシューマー（v1 api）または新しい 0.9 コンシューマー（v2 api）のいずれかを使用して、トピックから読み取れるコンシューマーグループを実装します。注: v1 API は非推奨となっています。
    • コンシューマー構成 - コンシューマーインスタンスは共有されませんが、基盤となっているサーバーリソースを共有します。そのため、限られた構成オプションが API を介して公開されます。ただし、REST Proxy 構成にコンシューマー設定を渡すことで、設定をグローバルに調整できます。
  • データフォーマット - REST Proxy は、base64 でエンコードされた未加工バイトである JSON、または JSON エンコードされた Avro、Protobuf、または JSON スキーマを使用して、データの読み取りと書き込みを行うことができます。Avro、Protobuf、または JSON スキーマを使用すると、スキーマが登録され、Schema Registry に対して検証されます。
  • REST Proxy クラスターとロードバランシング - REST Proxy は、複数のインスタンスを同時に実行して負荷を分散するように設計されており、インスタンスが 正しく構成 されていれば、さまざまなロードバランシングメカニズム（例: ラウンドロビン DNS、検出サービス、ロードバランサー）と連携して安全に実行できます。
  • 単純なコンシューマー - 一般的には、上位レベルのコンシューマーが優先されます。ただし、特定のオフセットでメッセージを取得するなど、下位レベルの読み取り操作を使用すると便利な場合があります。

参考

この構成の動作例については、Confluent Platform デモ を参照してください。構成リファレンスについては、デモの docker-compose.yml ファイル を参照してください。

  • 管理者の操作 - API v3 では、トピックを作成または削除したり、トピック構成をアップデートまたはリセットしたりできます。実践的な例については、『 Confluent Admin REST APIs demo 』を参照してください（デモを開始するには、GitHub から Confluent demo-scene リポジトリをクローンし、『 Confluent Admin REST APIs demo 』のガイドに従ってください）。

まだサポートされて "いない" 機能ですが、以下も同様に重要な機能です。

  • マルチトピック生成リクエスト - 現在、各生成リクエストは、単一トピックまたはトピックパーティションのみを処理できます。マルチトピック生成リクエストは API をより複雑にするもので、ほとんどのユースケースでは必要ありません。クライアントは、必要に応じてデータを複数のリクエストにまたがって容易に分割できます。
  • リクエストにおけるプロデューサー/コンシューマーのほとんどのオーバーライド - API で公開されているのは、いくつかの主なオーバーライドのみです（ただし、グローバルオーバーライドは管理者が設定できます）。その理由は 2 つあります。まず、プロキシはマルチテナントであるため、ユーザーがリクエストするほとんどのオーバーライドには、他のユーザーに影響を与えないようにするための追加の制限が必要です。次に、API を実装に結び付けすぎると、将来的な API の改善が制限されてしまいます。この点は、予定されているコンシューマーの新たな実装で特に重要です。

インストール

Confluent Platform の インストール手順 を参照してください。REST Proxy を起動する前に、Kafka と Schema Registry を起動する必要があります。「Confluent Platform クイックスタート」では、これらのサービスをローカルでテスト用に起動する方法について説明しています。

デプロイ

依存関係が実行されていれば、Confluent REST Proxy サービスの起動は簡単です。

# Start the REST Proxy. The default settings automatically work with the
# default settings for local |zk| and |ak| nodes.
<path-to-confluent>/bin/kafka-rest-start etc/kafka-rest/kafka-rest.properties

Debian パッケージや RPM パッケージをインストールしていれば kafka-rest-start が PATH に存在するので、それをそのまま実行できます。kafka-rest.properties ファイルには 構成設定 が含まれています。REST Proxy に含まれているデフォルトの構成には、ローカルでのテストのセットアップ用に便利なデフォルト設定が含まれています。この構成は、本稼働環境のデプロイでは変更する必要があります。デフォルトでは、サーバーはポート 8082 へのバインドを開始し、一意のインスタンス ID（複数のプロキシを同時に安全に実行するために必要）を指定せずに、ZooKeeper には localhost:2181 で、Schema Registry には http://localhost:8081 でアクセス可能であることを想定します。

バックグラウンドでサービスを起動した場合、以下のコマンドで停止できます。

bin/kafka-rest-stop

開発

開発バージョンをビルドするには、common、 rest-utils、および schema-registry の開発バージョンが必要な場合があります。これらをインストールしたら、Maven を使用して Confluent REST Proxy をビルドできます。すべての標準ライフサイクルフェーズが機能します。開発中、以下のコマンドを使用してください。

mvn -f kafka-rest/pom.xml compile

（ビルドする）

mvn -f kafka-rest/pom.xml test

（ユニットテストと統合テストを実行する）

mvn exec:java

（プロキシのインスタンスをローカルの Kafka クラスターに対して実行する（Kafka に付属のデフォルト構成を使用））

パッケージバージョンを作成するには、任意で以下のようにテストをスキップします。

mvn -f kafka-rest/pom.xml package [-DskipTests]

こうすることで、パッケージ化されたバイナリバージョンと同様にディレクトリのレイアウトを含み、本稼働環境に対応したバージョンを、target/kafka-rest-$VERSION-package に生成できます。standalone プロファイルを使用して、スタンドアロンの fat jar を生成することもできます。

mvn -f kafka-rest/pom.xml package -P standalone [-DskipTests]

（target/kafka-rest-$VERSION-standalone.jar を生成する。これにはすべての依存関係も含まれます。）

テストのためにローカルの ZooKeeper、Kafka および REST Proxy クラスターを実行するには、以下のコマンドを実行します。

./testing/environments/minimal/run.sh