PostmanでDify API (Chatbotアプリ) をテストする

Difyで作成したアプリはDifyのバックエンドAPIを経由してアクセスが可能です。ここでは、Difyで作成した[Chatbotアプリ](https://docs.dify.ai/ja-jp/guides/application-orchestrate/chatbot-application)をPostman経由でテストする方法について解説します。

なお、すでにこちらの記事にてPostmanでDify APIにリクエストを送信するまでの流れが分かりやすく書かれているので、本記事ではPostmanの使い方を中心に紹介します。

https://zenn.dev/kameoncloud/articles/c9af9b57b52525

以下、すでにDifyでChatbotアプリを構築済みであること前提に説明します。

## 1. Postmanアプリの準備

### ワークスペースの用意
Postmanアプリを立ち上げて、**Internalタイプ（以前はPersonal）** のワークスペースを用意する。Postmanアカウントを作成するとデフォルトでMy Workspaceという名前のInternalタイプのワークスペースが作成されているので、特にこだわりがなければそれを使ってください。

### コレクションの作成

事前にDify API用のコレクションを作成します。ワークスペースの左上にある「十」をクリックして新しいコレクションを作成してください。ここでは名前を`Dify`とします。

![Screenshot 2025-04-04 at 20.58.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/c1a3d646-938e-44e4-b67f-52124bea9e06.png)

### 日本語設定の紹介

これは、日本語設定したい人向け。日本語希望でなければスキップしてください

アプリ画面右上の⚙️をクリック > Settings > General > Application > Languageで日本語選択

![Screenshot 2025-04-04 at 20.44.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/1e7bbe0b-7045-4d3a-b968-52c66d3da90f.png)


### 自動保存設定の紹介

これは、自動保存設定したい人向け。自動保存希望でなければスキップしてください。自動保存を有効化していない場合は、設定追加・変更のたびに保存することをお忘れなく

アプリ画面右上の⚙️をクリック > 設定 > 一般> アプリケーション> 自動保存(Autosave)をチェック

![Screenshot 2025-04-04 at 20.44.36.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/878ced1b-a5c7-406a-bc75-d2bc7136ba46.png)

## 2. Dify API（Send Chat Message）をPostmanにインポート

まずは、DifyアプリのAPIアクセスページを開いて、下記イメージを参考に次の2つのことを行います。
- DifyアプリのAPIアクセスに必要なAPIキーを発行する
- Send Chat Message用のcurlコマンドをコピーする

![Screenshot 2025-04-04 at 20.21.59.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/e6c59d86-e323-4905-8535-6139acb18c5c.png)

コピーしたSend Chat Message用のcurlコマンドの本文のところにある`response_mode`がデフォルト`streaming`になってますが、これを`blocking`に変更します。変更したらこのような内容になっているはずです。

```bash
curl -X POST '<server-url>/v1/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {},
    "query": "What are the specs of the iPhone 13 Pro Max?",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "abc-123",
    "files": [
      {
        "type": "image",
        "transfer_method": "remote_url",
        "url": "https://cloud.dify.ai/logo/logo-site.png"
      }
    ]
}'
```

次に、1で用意したワークスペースの左上にある「インポート」ボタンをクリックする。インポート用モーダルが表示されるので、そこのテキストボックスに上記のcurlコマンドを貼り付けます。

![Screenshot 2025-04-04 at 20.51.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/015fccd0-2b4e-48a2-ba11-a17ee66df9ed.png)

無事、curlが読み込まれると、次のようなモーダルが表示されます。ここで、APIリクエストの格納先にさきほど作成したコレクション（`Dify`）を選んで「コレクションにインポート」ボタンをクリックしてください。これでインポートと完了です。

![Screenshot 2025-04-04 at 21.13.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/1673ef10-e076-484b-b9c6-cfde68aeb1ac.png)


## 3. APIキー認証の設定

APIリクエスト設定の「認可」メニューをクリックします。Auth Typeの中から「Bearerトークン」を選択して、フォームにさきほど取得したAPIキーを貼り付けます。

![Screenshot 2025-04-04 at 21.32.00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/98ab275d-6cce-44aa-abfd-4b4b10c66da3.png)

これで、APIリクエスト送信のための準備完了です。

## 4. APIリクエストを送信してみる

リクエスト本文のプロパティqueryメッセージを変えてみて、「送信」ボタンを押してリクエストを送信してみてください。成功すれば画面下半分のレスポンス表示部分に次のような結果のJSONが表示されるはずです。

![Screenshot 2025-04-04 at 21.40.08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/f993effd-b5ec-4695-8cd5-18efbd938a1b.png)

レスポンスに含まれる、conversation_idを取得してください。conversation_idを指定することで、特定のスレッドで会話を続けることができます。
今度はリクエスト本文のqueryメッセージを変えて、さらに取得したconversation_idを指定してリクエストを送信してみてください。初回リクエストと同様に、画面下半分のレスポンス表示部分に次のような結果のJSONが表示されるはずです。

![Screenshot 2025-04-05 at 7.43.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/4b228cbc-d0a4-4a49-9b25-90c56f51879b.png)

:::note
とりあえず、ここまでの設定で、最低限、PostmanでDify API (Chatbotアプリ) のテストができます。これ以降のトピックは、推奨設定またはTipsですので、余力がある人、興味がある人だけ読み進めてください。
:::

## 5. ベースURLとAPIキーを環境に保存

APIリクエストにおける、ベースURLとAPIキーはいわゆる実行する環境によって異なる値になる可能性があります。例えば、ローカル開発・本番環境などではそれぞれ異なるDifyバックエンドとなるため、これらの値は変わってきます。こういった場合に便利なのがPostmanの環境（Environment）という変数セットを格納する箱です。環境ごとにPostman環境という箱を用意して、ローカル開発 or 本番など利用環境に応じてなど箱を切り替えて利用できるイメージです。
ここでは、ベースURLとAPIキーを環境に保存して利用する方法を紹介します。

- ベースURL : Dify APIのベースとなるURL（例: http://xx.xx.xx.xx/v1 ）
- APIキー : Dify APIのAPIキー（例: app-****** ）

### 環境の設定

下図のように、サイドバーの環境をクリックして、環境変数を設定します:

![Screenshot 2025-04-05 at 4.32.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/0de6da8e-9753-4c00-8c19-a7e9c91d5018.png)

- ワークスペースの左上の「十」をクリックして新しい環境（環境変数を格納するための箱）を作成。ここでは名前を`Dify`
- `Dify`環境に次の2つの変数を作成
  - `baseUrl` (タイプ: デフォルト): ベースURLの値を初期値・現在値の両フィールドに設定 
  - `apiKey` (タイプ: シークレット): APIキーの値を初期値・現在値の両フィールドに設定 

### 環境に保存された変数の活用

下図のように、APIリクエスト設定画面にて、活用する環境を選択してから、`{{変数名}}`の形式で環境変数を参照してください。ここでは、ベースURLとAPIキー部分の文字列を、それぞれ`{{baseUrl}}`と`{{apiKey}}`に変更ください。

![Screenshot 2025-04-05 at 4.59.14.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/adc7a59a-b60b-4bb2-80d1-62f6f2b0b9f4.png)

問題なく変数の値が参照されるようになると、それぞれの{{変数}}のところにマウスカーソルをホバーさせてみた時、参照先の値が表示されます。

この状態で、再びAPIリクエストを送信してみてください。画面下半分のレスポンス表示部分に200ステータスのレスポンスが表示されたらOKです。

:::note 
補足記事: 変数設定に関するもろもろの詳細については記事「[徹底解説 - Postman 変数 (Variables)](https://qiita.com/yokawasa/items/05913df60aea07395903
)」が参考になります。
:::


## 6. APIキーをPostman Vaultに保存 (ローカル実行のみ)

:::note warn
（2025/04時点）Postman Vaultはローカル実行時でのみ有効な手法です。もし、**このAPIリクエスト設定をクラウド実行する場合、秘匿情報の扱いはPostman Vaultではなく環境の活用をおすすめします**。

次のようなケースでは、APIリクエストはクラウドで実行されます:

- コレクションのスケジュール実行 （モニター経由の実行含む）
- Webhook経由での実行（PublishされたPostman Flowsからの実行も含む）

どういう場合にクラウド実行なのかについては、記事「[Postmanのテスト実行オプションとそれぞれの実行場所 (ローカル or クラウド)と注意点について](https://qiita.com/yokawasa/items/49ab5cef18d1a71888a2)」に詳しい説明があります。
:::

PostmanでAPIキーなど秘匿情報を扱う場合に最も活用をおすすめしたいのが[Postman Vault](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/)です。Postman Vaultは、2024年5月発表の比較的新しい機能で、秘匿情報を安全にPostmanのローカルインスタンスに格納し、end-to-endで安全に参照できるようにする仕組みです。
ここでは、APIキーをPostman Vaultに保存して利用する方法を紹介します。

Postmanアプリのフッターにある「`Vault`」をクリックすると、ローカルVault設定画面が表示されます。ここで、DifyアプリのAPIキーをキー名 `apiKey`で保存してください。「許可されたドメイン」のところでVault変数を利用できるドメインを指定できますが、ここではブランク（全てのドメインから利用可能）でOKです。

![Screenshot 2025-04-05 at 5.46.34.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/b8e40c57-4b40-49fc-83b9-bf79b395b3b3.png)

次に、APIリクエスト設定画面にて、Bearerトークン入力部分に、`{{vault:apiKey}}`と入力してください。Postman Vaultに設定した変数は`{{vault:変数名}}`で参照できます。

![Screenshot 2025-04-05 at 5.55.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/1c8849c4-ce1f-4dc9-844b-3cbdcf16a054.png)

この状態で、再びAPIリクエストを送信してみてください。画面下半分のレスポンス表示部分に200ステータスのレスポンスが表示されたらOKです。


## 7. Postmanコンソールを確認してみる（デバッグ用）

Postmanコンソールで、これまで送信したAPIリクエストの詳細情報をみてみましょう。
Postmanコンソールには全てのPostmanアプリ経由のAPIコールが、ヘッダー、ネットワーク情報、ペイロードと共に記録されるので、デバッグやトラブルシューティングに利用できます。

それでは、フッターメニューの「`コンソール(Console)`」をクリックして、Postmanコンソールを開いてみてください。これまでAPIリクエストの情報が確認できるはずです。

![Screenshot 2025-04-05 at 6.16.09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/053012e0-e363-427c-8dae-72192b63e00a.png)

ちなみに、コンソールはPostmanスクリプトを使う場合に、スクリプト内部からのconsole.log()、console.info()、console.warn()、console.error()でデバッグ用メッセージを出力させることができ、スクリプトのデバッグ用途にも活用できます。

## 8. コードスニペット

PostmanのAPIリクエスト設定から、Python、JavaScript、NodeJS、Ruby、Goなど、さまざまなプログラミング言語用クライアントライブラリのコードスニペットを生成できます。

APIリクエスト設定画面の右サイドバーにある「`＜/＞`」をクリックすると、言語ごとのコードスニペットが選択できます。

![Screenshot 2025-04-05 at 6.27.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/fc8ea520-eb98-4aad-be07-6c7fdd8615b1.png)


最終的に、PostmanでテストしたAPIリクエストをアプリケーションに組み込む場合には、とても便利です。選択可能な言語フレームワークの詳細は[こちら](https://learning.postman.com/docs/sending-requests/create-requests/generate-code-snippets/)のページに書いてあります

他にもPostmanにはいろんな便利機能がありますが、これくらいにしておきます。


## 9. おまけ: Dify APIのPostmanコレクション

最後に、Dify API用（いまのところChatアプリのみ）のコレクションを作っておきました。よかったらフォークして使ってみてください。

[ Dify API用のパブリックワークスペース](https://www.postman.com/what-is-api-first/dify-api/overview)

![Screenshot 2025-04-05 at 7.06.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/69bc7625-76df-45a7-bbab-c3d5d42ca7a7.png)