📚

Postman : スクリプト機能から外部パッケージの呼び出しと実行

2025/09/08に公開

過去の記事でPostmanコレクション（テスト用APIコール）で、API呼び出しの前と後でぞれぞれパラメータやレスポンスを操作可能なスクリプト機能を紹介しました。

2025年8月に本機能が拡張されnpmかJSR外部レジストリから呼び出したパッケージをインポートして操作できるようなりました。

これにより、UUID生成、日付操作、データ整形などを独自で書かなくてもライブラリに任せることが可能になります。
Professional / Enterprise プランでは、管理者が権限を設定したプライベート npm パッケージを利用することもできます。パッケージのインポートは以下の書式で行えます。

pm.require("npm:パッケージ名@バージョン"),pm.require("jsr:パッケージ名@バージョン")

さっそくやってみる

ではPostmanが提供しているエコー用エンドポイントであるhttps://postman-echo.com/postを使って、APIリクエスト前にスクリプトを実行するpre-requestで外部パッケージをインポートしてみます。
サンプルではuuidというパッケージを使います。

uuid パッケージ

uuidとは世界的に一意な識別子（128ビットの値）です。テスト用に生成されるuuidは衝突の可能性はほぼない、と言われていますが、一意性を保証していませんので注意してください。文字列としては通常「xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx」という36文字形式で表記されます。

1. Collection で Postリクエストを作成

とてもシンプルにPOSTリクエストを作成してテストしておきます。

以下の通りエンドポイントからエコーバックが戻りますが、特に何もPOSTしていませんのですべて空欄です。

{
    "args": {},
    "data": {},
    "files": {},
    "form": {},
    "headers": {
        "host": "postman-echo.com",
        "x-request-start": "t1757304437.298",
        "connection": "close",
        "content-length": "0",
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "x-amzn-trace-id": "Root=1-68be5675-7c4082fa7d555fdf787e8a02",
        "user-agent": "PostmanRuntime/7.45.0",
        "accept": "*/*",
        "postman-token": "acad4a16-e538-4d0a-8bd3-a79a40d65e24",
        "accept-encoding": "gzip, deflate, br",
        "cookie": "sails.sid=s%3ArNxFFWhFtPOsFwHFhAaRtu0FUPYllOhP.MhIb782URClHaSBIptg2znR65BfMxySLWTapN4JSf60"
    },
    "json": null,
    "url": "https://postman-echo.com/post"
}

2. Pre-Request でUUIDの生成とJSON Bodyへの挿入

ではPre-Requestタブで以下のスクリプトを挿入します。

const { v4: uuidv4 } = pm.require("npm:uuid@9.0.1");
pm.variables.set("uuid", uuidv4());

uuidを生成する外部パッケージを呼び出し生成しています。

次にボディタブでJSONを挿入します。形式はRaw→JSONを指定します。

{
  "requestId": "{{uuid}}",
  "user": { "name": "test-user", "score": 42 },
  "tags": ["alpha","beta","gamma"]
}

実行すると以下の様に生成されたuuidがPOSTされた後エコーバックされ戻ってきていることがわかります。

{
    "args": {},
    "data": {
        "requestId": "aed7a5e1-ee1a-4fea-b6f8-d415da7e7ef7",
        "user": {
            "name": "test-user",
            "score": 42
        },
        "tags": [
            "alpha",
            "beta",
            "gamma"
        ]
    },
<snip>

3. Post-Response

では次にエコーバックされたjsonを操作してコンソールに出力するスクリプトをPost-responseに挿入します。

const _ = pm.require("npm:lodash@4.17.21");
const dayjs = pm.require("npm:dayjs@1.11.13");

const res = pm.response.json();

// 送信したデータ（sent）を安全に取り出す
let sent = null;
if (res && res.json && typeof res.json === "object") {
  // JSONとして送った場合はこちらが最優先（すでにオブジェクト）
  sent = res.json;
} else if (res && typeof res.data === "string" && res.data.length > 0) {
  // 文字列として返ってくる場合のみ parse
  sent = JSON.parse(res.data);
}

// 念のためチェック
pm.test("送信データを取得できた", () => {
  pm.expect(!!sent, "res.json/res.data どちらにも中身がありません").to.be.true;
});

// ここから加工例
const prettyName = _.startCase(sent.user.name);
const sortedTags = _.sortBy(sent.tags);
const stamped = { ...sent, processedAt: dayjs().toISOString() };
const picked = _.pick(stamped, ["requestId", "user", "processedAt"]);

// 検証
pm.test("requestId は UUID 形式", () => {
  pm.expect(picked.requestId).to.be.a("string").and.have.lengthOf(36);
});
pm.test("tags が昇順ソート", () => {
  pm.expect(sortedTags).to.eql(["alpha","beta","gamma"]);
});

// デバッグ
console.log("typeof res.json:", typeof res.json, "typeof res.data:", typeof res.data);
console.log({ prettyName, sortedTags, picked });

配列操作・オブジェクト操作・文字列操作などを行うlodash、日付操作ライブラリのdayjsをインポートしています。
実行を行うとコンソールにレスポンスのJSONをパースした値が表示されます。

例えばPostman Flowsを使ってこのAPIコールの結果をもとに次のAPIコールに引き渡す際の値を抽出することができます。