ファイルを受け取るエンドポイントを構築しました。ユーザーはプロフィール画像を POST /avatars にアップロードするか、アプリが署名付きPDFを POST /documents にプッシュします。頭の中ではルートは機能しています。次に、それがHTTP上で機能することを証明する必要があります。実際のファイルを選択し、フォームフィールドに添付し、リクエストを送信し、応答を確認します。
多くのAPIツールが扱いにくいと感じる部分です。ファイルのアップロードにはJSONではなく multipart/form-data を使用するため、ボディを貼り付けて送信するだけでは済みません。ファイルフィールドを理解するリクエストビルダーと、後でテストが実行されたときにファイルを見つけられるテストランナーが必要です。Apidog はその両方に対応しており、このガイドではその全行程を説明します。単一のアップロードの送信、JSONと同時にファイルを送信する方法、応答の検証、そして誰も教えてくれない正直な部分、つまり同じアップロードステップがRunnerまたはCLIでヘッドレス実行されたときにファイルが見つからない場合に何が起こるか、についてです。まずフォーマット自体の背景を知りたい場合は、APIsでのファイルアップロードの入門記事でマルチパートリクエストの構造について解説しています。FormDataに関するMDNリファレンスはブラウザ側での良い参考になります。
multipart/form-dataとは何か、そしてなぜアップロードに必要なのか
APIリクエストボディにはいくつかの形式があります。Apidogのリクエストボディセクションでは、form-data、x-www-form-urlencoded、JSON、XML、raw、またはバイナリを選択できます。ほとんどの場合、JSONを使用しますが、ファイルのアップロードは例外です。
form-data ボディタイプは Content-Type: multipart/form-data ヘッダーにマッピングされます。これは、他のデータと共にファイルをアップロードするために作られた形式です。単一のブロブではなく、ボディは複数のパートに分割され、それぞれが独自の名前と内容を持ちます。あるパートはキャプションのようなプレーンな文字列になり、別のパートは画像の生バイトになることがあります。そのため、写真のアップロードとそのメタデータを同じリクエストで送信できるのです。
近い仲間は x-www-form-urlencoded です。エディターでは似ていて、ボディにキーと値のペアが送信されますが、これはファイルを伴わない単純なフォーム向けです。エンドポイントがファイルを受け取る場合、form-data が選択すべきものです。すべてのフィールドが短いスカラー値であり、バイトデータが含まれない場合にのみ x-www-form-urlencoded を使用してください。
form-data では、Apidogは各パラメータをキーと値のペアとして表示し、各パラメータは型（文字列、整数、ファイルなど）を持っています。このパラメータごとの型が、すべてを可能にする秘訣です。フィールドを file に設定すると、Apidogはその値を送信するテキストとしてではなく、添付するファイルとして扱います。
単一のファイルアップロードを送信し、応答を検証する
POST /avatars をテストしているとしましょう。これは avatar という1つのフィールド（画像を含む）を受け取り、保存されたURLを含むJSONを返します。以下に手順を説明します。
1. 「ボディ」セクションを開き、「form-data」を選択します。 エンドポイントまたは新しいリクエストで、メソッドを POST に、URLをアバターのルートに設定します。「ボディ」タブを開き、form-data ボディタイプを選択します。Apidogが自動的に Content-Type: multipart/form-data を設定します。
2. ファイルパラメータを追加し、その型をファイルに設定します。 キー avatar を持つパラメータを追加します。キーの横にある型セレクタを使用して、その型を string から file に変更します。値セルがテキストボックスではなくファイルピッカーに変わります。
3. 「アップロード」をクリックし、ローカルファイルを選択します。 avatar 行の Upload をクリックし、例えば jane-profile.png のように、お使いのマシンから画像を選択します。Apidogはそのファイルへのパスを記録します。
4. リクエストを送信します。 「送信」をクリックします。Apidogは保存されたローカルパスからファイルを読み込み、マルチパートボディを構築して送信します。事前に知っておくべきこと：Apidogはリクエストでファイルを送信しますが、ファイルをクラウドに保存しません。バイトデータではなく、ローカルパスのみを保存します。この詳細は後で重要になるので覚えておいてください。
成功した呼び出しは次のような応答を返します。
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. 応答を検証します。 200 を返す送信だけではテストの合格とはなりません。検証を確実にするためにアサーションを追加します。Apidogでは、これらをエンドポイントまたはシナリオステップの「リクエスト後のアサーション」として追加します。簡単に言えば、ステータスと、ボディが使用可能なURLを含んでいることを確認したいのです。
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
これらはApidogのアサーションUIに直接マッピングされます。ステータスコードに対するアサーションが1つ、JSONPath $.avatarUrl の存在に対するアサーションが1つ、$.contentType に対するアサーションが1つです。アサーションが初めての場合は、APIアサーションガイドでオペレーターの全セットとJSONPathがフィールドをターゲットにする方法が示されています。
ツール外での簡単な確認のために、curlでの同じアップロードは次のようになります。
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
-F フラグはcurlがマルチパートを構築する方法であり、@ はファイルの内容を読み取るように指示します。Apidogの form-data ファイルパラメータは、フラグの代わりにピッカーを使って同じことを行います。
ファイルとJSONを同時に送信する
実際のエンドポイントが裸のファイルだけを受け取ることはほとんどありません。POST /documents はファイルに加えて、タイトル、カテゴリ、あるいはタグの配列といったメタデータを要求するかもしれません。これを1つのマルチパートリクエストで行うには、2つの明確な方法があります。
単純なケースはスカラーフィールドです。ファイルフィールドの隣にさらに form-data パラメータを追加し、それらを string または integer のままにします。title の文字列、category の文字列、型が file に設定された file。これら3つすべてが同じリクエストで送信されます。
メタデータがネストされたオブジェクトや配列のように構造化されている場合は、それを文字列パート内のJSONとして送信します。metadata という名前の form-data パラメータを追加し、その型を string のままにして、JSONをそのまま値に貼り付けます。
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
したがって、リクエストには2つのパートがあります。q3-invoice.pdf を含む file (型は file) と、そのJSONを含む metadata (型は string) です。サーバーは一方のパートからファイルを読み取り、もう一方からJSONを解析します。多くの公開APIはこの正確な方法でアップロードを受け付けています。Stripeのファイルアップロードドキュメントは、ファイルパートとプレーンフィールドを組み合わせる実際のマルチパートエンドポイントの良い例です。このパターンは非常に一般的であるため、Postmanユーザーもこれに遭遇します。もし移行を考えているなら、PostmanでのファイルとJSONデータのアップロードに関するチュートリアルは、Apidogの form-data フィールドにきれいにマッピングされます。
複数のファイルを添付する必要がありますか？型が file の別のパラメータを追加してください。メインファイルとサムネイルを受け入れる POST /documents は、file と thumbnail の2つのファイル行を受け取り、それぞれが独自の「アップロード」ボタンを持ちます。特別なマルチファイルモードはありません。エンドポイントが期待するすべてのパートをカバーするまで、ファイル型パラメータを追加するだけです。
リクエストを繰り返し可能なテストシナリオに変換する
1回の送信でエンドポイントが一度機能することを証明します。回帰を防ぐには、オンデマンドまたはスケジュールで実行される保存済みテストシナリオ内にアップロードを組み込むことが望ましいです。アバターをアップロードし、返された id を取得し、GET /users/{id} を呼び出して、アバターのURLが永続化したことを検証するというステップを連鎖させます。
単一のリクエストを構築したのと同じ方法でこれを構築し、シナリオのステップとして保存します。Apidogでテストシナリオを作成する方法ガイドでは、ステップの連鎖とステップ間の値の受け渡しについて説明しています。アップロードがシナリオに組み込まれると、デプロイごとにステージング環境に対して実行したり、APIテストシナリオに条件ロジックを使って条件分岐を追加したり、スケジュールされたAPIテストでタイマーを設定したりすることができます。
上記はすべて、あなたのマシンにファイルが存在するため、あなたのマシン上で問題なく実行されます。その前提こそが、次に壊れるものです。
落とし穴：別の場所で実行されるアップロード
ハッピーパスが隠している部分がここにあります。Apidogはファイル自体ではなく、ファイルパスを保存します。あなたのラップトップ上では、パスが常に実際のファイルに解決されるため、これは見えません。しかし、同じステップが別のマシンで実行された瞬間、そのパスは何も指さなくなります。
これには2つの場所で遭遇します。
チームコラボレーション。 チームメイトがあなたの POST /avatars リクエストを開くと、彼らはあなたが選択したファイルパラメータとパス（例えば /Users/jane/pics/jane-profile.png）を目にします。彼らはリクエストを見ることはできますが、それを送信することはできません。なぜなら、そのファイルは彼らのディスクではなく、あなたのディスクに存在しているからです。パスはそれを選択したマシンにローカルなものです。
RunnerおよびCLIの実行。 これは自動化で問題となる点です。アップロードシナリオはローカルではパスしますが、Runnerでスケジュールしたり、CLIから実行したりすると、ファイルアップロードステップが失敗します。アサーションに問題はありません。単にRunnerが、あなたのラップトップが保存したパスにあるファイルを見つけられないのです。なぜなら、そのパスはRunnerのホストには存在しないからです。
解決策はその原因に続きます。ファイルは送信を行うマシン上に存在し、ステップのパスはそのファイルを指している必要があります。
Runnerの場合： Runnerは、ボリュームにマウントされたホストディレクトリからファイルを読み取ります。このマウントは、-v フラグを使用してRunnerをデプロイするときに設定します。アップロードファイルをそのマウントされたホストディレクトリにコピーします。次に、シナリオ内のファイルアップロードステップのステップ詳細を開き、右上の「Batch Edit」ボタンをクリックし、ファイルフィールドの値をRunnerのディレクトリ内のパスに置き換えます。例えば、以下のようになります。
/opt/runner/jane-profile.png
CLIの場合： 同じ形式です。ファイルをCLIマシンに置き、ステップで「Batch Edit」を使用して、そこにあるファイルの場所にパスを指定します。例えば、以下のようになります。
/opt/apidog/runner/jane-profile.png
ハードコーディングよりもクリーンに：変数を使用する。 ステップにリテラルパスを固定する代わりに、値を変数に置き換え、その変数の値を環境ごとに実際のファイルパスに設定します。これにより、同じシナリオがあなたのラップトップ、Runner、そしてCIで、毎回ステップを編集することなく実行されます。変数をローカルでは /Users/jane/pics/jane-profile.png に、Runnerでは /opt/runner/jane-profile.png に指定することで、ステップ自体は決して変更されません。
明確に述べておくべき前提条件が1つあります。Runnerは、デプロイ時に -v でマウントしたディレクトリの下にあるホストファイルのみにアクセスできます。もしあなたのファイルがそのマウント下にない場合、どのパスもそれを見つけることはできません。これはデプロイメントの設定の詳細であり、計画上の制限ではありません。公式版が必要な場合は、ファイルアップロードリクエストに関するApidogドキュメントに、マウントと一括編集の手順が詳しく記載されています。
Apidog CLIでワークフローを自動化する
アップロードシナリオが保存されると、CIでヘッドレス実行できます。CLIをインストールして認証します。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
次に、保存されたシナリオをIDで実行し、環境を指定します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ここで、-t はテストシナリオID、-e は環境ID、-r はレポーター（cli、html、または junit を使用し、複数指定する場合はコンマで区切ります）です。CLIはクラウドプロジェクトから保存されたシナリオを実行し、終了コードで合否を報告します。これにより、パイプラインのゲートとして機能させることができます。セットアップの詳細については、Apidog CLIインストールガイドに記載されています。
正直な注意点が1つあります。これは前のセクションと同じ内容です。ファイルアップロードステップを含むシナリオは、CLIマシン上にファイルが存在している必要があり、ステップのパスはそのファイルを指している必要があります。ファイルをRunnerに置き、実行前にパスを「Batch Edit」するか（または変数を使用する）必要があります。これを怠ると、シナリオの残りの部分は問題なくても、アップロードステップはファイルを見つけることができません。行ごとの入力の受け渡しを含むより完全なCI設定については、Apidog CLIを使用したデータ駆動型テストを参照してください。
よくある質問
チームメイトが私のファイルアップロードリクエストを送信できないのはなぜですか？ Apidogはファイル自体ではなくローカルファイルパスを保存し、ファイルをクラウドにアップロードすることはありません。あなたのチームメイトはリクエストとあなたが選択したパスを見ますが、そのパスは彼らのディスクではなく、あなたのディスク上のファイルを指します。彼らが自分のマシンにファイルのコピーを置き、そのフィールドを自分のパスに指定するようにしてください。スケジュールされたテストやRunnerジョブが実行される場所にファイルを配置する必要があるのも、同じ仕組みによるものです。
同じリクエストでファイルと一緒にJSONを送信するにはどうすればよいですか？ ボディタイプを form-data のままにします。型が file のファイルフィールドを追加し、次に型が string の別のパラメータを追加し、その値にJSONを貼り付けます。サーバーは1つのマルチパートリクエストで両方のパートを受け取ります。つまり、一方のパートにファイルが、もう一方にJSON文字列が含まれます。これは、アップロードにメタデータを添付する標準的な方法です。
Runnerでファイルに使用すべきパスは何ですか？ デプロイ時に -v フラグでRunnerのボリュームにマウントしたホストディレクトリ内のパスを使用します。例えば /opt/runner/yourfile.jpg のようにです。ファイルをそのマウントされたディレクトリにコピーし、次にステップを開き、「Batch Edit」をクリックして、フィールドの値をそのパスに設定します。CLIでの同等のパスは /opt/apidog/runner/yourfile.jpg のようになります。
ファイルサイズ制限や許可されるファイルタイプリストはありますか？ Apidogでのアップロードの動作は、リクエストがどのように構築され、ファイルがどこから読み込まれるかに関するものです。サイズやタイプに関する実際の制限は、テストしているAPIに由来するため、サーバー独自の検証ルールを確認し、サイズが大きすぎるファイルや拒否されたファイルに対して返される応答を検証するアサーションを記述してください。
アップロードにはform-dataとx-www-form-urlencodedのどちらを使うべきですか？ form-data を使用してください。これは multipart/form-data にマッピングされ、ファイルを運ぶために構築されています。x-www-form-urlencoded は、ファイルを含まない短いスカラーフィールドの単純なフォーム用であり、画像やPDFを運ぶことはできません。
まとめ
ファイルアップロードのテストは、2つのことに集約されます。マルチパートリクエストを正しく構築すること、そしてテストが実行される場所でファイルにアクセスできることを確認することです。Apidog では、ボディを form-data に設定し、フィールドのタイプを file に変更し、「アップロード」をクリックし、JSONがあればそれを文字列パートとして追加し、その後送信して検証します。同じシナリオをRunnerやCLIに移行する際は、そのマシンにファイルを準備し、「Batch Edit」または変数でパスを再指定すれば、自動化された実行がローカルでの実行と同様に機能します。
ご自身のエンドポイントで試してみたいですか？Apidogをダウンロードし、アップロードルートに form-data リクエストを送り、応答が返ってくるのを確認してください。無料で始められ、クレジットカードは不要です。