# Protobuf

> Proxyman で .desc ファイルディスクリプタと Message Type ルールを使い、Protobuf の HTTP/HTTPS リクエスト、レスポンス、WebSocket メッセージをデコードします。

## 1. 概要 {#1-protobuf}

* Proxyman macOS では、指定した desc ファイルを使って、HTTP/HTTPS リクエストとレスポンスの Protobuf ボディをデコードできます
* Protobuf のバイナリをデコードし、プレーンテキストとして表示します
* 1 つの Protobuf バイナリ内の Single Message と、複数の Delimited Messages に対応しています
* desc ファイルをインポートすると、そこに含まれるすべての Message Type を読み込み、Protobuf バイナリをデコードできます
* [WebSocket の Protobuf](https://proxyman.com/docs/ja/advanced-features/websocket#websocket-with-protobuf-payload) をデコード

![生の Protobuf リクエストボディと、同じボディを JSON にデコードした結果を並べて表示する Proxyman](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_32_54.png)

## 2. Protobuf ファイルディスクリプタ（\*.desc） {#2-protobuf-file-descriptor-desc}

Proxyman で Protobuf データを正しく解析するには、ファイルディスクリプタ（\*.desc）が必要です。

ファイルディスクリプタを入手する方法はいくつかあります。

### 1. 同僚に聞く {#1-ask-your-colleagues}

社内で Protobuf を使っている場合、特にバックエンドチームとフロントエンドチームであれば、同僚がすでにこのファイルを持っている可能性が高いです。

ディスクリプタファイルは 1 つの場合も、複数の場合もあります。

### 2. \*.proto ファイルから生成 {#2-generate-from-proto-file}

\*.proto ファイルが多数ある場合は、次のコマンドで 1 つの \*.desc ファイルを生成できます。

```bash
# Install protobuf cli if need
brew install protobuf

# Create `input` folder on the Desktop
# Copy all proto files to the `input` folder

# Generate 1 descriptor file with multiple proto files
protoc --descriptor_set_out=output.desc --include_imports -I=/Users/<your_name>/Desktop/input /Users/<your_name>/Desktop/input/*.proto

# Done
# output.desc
```

ディスクリプタファイルを用意したら、Proxyman にインポートします。

* **Tools** メニュー -> **Protobuf…** を開き、**Protobuf Schema...** ボタンをクリックします。
* **+** ボタンをクリックし、**output.desc** ファイルを選択します。

> **備考:** Proxyman 3.6.0 以降では、より正確な Protobuf 解析のために **ファイルディスクリプタ（\*.desc）** のみを受け付けます。
>
> **\*.proto** ファイルがある場合は、**\*.desc** に変換できます。上の [\*.proto ファイルから生成](#2-generate-from-proto-file) を参照してください。

> **備考:** Proxyman は、Timestamp、Struct、Value、Enum、Method など、**Google Protobuf** の一般的な型を自動的にインポートします。
>
> Proxyman は **proto2** と **proto3** の両方の構文に対応しています。[詳しくはこちら](https://developers.google.com/protocol-buffers/docs/proto3)

## 3. Protobuf の設定 {#3-protobuf-config}

Protobuf を使う前に、Proxyman が Protobuf データの解析に使用する Message Type を設定する必要があります。

次の表で各設定を説明します。

| 名前 | 説明 |
| --- | --- |
| Schema | 必要に応じて `.desc` ファイルを追加します |
| Message Type | Protobuf バイナリ内のルートオブジェクトのクラス名。**パッケージ名を含める必要があります** |
| Payload Type: **Auto** | Protobuf バイナリが Single Message か [Delimited Message](https://developers.google.com/protocol-buffers/docs/techniques#streaming) のどちらでエンコードされているかを自動判定します |
| Payload Type: **Single Message** | Protobuf バイナリ内の Single Message |
| Payload Type: **Delimited List** | Protobuf バイナリ内の複数のメッセージ（長さプレフィックス付き） |

![マッチングルール、Add Schema、Message Type、Payload Type のオプションが表示されている Proxyman の Protobuf Settings ルール](https://proxyman.com/docs/assets/Screenshot%202026-01-31%20at%2010.04.50.png)

_Proxyman で Protobuf の HTTPS レスポンスをデコード_

## 4. 使い方 {#4-how-to-use}

Protobuf の名前付きフィールドを正しく解析する方法は **2 つ** あります：

* Protobuf ルールを定義する
* Content-Type ヘッダーから読み取る

### 4.1 Protobuf ルールを定義する {#41-define-protobuf-rule}

1. Protobuf リクエストには Content-Type ヘッダーが必要です：`Content-Type: application/x-protobuf` または `Content-Type: application/protobuf`
2. Proxyman は Protobuf ペイロードを検出すると、Message Type が指定されていないため正しく解析できないという警告を表示します。**Add** をクリックして Protobuf Settings を開いてください。

または、リクエストを右クリックして **Tools** -> **Protobuf…** を選択することもできます。

![Missing Message Type の警告、Add ボタン、名前のない番号付きフィールドが表示されている Proxyman の Protobuf リクエストボディ](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_56_19.png)

3\. Protobuf ルールのウィンドウで、このリクエスト/レスポンスの Message Type を選択します（必要に応じて desc ファイルを追加してください）。

> **備考:** リクエストとレスポンスで異なる Protobuf Message Type を使用している場合は、\`Use different Message Type for Request / Response\` チェックボックスをオンにしてください。

4\. **Add** をクリックすると、ボディが JSON 形式で表示されます。

### 4.2 Content-Type ヘッダーから読み取る {#42-read-from-content-type-header}

`Content-Type` から Protobuf の設定を **動的に** 指定できます。

例えば、リクエストまたはレスポンスの `Content-Type` は次のような値になります。

`Content-Type: application/x-protobuf; messageType="tutorial.Address"; delimited=true`

`Content-Type: application/x-protobuf; messageType="com.proxyman.User"; delimited=false`

これにより、Proxyman は Protobuf ボディの Message Type とペイロードのエンコード方式を判断できます。

## 5. ✅ WebSocket の Protobuf（macOS 6.5.0 以降） {#5--protobuf-with-websocket-from-macos-650-or-later}

* 1 つのバイナリ WebSocket フレームをデコードするには、[websocket.md](https://proxyman.com/docs/ja/advanced-features/websocket) を参照してください。
* WebSocket 用の Protobuf ルールを作成できます。クライアントからのメッセージには Request Message Type を、サーバーからのメッセージには Response Message Type を使用します。

## 6. トラブルシューティング {#6-troubleshooting}

### 6.1 一部の名前フィールドが表示されない {#61-some-name-fields-are-missing}

フィールド定義が Protobuf ファイルディスクリプタに含まれていない場合、一部のフィールド名が表示されないことがあります。ディスクリプタが古くなっている可能性があります。

**解決方法**：

* 古い Protobuf Schema を削除し、サーバーから取得した最新のディスクリプタファイルを追加してください。
* Proxyman 3.5.2 以前を使用している場合は、3.6.0 以降にアップデートしてください。その後、より良い結果を得るためにファイルディスクリプタ（\*.desc）を使用してください。

## 詳細情報 {#learn-more}

* [WebSocket をキャプチャし、Protobuf メッセージをデコードする方法](https://proxyman.com/posts/how-to-capture-websocket-with-protobuf-message)
* [Proxyman と mitmproxy の比較：Protobuf WebSocket メッセージのデコード](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Protobuf-WebSocket)