Charlesの便利な機能・使い方

[Charles](https://www.charlesproxy.com/) は HTTP(S) 通信の内容を閲覧したり、改変したりすることができるツールです。

Android や iOS のアプリ開発などで通信のデバッグをする際に非常に役に立つツールですので、便利な機能や使い方についてご紹介したいと思います。

**注意点**

この記事では Charles の導入・設定方法についての解説は省略させていただきます。

私が Mac ユーザーですので、記事内で紹介しているショートカットキーや画面キャプチャは Mac のものとなります。

また、Charles のバージョンは v4.6.1 時点のものとなります。

# 通信の閲覧

## Structure と Sequence タブ

通信を閲覧する際に `Structure` と `Sequence` の2種類のタブがあります。

`Structure` では Host ごとにグルーピングされて表示され、`Sequence` では指定した順番に表示されます。

### Structure

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/6e699cec-473c-a6af-ca01-dea21aa5e03f.png" width=640>


### Sequence

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/a9335dac-82fb-dfd3-6880-db6e38a16e42.png" width=640>

## リクエスト、レスポンス情報の表示

画面上部にある `Contents` タブを選択するとリクエストヘッダ、レスポンスヘッダ、レスポンスボディを閲覧することができます。

### リクエストヘッダ、レスポンスヘッダ

以下のキャプチャの右側上部がリクエストヘッダの情報、右側下部がレスポンスヘッダの情報になります。

それぞれ `Headers` タブを指定することにより情報を見ることができます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/c969f0d0-fa17-7e84-50be-5655915abd47.png" width=640>

### レスポンスボディ

以下のキャプチャでは Qiita の API を使用しており、レスポンスボディには JSON 形式の文字列が返されます。 この場合 `JSON Text` タブを選択することによりレスポンスボディの内容が確認できます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/d8981530-de57-4e56-c360-ef972ed151b8.png" width=640>

# 通信の改変

## Throttling

通信速度の設定ができます。

通信が悪い状況を確認したい場合に使えます。

### 通信速度の設定

メニューの `Proxy` > `Throttle Settings...` で設定画面が開きます。

ショートカットメニューだと `shift + command + T` です。

![Throttle Settings.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/0f6ced01-f68d-f9b1-4fca-283ac8393cf5.png)

- `Throttole preset`
    - 設定のパターンを選択することができます。いくつかデフォルトで設定のパターンが用意されています
- `Add Preset` 
    -　好みの設定のパターンを追加することができます
- `Enable Throttling`
    - チェックを入れると設定が有効になります
- `Only for selected hosts`
    - 指定したホストのみ設定を有効にすることもできます

### 通信速度設定の有効・無効切り替え

設定の有効・無効の切り替えは以下の方法でも可能です。

- ショートカットキー `command + T` 
- メニューの `Proxy > Start Throttling / Stop Throttling`
- 亀のボタンによる切り替え（以下のキャプチャ参照）

![turtle.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/1862b893-bcd5-1a61-e097-088b14b3d455.png)

## Breakpoint

指定した通信のリクエスト / レスポンス時にブレークポイントを設定することができます。

ブレークポイントが設定された通信のリクエストが実行される前、もしくはレスポンスを受け取る前にブレークポイント画面が表示され、リクエストやレスポンスの内容を変更することが可能です。

私はよくレスポンスにブレークポイントを設定し、Web サーバーにリクエストは届くけどレスポンスは受け取れなかった状況を確認する際に使用したりしています。

### ブレークポイントの設定

メニューの `Proxy` > `Breakpoint Settings...` で設定画面が開きます。

ショートカットメニューだと `shift + command + K` です。

以下が設定画面になります。

![Breakpoint Settings1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/80aa45f9-f8cc-2896-0ae1-3e7428427717.png)

`Enable breakpoints` にチェックを入れるとブレークポイントの設定が有効になります。

`Add` から Breakpoint に設定したい通信を設定します。

![Breakpoint Settings2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/a9274fbc-2475-7d36-3088-4a95e7babc96.png)

ブレークポイントの設定は `Request` と `Response` の設定が可能です。（両方同時に設定も可能です）

Charles で閲覧済みの通信をブレークポイントに設定するのであれば、その通信を選択して右クリックし `Breakpoints` を選択すると簡単です。

![Breakpoint Settings3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/23b6756f-dad3-4d79-8b1c-d3f4fd699189.png)

### ブレークポイントの有効・無効切り替え

ブレークポイントの有効・無効の切り替えは以下の方法でも行えます。

- ショートカットキー `command + K`
- メニューの `Proxy` > `Enable Breakpoints / Disable Breakpoints`
- 六角形のボタンによる切り替え（以下のキャプチャ参照）

![Breakpoint Button.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/955e6fe7-d69b-d949-13d9-be180940f67a.png)

### ブレークポイントの画面

ブレークポイントで指定された通信のリクエストやレスポンスが実行されるタイミングで、自動的にブレークポイントの画面が表示されます。

#### リクエスト時のブレークポイント

リクエスト時のブレークポイントの画面は以下のようになっています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/39caa0ce-5845-6e54-253b-beb1097ddcf2.png" width=640>

画面上部に `Edit Request` タブがあり、こちらに切り替えるとリクエストの編集が行えます。

以下のキャプチャでは `URL` の編集が行えるようになっています。

HTTP メソッドやパス、クエリパラメーターの変更や、クエリパラメーターの追加・削除などが行えます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/bfe59cac-d30c-f48c-efcf-758addca3d68.png" width=640>

画面下部にあるタブを `Headers` に切り替えると、リクエストヘッダの編集も行えます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/3a7d1eb5-18fe-fd32-57cc-4bd361e90797.png" width=640>

編集が完了したら画面下部にある `Execute`、`Abort`、`Cancel`　のいずれかのボタンでその後の通信処理の動作を選択できます。

- `Execute`
    - 編集で変更した内容を適用した上で通信処理を継続する
- `Abort`
    - 通信を失敗させる
- `Cancel`
    - 編集で変更した内容を破棄して通信処理を継続する

#### レスポンス時のブレークポイント

レスポンス時のブレークポイントの画面は以下のようになっています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/a31d78a8-d182-28d1-0f3d-186b99743463.png" width=640>

画面上部に `Edit Response` タブがあり、こちらに切り替えるとレスポンスの編集が行えます。

以下のキャプチャでは レスポンスヘッダの編集が行えるようになっています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/0586ea8d-56ba-86e7-1647-54820172ad1d.png" width=640>

レスポンスボディが JSON 形式の文字列で返される場合、画面下部にあるタブを `JSON Text` に切り替えるとレスポンスボディの編集も行えます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/6c7fef7e-64c2-9604-3868-b9d8245ca3b1.png" width=640>

編集完了後はリクエスト時と同様に `Execute`、`Abort`、`Cancel` のいずれかのボタンを押してその後の動作を選択します。

ブレークポイントによる編集はちょっと変更したい時には便利ですが、変更内容が多かったり通信のたびに何度も変更する必要がある場合は不便です。

その場合は後述する `Rewirte` や `Map Local` を使うことをオススメします。

## Map Remote

Map Remote ではリクエスト先を変更することができます。

例えばアプリ開発でクライアントも Web API も一人で開発していて、Web API の変更をクライアント側で試したい場合に接続先をローカルに立ち上げたサーバに変更することなどができます。

メニューの `Tools` > `Map Remote...` で設定画面が開きます。

ショートカットメニューだと `option + command + M` です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/fd298f1b-067e-67da-0c1c-4153ff3085c3.png" width=640>

`Enable Map Remote` にチェックを入れると Map Remote の設定が有効になります。

`Add` ボタンをクリックすると設定を追加することができます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/d3540bb9-bfcb-941b-98d3-fd93ecd2e968.png" width=480>

`Map From` に既存の通信先を指定し、`Map To` で変更したい通信先を指定します。

この例だと `https://qiita.com` の通信をローカルに立ち上げたサーバ `http://localhost:3000` に接続先を変更しています。

## Map Local

Map Local は指定されたローカルファイルの中身を読み込んでレスポンスボディとして返す機能です。

レスポンスボディの内容を自由に設定することができるので、デバッグする際などにはとても重宝します。

メニューの `Tools` > `Map Local...` で設定画面が開きます。

ショートカットメニューだと `option + command + L` です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/d7f0d191-c1d9-fef8-3459-e6008aa6ba44.png" width=640>

`Enable Map Local` にチェックを入れると Map Local の設定が有効になります。

`Add` ボタンをクリックすると設定を追加することができます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/287baca9-9f1a-c690-c185-46102f763b9d.png" width=480>

`Map To` の `Local path` にレスポンスボディとして返したい内容を記述したファイルのパスを設定します。

閲覧済みの通信を Map Local で設定するのであれば、通信を選択して右クリックして `Map Local` を選択すると簡単です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/c39ac95e-48bd-bfa9-74b7-6c7d274a3485.png" width=640>

## No Caching

リクエストヘッダ、レスポンスヘッダのキャッシュに関する設定を変更して、キャッシュを無効にしてくれます。

メニューの `Tools` > `No Caching...` で設定画面が開きます。

ショートカットメニューだと `option + command + N` です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/2a5dde93-4feb-1561-5350-3b7f0bf009d5.png" width=640>

`Enable No Caching` にチェックを入れることで、キャッシュが無効になるように設定されます。

`Only for selected locations` にチェックを入れることで、`Location` に設定された通信先のみが無効になるように設定することも可能です。

## Block List

Block List では指定された通信をブロック（失敗）させます。

メニューの `Tools` > `Block List...` で設定画面が開きます。

ショートカットメニューだと `option + command + B` です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/06e95c1d-c9ac-1bcc-b7ad-42955bbd9574.png" width=640>

`Enable Block List` にチェックを入れると、`Location` に指定されている通信がブロックされます。

`Blocking action` で失敗させる際の挙動を設定でき、以下の2つのパターンがあります。

- `Drop connection`
- `Return 403 Response`

`Add` ボタンを押すと、Block List への追加設定が行えます。

以下のキャプチャの下部に説明がありますが、空のフィールドは全ての値にマッチするようになっています。

また、`*` や `?` によるワイルドカードの指定が可能です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/7d3b8efa-d1e3-4169-7016-053938d2e7ce.png" width=640>


## Allow List

Allow List は Block List とは逆に指定された通信だけを許可し、それ以外の通信はブロック（失敗）させます。

メニューの `Tools` > `Allow List...` で設定画面が開きます。

ショートカットメニューだと `option + command + W` です。

設定方法自体は Block List と同じなので、設定方法の説明は割愛いたします。


## Rewrite

Rewrite は指定された通信のリクエスト、レスポンスの内容を変更するための機能で、以下のことが行えます。

- リクエストヘッダ、レスポンスヘッダへの値の追加、削除、変更
- ホスト、パスの変更
- クエリパラメータの追加、削除、変更
- レスポンスのステータスコードの変更
- ボディの変更

Rewrite はメニューの `Tools` > `Rewirte` で設定画面が開きます。

ショートカットメニューだと `option + command + R` です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/70c91de4-05a3-232b-5f06-7f039229cc91.png" width=640>

画面左側には設定した内容の一覧が表示されます。

左側で設定した内容の一覧を選択すると、画面右上に `Location` の一覧（どの通信を Rewrite 対象にするか）、右下には Rewrite する際のルールが表示されます。

`Location` の設定は Block List と同じなので割愛します。

Rewrite のルールを設定する際の画面は以下のようになっています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/ea8f04cf-9805-cef0-96e8-da522df30c23.png" width=640>


`Type` で変更したい内容を選択でき、以下の項目が選択可能です。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/6df4cf74-d26d-ca6e-a833-f45301226d39.png" width=480>

`Match` と `Replace` の項目にそれぞれ値を設定することで、変更する内容を設定することができます。

先ほどのキャプチャの例だと、`per_page` のクエリパラメータの値を 10 に設定するようにしています。

正規表現を使用することもできるので、値の変更を行う際にはある程度柔軟に設定することも可能になります。

# その他機能

## Copy cURL Request

curl コマンドをクリップボードにコピーしてくれます。

例えば特定の Web API に何か問題が見つかってチームメンバーに共有する必要があった場合に便利で、 curl コマンドを共有することによって解決が容易になることが多いので、ぜひとも使ってみてください。

- 特定の通信を選択して右クリックする
- `Copy cURL Request` を選択する（キャプチャ参照）

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/5f574c31-72ad-e661-9f6e-55d8f2d6613b.png" width=640>

実行した結果、以下のようにクリップボードにコピーされます。

```
curl -H 'Host: qiita.com' -H 'user-agent: okhttp/4.9.1' -H 'if-none-match: W/"6687ae9470c7ca50e98cf521b5ec1291"' --compressed 'https://qiita.com/api/v2/items?page=1&per_page=20'
```

## Copy Response

レスポンスボディをクリップボードにコピーしてくれます。

前述の Map Local でローカルに配置するファイルを作成する際などに使えます。

- 特定の通信を選択して右クリックする
- `Copy Response` を選択する（キャプチャ参照）

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/9f8aa565-35ca-4939-6529-eef34578ba19.png" width=640>


## Repeat / Repeat Adcanced

`Repeat` では指定した通信を再度リクエストします。

`Repeat Advanced` ではリクエストをリピートする回数やその際の並列数、リクエスト間隔を指定することができます。

- 特定の通信を選択して右クリックする
- `Repeat` / `Repeat Advanced...` を選択する（キャプチャ参照）

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/190187/ef180393-1701-bd2e-7b9f-9d68f75a59b6.png" width=640>

# まとめ

以下に今回紹介した機能をまとめてみました。

| 機能名 | 概要 |
| --- | --- |
| Throttling | 通信速度の設定 |
| Breakpoint | 指定した通信にブレークポイントを設定し、リクエスト・レスポンスの内容を変更して実行したり、通信自体を中断させることができる |
| Map Remote | 接続先の変更 |
| Map Local | 指定されたローカルファイルの内容を読み込んで、それをレスポンスボディとして返す |
| No Caching | キャッシュを無効にする |
| Block List | 指定した通信をブロックする |
| Allow List | 指定した通信のみを許可し、それ以外をブロックする |
| Rewrite | リクエスト・レスポンスの内容を変更する |
| Copy cURL Request | curl コマンドをクリップボードにコピーする |
| Copy Response | レスポンスボディの内容をクリップボードにコピーする |
| Repeat / Repeat Advanced | 通信の再リクエストを行う |

# 最後に

以上、いくつか Charles の機能を紹介させていただきました。

Charles は今回紹介した機能以外にも便利な機能があるので、ドキュメントなどを参考にしてみてください。

Charles を使う際にこの記事が参考になっていただければ嬉しいです。

# 参考

- https://www.charlesproxy.com/documentation/