matchport

ポートグループで入力レコードをフィルタリングします。ポートまたはプロトコル値がnullであるか、タイプが一致しない場合はそのレコードを破棄します。

コマンドプロパティ

項目	説明
コマンドタイプ	加工クエリ
必要な権限	なし
ライセンス使用量	該当なし
並列実行	対応
分散実行	データノードで実行（mapper）

構文

matchport [guid=STR] [name=STR] [port=STR] [protocol=STR] [invert=BOOL] [verify=BOOL]

上記の構文のうちnameは4.0.2609.0以降で使用できます。

オプション

guid=STR: マッチングに使用するポートグループのGUID（nameと同時に使用できません）。guidとnameオプションのいずれか一方を必ず指定してください。
name=STR: マッチングに使用するポートグループの名前（guidと同時に使用できません）。guidとnameオプションのいずれか一方を必ず指定してください。このオプションは4.0.2609.0以降で使用できます。5.0系（5.0.2605.2まで）では使用できず、常にguidを指定する必要があります。
port=STR: ポート番号が格納されているフィールドの名前。（デフォルト: port）
protocol=STR: プロトコルが格納されているフィールドの名前。tcp、udp、icmpの値を認識します。（デフォルト: protocol）これら3つの値以外の文字列は、プロトコルを指定しない場合と同様に扱われ、TCP・UDPの両方を対象に対照します。
invert=BOOL: tを指定するとポートグループにマッチするレコードを破棄し、マッチしないレコードのみを出力します。（デフォルト: f）
verify=BOOL: fを指定するとパース段階でポートグループの有効性検査を省略します。（デフォルト: t）

入力フィールド

フィールド	タイプ	必須	説明
`port`	32ビット整数	必須	ポート番号。`port`オプションで別のフィールド名を指定できます。数値タイプでない場合はレコードを破棄します。
`protocol`	文字列	必須	プロトコル名。`protocol`オプションで別のフィールド名を指定できます。文字列でない場合はレコードを破棄します。

エラーコード

パースエラー

エラーコード	メッセージ	説明
300010	cannot use both field and port option of matchport	`field`と`port`オプションを同時に指定した場合
300011	cannot use both field and protocol option of matchport	`field`と`protocol`オプションを同時に指定した場合
300012	Specify 'guid' option in the matchport command.	5.0系（5.0.2605.2まで）で`guid`オプションが指定されていない場合。4.0系ではこのコードは4.0.2609.0から300056に置き換えられました
300013	Port group not found.	指定したGUIDに対応するポートグループが存在しない場合（`verify=t`の場合にのみ検証）
300014	Cannot load port group.	ポートグループデータの読み込み中にエラーが発生した場合
300056	Specify 'guid' or 'name' option in the matchport command.	`guid`と`name`オプションのどちらも指定されていない場合。4.0.2609.0以降で使用できる`name`オプションに伴うコードで、5.0系（5.0.2605.2まで）には該当しません。
300057	Port group not found by name.	`name`オプションで指定した名前のポートグループが存在しない場合。4.0.2609.0以降で使用できる`name`オプションに伴うコードで、5.0系（5.0.2605.2まで）には該当しません。
300058	Duplicate port group name.	`name`オプションで指定した名前のポートグループが複数存在する場合。4.0.2609.0以降で使用できる`name`オプションに伴うコードで、5.0系（5.0.2605.2まで）には該当しません。
300059	Specify only one of 'guid' or 'name' option in the matchport command.	`guid`と`name`オプションを同時に指定した場合。4.0.2609.0以降で使用できる`name`オプションに伴うコードで、5.0系（5.0.2605.2まで）には該当しません。
300060	The GUID in the matchport command is invalid format.	`guid`オプション値が有効なGUID形式でない場合。4.0.2609.0以降で発生します。5.0系（5.0.2605.2まで）はこのコマンドのGUID形式を検証しません。

ランタイムエラー

該当なし

説明

matchportコマンドは、入力レコードのポート番号とプロトコル値が指定されたポートグループに含まれるかを確認し、マッチするレコードのみを出力します。invertオプションをtに指定するとマッチしないレコードのみを出力します。

guidまたはnameオプションでマッチングに使用するポートグループを指定します。nameオプションを指定すると、その名前のポートグループを照会してGUIDを確認します。両方のオプションを同時に指定した場合、またはどちらも指定しなかった場合はエラーになります。nameで指定した名前が存在しない場合や、複数のグループと重複する場合もエラーになります。

ポートフィールドの値が数値タイプでないか、プロトコルフィールドの値が文字列でない場合、invertオプションの値に関わらずそのレコードを破棄します。

分散環境ではデータノードでフィルタリングを実行します。

使用例

ポートグループでフィルタリング

json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000

指定したポートグループに含まれるレコードのみを出力します。

ポートグループにマッチしないレコードの抽出
```
json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000 invert=t
```
invert=tオプションを指定してポートグループに含まれないレコードのみを出力します。
ユーザー定義フィールド名の指定
```
json "[{'dst_port': 443, 'proto': 'tcp'}, {'dst_port': 53, 'proto': 'udp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000 port=dst_port protocol=proto
```
portとprotocolオプションでポート番号フィールドとプロトコルフィールドの名前を指定します。
名前でポートグループを指定（4.0系、4.0.2609.0以降）
```
json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}]"
| matchport name=web_ports
```
GUIDの代わりに名前でポートグループを指定してマッチングします。

変更履歴

対象	導入リリース
`matchport` コマンド	Sonar 4.0以前
`name` オプション	4.0.2609.0