Kafka Topic に接続して、JSON で受信

[Kafka Topic に接続して、JSON で受信] 入力コネクタは、Generic JSON として書式設定されたイベント データ レコードを Apache Kafka® Topic から取得し、適合させるために使用されます。 Apache Kafka® の基本操作の詳細については、「Apache Kafka の概要」をご参照ください。

使用上の注意

• この入力コネクタは、Kafka Topic から JSON データを受信する場合に使用します。 この入力コネクタは、Kafka の Consumer です。
• この入力コネクタは、JSON インバウンド アダプターと Kafka インバウンド トランスポートを組み合わせます。
• このアダプターは、フィーチャ JSON や GeoJSON とは異なり、汎用 JSON を解釈します。
• 汎用 JSON レコードには、ジオメトリを表すデータを含める必要はありません。
• アダプターは、単一の JSON レコードと、配列に整理された JSON レコードの両方を処理します。
• アダプターは、X、Y、Z 属性値からポイント ジオメトリを構築することができます。
• この入力コネクタには [Learning Mode] が含まれます。Learning Mode は、入力コネクタが構築したジオイベント定義を修正できるようにする場合に便利です。 このプロパティの目的とは、受信したイベント データが可変的なスキーマやデータ構造を持つことを一時的に許可することです。 入力コネクタは、受信したデータ レコードのサンプルを使用して可変的なデータ構造について学習し、これまでに観測されなかった新しい属性フィールドを既存のジオイベント定義に付加します。
• ジオイベント定義のリアルタイム変更を許可すると、ジオイベント サービスのリアルタイム解析の設計に悪影響が及ぶことがあります。 インバウンド イベント データでスキーマの不一致が予期される場合は、[Learning Mode] をできる限り短い時間にわたって使用し、インバウンド データで予期されるすべてのバリアントをサポートするジオイベント定義を生成することをお勧めします。 その後 [Learning mode] をオフにし、自動生成されたジオイベント定義をコピーして、本番配置用に調整することができます。
• Kafka インバウンド トランスポートは、KKafka クラスターまたは Broker で認証するために、TLS 1.2 および SASL セキュリティ プロトコルをサポートしています。

パラメーター

パラメーター	説明
名前	GeoEvent Manager で参照用として使用される入力コネクタの記述名。
カスタム Kafka プロパティでオーバーライド	デフォルトの GeoEvent Server Kafka クライアント プロパティをオーバーライドするかどうかを指定します。 デフォルトは [いいえ] です。 [はい] – トランスポートにより表示されるデフォルトの Kafka クライアント プロパティはオーバーライドされます。 有効な Kafka 構成が正しく書式設定された Kafka .properties ファイルを含む、GeoEvent Server に登録されたフォルダーを指定する必要があります。 サポートされている構成のリストと指定された .properties ファイルの推定される書式設定については、「Apache Kafka の構成」をご参照ください。 [いいえ] – トランスポートにより表示されるデフォルトの Kafka クライアント プロパティはオーバーライドされません。 [Kafka Bootstrap Servers] と [Consumer のグループ ID] を指定する必要があります。
Kafka Bootstrap Servers (条件)	Kafka クラスターへの初期接続を確立するために使用されるホスト名とポートのペアのリスト。 ホスト名とポートのペアは、次の例のようにカンマ区切りである必要があります。 broker0.example.com:9092,broker1.example.com:9092,broker2.example.com:9092 このパラメーターは、[カスタム Kafka プロパティでオーバーライド] が [いいえ] に設定されている場合に表示されます。
Topic 名	対象データが使用される Kafka Topic 名または Kafka Topic のリスト。 複数のトピックは、セミコロンで区切る必要があります。 topic1 topic1;topic2;topic3;topic4 注意: 複数の Kafka Topic を指定する機能は、ArcGIS GeoEvent Server 10.8 以降でサポートされます。
Consumer 数	Consumer グループごとの Consumer 数を指定します。 Consumer 数はデフォルトで 1 に設定されています。 注意: Consumer 数は、Kafka トピックのパーティション数によって制限されます。 Consumer インスタンスの詳細については、「Apache Kafka の概要」をご参照ください。
Consumer のグループ ID (条件)	一連の Consumer の Consumer グループを一意に識別するオプションの文字列。 Consumer グループ名とも呼ばれます。 Consumer のグループ ID を指定しない場合、GeoEvent Server は、geoevent-consumer と呼ばれる静的な Consumer のグループ ID を割り当てます。 この静的な Consumer のグループ ID は、Consumer のグループ ID が未指定のままにされている Kafka コネクタのすべてのインスタンスで共有されます。 Consumer のカスタム グループ ID を指定することを強くお勧めします。 Consumer グループの詳細については、「Apache Kafka の概要」をご参照ください。 このパラメーターは、[カスタム Kafka プロパティでオーバーライド] が [いいえ] に設定されている場合に表示されます。
Kafka プロパティ ファイルの登録済みフォルダー (条件)	Kafka .properties ファイルを含む GeoEvent Server に登録されたフォルダー。 Kafka .properties ファイルは、[カスタム Kafka プロパティでオーバーライド] が [はい] に設定されている場合にカスタム Kafka プロパティを定義します。 GeoEvent Server に登録されたフォルダーが、Kafka .properties ファイルが配置された場所への絶対パスであることを確認してください。 このパラメーターは、[カスタム Kafka プロパティでオーバーライド] が [はい] に設定されている場合に表示されます。
Kafka プロパティ ファイル名 (条件)	クライアント構成のカスタム Kafka プロパティを含む Kafka .properties ファイルの名前。 ファイルの名前は .properties 拡張子なしで指定する必要があります。 カスタム Kafka .properties ファイルの名前が「sample.properties」の時、このパラメーターを「sample」と指定します。 このパラメーターは、[カスタム Kafka プロパティでオーバーライド] が [はい] に設定されている場合に表示されます。
最初から開始	レコードが最初のオフセットで始まる Topic から消費されるか、または Consumer にコミットした最後のオフセットから消費されるかを指定します。 デフォルトは [はい] です。 [はい] – レコードは最初のオフセットで始まる Topic から消費されます。 [いいえ] – レコードはコミットした最後のオフセットから消費されます。 注意: オフセットの詳細については、「Apache Kafka の構成」をご参照ください。
JSON オブジェクト名	受信した JSON データ内の下部構造のルート ノードとして使用される JSON 要素の名前。 [JSON オブジェクト名] を使用して JSON 要素を名前で指定する場合、アダプターは、オブジェクト名が指定した要素名と一致する部分構造を検索します。 特定された部分構造内のデータだけが考慮されます。 この設定を空白のままにすると (デフォルト)、最上位の JSON オブジェクトが JSON 構造全体のルートとして使用されます。
ジオイベント定義の作成	インバウンド イベント データに新しいジオイベント定義を使用するか、既存のジオイベント定義を使用するかを指定します。 GeoEvent Server がインバウンド データ属性フィールドおよびデータ タイプを理解するには、ジオイベント定義が必要です。 [はい] – 最初に受信したイベント レコードのスキーマに基づき、新しいジオイベント定義が作成されます。 [いいえ] – 新しいジオイベント定義は作成されません。 インバウンド イベント データのスキーマに一致する、既存のジオイベント定義が選択されます。
ジオイベント定義名 (新規) (条件)	新しいジオイベント定義に与えられる名前。 指定した名前を持つジオイベント定義がすでに存在する場合、既存のジオイベント定義が使用されます。 最初に受信したデータ レコードを使用し、後続のデータ レコードで予期されるスキーマを決定します。新しいジオイベント定義は、最初のデータ レコードのスキーマに基づいて作成されます。 このパラメーターは、[ジオイベント定義の作成] が [はい] に設定されている場合に表示され、[いいえ] に設定されている場合は非表示になります。
ジオイベント定義名 (既存) (条件)	受信したデータを適合して、GeoEvent Service によって処理されるイベント データを作成する際に使用する、既存のジオイベント定義の名前。 このパラメーターは、[ジオイベント定義の作成] が [いいえ] に設定されている場合に表示され、[はい] に設定されている場合は非表示になります。
フィールドからジオメトリを作成	入力コネクタが、属性として受信した座標値を使用してポイント ジオメトリを作成するかどうかを指定します。 デフォルトは [いいえ] です。 [はい] – 指定したイベント属性の値を使用し、ポイント ジオメトリを作成します。 [いいえ] – ポイント ジオメトリは作成されません。 属性フィールドには、ジオメトリとして解釈される値が含まれているか、イベント レコードが非空間である (ジオメトリがない) と想定されます。
X ジオメトリ フィールド (条件)	ポイント位置の X 座標部 (水平、経度など) を含むインバウンド イベント データの属性フィールド。 このパラメーターは、[フィールドからジオメトリを作成] が [はい] に設定されている場合に表示され、[いいえ] に設定されている場合は非表示になります。
Y ジオメトリ フィールド (条件)	ポイント位置の Y 座標部 (垂直、緯度など) を含むインバウンド イベント データの属性フィールド。 このパラメーターは、[フィールドからジオメトリを作成] が [はい] に設定されている場合に表示され、[いいえ] に設定されている場合は非表示になります。
Z ジオメトリ フィールド (条件)	ポイント位置の Z 座標部 (深さ、高さなど) を含むインバウンド イベント データのフィールド名。 空白のままにすると Z 値は省略され、2D ポイント ジオメトリが作成されます。 このパラメーターは、[フィールドからジオメトリを作成] が [はい] に設定されている場合に表示され、[いいえ] に設定されている場合は非表示になります。
ラーニング モード	[ラーニング モード] を有効にするか無効にするかを指定します。 ラーニング モードが [はい] に設定されている場合、インバウンド アダプターが作成し、維持しているジオイベント定義に新しいフィールドが付加されます。 [はい] – ラーニング モードが有効になります。 ジオイベント定義は、異なるスキーマを持つイベント レコードの新規フィールドで更新されます。 [いいえ] – ラーニング モードは有効になりません。 ジオイベント定義は修正されません。 [ラーニング モード] は、入力コネクタが構築したジオイベント定義を修正できるようにする場合に便利です。 このパラメーターの目的とは、受信したイベント データが可変的なスキーマやデータ構造を持つことを一時的に許可することです。 入力コネクタは、受信したデータ レコードのサンプルを使用して可変的なデータ構造について学習し、これまでに観測されなかった新しい属性フィールドを既存のジオイベント定義に付加します。 ジオイベント定義のリアルタイム変更を許可すると、ジオイベント サービスのリアルタイム解析の設計に悪影響が及ぶことがあります。 ベストプラクティスとして、インバウンド イベント データでスキーマのばらつきが予期される場合は、[ラーニング モード] をできる限り短い期間で使用し、インバウンド データで予期されるすべてのバリエーションをサポートするジオイベント定義を生成することをお勧めします。 その後 [ラーニング モード] をオフにし、自動生成されたジオイベント定義をコピーして、本番デプロイメント用に調整することができます。
デフォルト空間参照	座標値が、想定されている WGS84 地理座標系システムの緯度と経度の値ではない属性フィールド値をもとにジオメトリを作成するか、受信したジオメトリ文字列に空間参照が含まれない場合に使用される空間参照の Well-Known ID (WKID)。 WKID または Well-Known Text (WKT) を含む属性フィールドの WKT 値または名前が指定されることもあります。
推定される日付形式	日付時間値として予期される文字列表現を一致させ、それを Java Date 値に変換するために使用されるパターン。 パターンの形式は、Java SimpleDateFormat クラス変換に従います。 このパラメーターにはデフォルト値がありません。 GeoEvent Server では、日付/時間値を ISO 8601 標準で表すことを推奨していますが、日付値として一般的に認識されている日付/時間値の文字列表現のいくつかは、[推定される日付形式] パターンを指定しなくても Java Date 値に変換することができます。 これらの要件を次に示します。 "2019-12-31T23:59:59" – ISO 8601 標準形式 1577836799000 – Java Date (紀元からの時間を示す Long 型整数、UTC) "Tue Dec 31 23:59:59 -0000 2019" – 一般的な Web サービス文字列形式 "12/31/2019 11:59:59 PM" – 米国で使用される一般的な形式 (12 時間形式) "12/31/2019 23:59:59" – 米国で使用される一般的な形式 (24 時間形式) 受信した日付/時間の値が、上記の 5 つ以外の形式で表される場合は、GeoEvent Server が日付/時間値を適合する方法を把握できるよう、[推定される日付形式] を指定する必要があります。
GeoJSON として	受信ジオメトリを、フィーチャ JSON ではなく GeoJSON ジオメトリ オブジェクトとして解析するかどうかを指定します。 デフォルトでは、ジオメトリを文字列として受信した場合、「ジオメトリ オブジェクト」で示すように、値はフィーチャ JSON になります。 [はい] – 受信ジオメトリはフィーチャ JSON ではなく GeoJSON として解析されます。 [いいえ] – 受信したジオメトリの文字列表現はフィーチャ JSON であると想定されます。
認証が必要	Kafka クラスターまたは Kafka Broker への接続に認証が必要かどうかを指定します。 デフォルトは [いいえ] です。 [はい] – Kafka クラスターまたは Broker への接続に認証が必要です。 [いいえ] – Kafka クラスターまたは Broker への接続に認証は不要です。
認証方法 (条件)	Kafka クラスターのセキュリティ保護に使用されるセキュリティ プロトコルを指定します。 利用できるセキュリティ プロトコルは TLS 1.2 および SASL です。 [TLS 1.2] – Kafka クラスターが使用するセキュリティ プロトコルは TLS 1.2 です。 Kafka クラスターの PKI ファイル (x509 証明書) が、ArcGIS GeoEvent Server が構成されている ArcGIS Server のトラスト ストアにインポートされていることを確認してください。 証明書のインポートに関する具体的な手順については、「既存の CA 署名証明書での ArcGIS Server の構成」の「ArcGIS Server への証明書のインポート」セクションをご参照ください。 [SASL] – Kafka クラスターによって使用されるセキュリティ プロトコルは、SASL です。 SASL SSL と Kerberos のみがサポートされています。 注意: Kerberos を使用する場合、ArcGIS GeoEvent Server を実行しているオペレーティング システムのユーザー アカウントに、Kerberos セットアップ/構成内のキータブ ファイルへの読み取りアクセス権があることを確認してください。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。
認証情報ファイルの登録済みフォルダー (条件)	Kafka クラスターの PKI ファイル (x509 証明書) を含む GeoEvent Server に登録されたフォルダー。 GeoEvent Server に登録されたフォルダーが、Kafka クラスターの証明書が配置された場所への絶対パスであることを確認してください。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、TLS 1.2 にのみ適用できます。
認証情報の構成ファイル (条件)	Kafka クラスターの PKI ファイル (x509 証明書) の名前。 この証明書とそれに関連するプライベート キーは、.p12 または .pfx の拡張子を持つファイルで表される PKCS#12 形式で保存する必要があります。 ファイルの名前と拡張子を指定します。 my_kafka_certificate.pfx my_other_kafka_certificate.p12 注意: このパラメーターでは、証明書ファイル名と拡張子のみがサポートされます。 証明書への相対パスはこのパラメーターに指定しないでください。 [認証情報ファイルの登録済みフォルダー] パラメーターを使用して証明書ファイルへの絶対パスを登録します。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このプロパティは、TLS 1.2 にのみ適用できます。
キーストアのパスワード (条件)	Kafka クラスターの PKI ファイル (x509 証明書) のパスワード。 証明書のプライベート キーとも呼ばれます。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、TLS 1.2 にのみ適用できます。
SASL 認証タイプ (条件)	Kafka クラスターがサポートする SASL 認証メカニズムのタイプを指定します。 利用可能な SASL 認証タイプには、SASL GSSAPI (Kerberos) と SASL PLAIN が含まれます。 [SASL/GSSAPI (Kerberos)] – Kafka クラスターは SASL/GSSAPI Kerberos 認証を使用します。 [SASL/PLAIN] – Kafka クラスターは SASL/PLAIN 認証を使用します。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL にのみ適用できます。
Kerberos プリンシパル (条件)	特定ユーザーの Kerberos プリンシパル。 例: [e-mail]. このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL/GSSAPI (Kerberos) にのみ適用できます。
キー タブの使用 (条件)	キータブを Kerberos 設定で使用するかどうかを指定します。 デフォルトは [はい] です。 [はい] – キータブは Kerberos 設定で使用されます。 [いいえ] – キータブは Kerberos 設定で使用されません。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL/GSSAPI (Kerberos) にのみ適用できます。
キーの保存 (条件)	キーを Kerberos 設定に保存するかどうかを指定します。 デフォルトは [はい] です。 [はい] – キーは Kerberos 設定に保存されます。 [いいえ] – キーは Kerberos 設定に保存されません。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL/GSSAPI (Kerberos) にのみ適用できます。
Username (条件)	Kafka クラスターでの認証に使用されるユーザー名を指定します。 クラウド プロバイダーによっては、接続文字列とも呼ばれます。 正しい構文については選択したクラウド プロバイダーのドキュメントをご参照ください。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL/PLAIN にのみ適用できます。
パスワード (条件)	Kafka クラスターでの認証に使用されるパスワードを指定します。 正しい構文については選択したクラウド プロバイダーのドキュメントをご参照ください。 このパラメーターは、[認証が必要] が [はい] に設定されている場合に表示されます。 このパラメーターは、SASL/PLAIN にのみ適用できます。

検討事項および制限事項

• Consumer の管理と最適化が不十分な場合、[Kafka Topic に接続して、JSON で受信] 入力コネクタはデータを取得できなくなります。 Consumer グループ内の Consumer 数は、Kafka トピックのパーティション数によって制限されます。 Consumer グループ内の Consumer 数が Kafka Topic で利用できるパーティション数を超えると、超過する Consumer はデータを受信しません。 Consumer 数を最適化して、Kafka Topic 上のパーティションの数に最適な数にすることを検討するか、コネクタごとに異なる Consumer グループを実装して、これを回避してください。 Consumer と Consumer グループの詳細については、「Kafka のドキュメント」をご参照ください。
• [Kafka Topic に接続して、JSON で受信] 入力コネクタは Kafka のクライアント Consumer です。 この入力コネクタにも、Kafka の他のクライアント Consumer に要求されるものと同じ懸念事項が適用されます。 たとえば、この入力コネクタは Kafka Topic からデータを受信していないが Kafka の別のクライアント Consumer は受信している場合、2 つのクライアント Consumer に関連する要因を検討します。 これには、構成された Consumer グループ ID、Topic で使用可能なパーティションの数、既存の Consumer の数が含まれますが、これらに限定されません。 または、入力コネクタが立て続けに停止され開始される場合、Consumer の視点から Kafka の影響を検討します。 Kafka Topic のパーティションを再調整すると、入力コネクタが同じ Consumer グループの Consumer としてすぐに再結合することができなくなる可能性があります。