DEV Community

Cover image for Cách sử dụng Scripts trước yêu cầu và sau phản hồi trong Apidog
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách sử dụng Scripts trước yêu cầu và sau phản hồi trong Apidog

Một số yêu cầu cần được xử lý trước khi rời khỏi máy của bạn, và một số cần được xử lý ngay khi nhận được phản hồi. Một API thanh toán muốn có chữ ký HMAC được tính toán từ một dấu thời gian và khóa bí mật của bạn. Một điểm cuối đăng nhập trả về một mã thông báo mà mọi cuộc gọi sau đó đều cần. Một quy trình thanh toán phải xác nhận rằng phản hồi thực sự trả về mã 200 và ID đơn hàng chính xác. Bạn có thể tự làm tất cả những điều này, nhưng sẽ rất tốn thời gian và dễ bị lỗi khi chia sẻ yêu cầu với đồng đội.

Dùng thử Apidog ngay hôm nay

Script giải quyết vấn đề này. Trong Apidog, bạn có thể đính kèm các đoạn JavaScript nhỏ vào một yêu cầu để chúng tự động chạy: một nhóm trước khi yêu cầu được gửi và một nhóm khác sau khi phản hồi quay về. Nếu đã từng viết script Postman, bạn vẫn có thể dùng API đối tượng pm quen thuộc vì engine của Apidog tương thích với API này.

Bài viết này triển khai một luồng thực tế:

  1. Ký yêu cầu bằng HMAC trong Pre Processors.
  2. Trích xuất mã thông báo trong Post Processors.
  3. Xác nhận mã trạng thái và dữ liệu phản hồi.
  4. Tái sử dụng logic bằng Public Scripts.
  5. Chạy kịch bản trong CI với Apidog CLI.

Hành vi scripting được mô tả trong tài liệu scripting của Apidog, nhưng tên tab và một số chi tiết khác với Postman cần được lưu ý.

Script tiền xử lý và hậu xử lý thực sự làm gì?

Apidog chạy script theo hai giai đoạn.

Pre Processors: chuẩn bị yêu cầu trước khi gửi

Pre Processors chạy trước khi yêu cầu được gửi đến máy chủ. Dùng chúng để:

  • Tạo dấu thời gian.
  • Tính chữ ký HMAC.
  • Sinh ID đơn hàng hoặc request ID.
  • Đọc biến và chuyển thành header.
  • Chuẩn bị dữ liệu body hoặc query parameter.

Ở thời điểm này, phản hồi chưa tồn tại. Vì vậy, bạn không thể kiểm tra pm.response trong Pre Processor.

Post Processors: kiểm tra và tái sử dụng phản hồi

Post Processors chạy sau khi nhận phản hồi. Dùng chúng để:

  • Kiểm tra mã trạng thái.
  • Xác nhận cấu trúc JSON.
  • Trích xuất token xác thực.
  • Lưu ID tài nguyên vừa tạo.
  • Lưu cursor phân trang cho yêu cầu tiếp theo.

Ví dụ, pm.response với các thuộc tính như code, status, headers, responseTime, responseSize, text() và json() chỉ hoạt động trong Post Processors.

Hai giai đoạn trao đổi dữ liệu thông qua biến:

Pre Processor → thiết lập biến → request sử dụng biến → Post Processor đọc hoặc cập nhật biến
Enter fullscreen mode Exit fullscreen mode

Nếu chuyển từ Postman, hãy chú ý tên tab:

Postman Apidog
Pre-request Script Pre Processors
Tests Post Processors

Hành vi tương tự, nhưng vị trí trên giao diện khác nhau.

Thiết lập: mở yêu cầu và tìm các tab script

Tải Apidog nếu bạn chưa cài đặt. Công cụ chạy trên macOS, Windows và Linux.

Sau đó:

  1. Mở một API request trong Apidog.
  2. Tìm tab Pre Processors hoặc Post Processors.
  3. Chọn add a Custom Script.
  4. Viết JavaScript sử dụng đối tượng pm.

Trước khi bắt đầu, cần hiểu thứ tự ưu tiên của biến trong Apidog:

Biến cục bộ (Local Variables) > Biến môi trường (Environment Variables) > Biến toàn cục chia sẻ trong dự án (Global Variables Shared within Project) > Biến toàn cục chia sẻ trong nhóm (Global Variables Shared within Team).

Nếu một biến không có giá trị như mong đợi, hãy kiểm tra xem biến có cùng tên ở cấp ưu tiên cao hơn hay không.

Với cấu hình ổn định, dùng chung cho dự án, bạn có thể lưu trong các tham số toàn cục của Apidog.

Ví dụ Pre Processor: ký yêu cầu bằng HMAC

Giả sử bạn gọi một API thanh toán yêu cầu chữ ký HMAC-SHA256 cho từng request.

Mẫu phổ biến là:

payload = timestamp + "\n" + raw_request_body
signature = HMAC_SHA256(payload, secret)
Enter fullscreen mode Exit fullscreen mode

Nhiều nhà cung cấp API dùng mẫu tương tự để xác thực webhook. Tài liệu chữ ký webhook của Stripe mô tả rõ cách máy chủ xác minh timestamp, payload và secret.

Bước 1: Tạo biến môi trường

Tạo biến môi trường:

payments_api_secret = your-secret-key
Enter fullscreen mode Exit fullscreen mode

Không hard-code khóa bí mật trực tiếp trong script.

Bước 2: Thêm HMAC script vào Pre Processors

Mở Pre Processors → add a Custom Script, sau đó thêm:

// Pre Processor: ký yêu cầu trước khi nó được gửi
const CryptoJS = require('crypto-js');

// Dấu thời gian Unix hiện tại, tính bằng giây
const timestamp = Math.floor(Date.now() / 1000).toString();

// Đọc khóa bí mật từ biến môi trường
const secret = pm.environment.get('payments_api_secret');

// Xây dựng payload: timestamp + xuống dòng + body thô
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;

// Tính HMAC-SHA256 và mã hóa hexadecimal
const signature = CryptoJS
  .HmacSHA256(payload, secret)
  .toString(CryptoJS.enc.Hex);

// Lưu giá trị để request sử dụng
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);

pm.console.log('Đã ký yêu cầu vào ' + timestamp);
Enter fullscreen mode Exit fullscreen mode

Bước 3: Dùng biến trong request headers

Mở tab Headers và thêm:

X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Enter fullscreen mode Exit fullscreen mode

Khi gửi request, thứ tự chạy sẽ là:

  1. Pre Processor tạo timestamp.
  2. Pre Processor tính signature.
  3. Apidog lưu các giá trị vào environment.
  4. Apidog thay {{x_timestamp}} và {{x_signature}} vào headers.
  5. Request được gửi đến máy chủ.

Lưu ý: Apidog hỗ trợ import toàn bộ module:

const CryptoJS = require('crypto-js');
Enter fullscreen mode Exit fullscreen mode

Không dùng đường dẫn submodule như:

require('crypto-js/sha256');
Enter fullscreen mode Exit fullscreen mode

Các thao tác biến chỉ cập nhật giá trị hiện tại, không phải giá trị ban đầu được nhập trong trình chỉnh sửa môi trường. Đây là hành vi phù hợp với timestamp và chữ ký ngắn hạn.

Nếu cần chuyển đổi từ script Postman, xem thêm bài viết về script tiền yêu cầu của Postman.

Ví dụ Post Processor: trích xuất token và xác nhận phản hồi

Giả sử endpoint đăng nhập trả về:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": 4812, "email": "dana@example.com" },
  "expires_in": 3600
}
Enter fullscreen mode Exit fullscreen mode

Mục tiêu là:

  • Xác nhận HTTP status là 200.
  • Kiểm tra token tồn tại và là chuỗi.
  • Kiểm tra user.id là số.
  • Lưu token để dùng trong các request tiếp theo.

Mở Post Processors → add a Custom Script và thêm:

// Post Processor: xác minh phản hồi, sau đó trích xuất mã thông báo
pm.test('Trạng thái là 200', function () {
  pm.response.to.have.status(200);
});

const jsonData = pm.response.json();

pm.test('Phản hồi trả về một mã thông báo', function () {
  pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});

pm.test('ID người dùng có mặt', function () {
  pm.expect(jsonData.user.id).to.be.a('number');
});

// Lưu token để các request khác sử dụng
pm.environment.set('auth_token', jsonData.token);

pm.console.log('Đã lưu mã thông báo cho người dùng ' + jsonData.user.email);
Enter fullscreen mode Exit fullscreen mode

Sau đó, trong các endpoint cần xác thực, thêm header:

Authorization: Bearer {{auth_token}}
Enter fullscreen mode Exit fullscreen mode

Kết quả: bạn không cần sao chép token thủ công từ phản hồi đăng nhập sang từng request khác.

Các khối pm.test() biến thao tác gửi request thủ công thành một bài kiểm thử có thể lặp lại. Apidog hỗ trợ các matcher kiểu Chai thông qua pm.expect().

Để tìm hiểu thêm về assertion, xem hướng dẫn xác nhận API trong Apidog. Nếu cần tạo dữ liệu giả, bạn có thể kết hợp với Faker.js trong Apidog.

Lưu ý trong Post Processors

  • pm.iterationData là chỉ đọc. Bạn có thể đọc dữ liệu kiểm thử nhưng không thể ghi lại vào đó.
  • pm.cookies trả về cookie trong phản hồi từ máy chủ, không phải cookie đã gửi đi cùng request.

Tái sử dụng logic với Public Scripts

Nếu cần dùng cùng một logic HMAC cho nhiều endpoint, không nên sao chép script vào từng request. Khi thuật toán hoặc payload thay đổi, bạn sẽ phải sửa ở nhiều nơi.

Thay vào đó, dùng Public Scripts.

Cách tạo Public Script

  1. Mở Settings > Public Scripts.
  2. Tạo script dùng chung.
  3. Đính kèm script vào Pre Processors hoặc Post Processors của request.

Thứ tự chạy rất quan trọng:

  • Public Scripts chạy trước Custom Scripts trong cùng danh sách.
  • Nếu có nhiều Public Scripts, chúng chạy từ trên xuống dưới theo thứ tự hiển thị.

Chia sẻ hàm giữa Public Script và Custom Script

Nếu Custom Script cần gọi một hàm từ Public Script, hàm đó phải là biến toàn cục.

Trong Public Script:

// Biến sign() thành hàm toàn cục bằng cách không dùng var, let hoặc const
sign = function (payload, secret) {
  const CryptoJS = require('crypto-js');

  return CryptoJS
    .HmacSHA256(payload, secret)
    .toString(CryptoJS.enc.Hex);
};
Enter fullscreen mode Exit fullscreen mode

Trong Custom Script đặt bên dưới Public Script:

const timestamp = Math.floor(Date.now() / 1000).toString();
const secret = pm.environment.get('payments_api_secret');

pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', sign(timestamp, secret));
Enter fullscreen mode Exit fullscreen mode

Nếu khai báo hàm với const, let, var hoặc đặt Custom Script trước Public Script, bạn có thể gặp lỗi hàm không xác định.

Thư viện, gói bên ngoài và gỡ lỗi

Apidog có sẵn một số thư viện để dùng trực tiếp qua require().

  • crypto-js (v3.1.9-1) để băm và HMAC.
  • jsrsasign (v10.3.0) cho JWT và RSA, yêu cầu Apidog 1.4.5 trở lên.
  • chai (v4.2.0) cho assertion matcher.
  • lodash
  • moment
  • uuid
  • xml2js
  • cheerio
  • postman-collection
  • atob
  • btoa
  • csv-parse/lib/sync
  • tv4
  • ajv

Ngoài ra còn có các thư viện tích hợp của Node như:

path, assert, buffer, util, url, querystring, stream, events
Enter fullscreen mode Exit fullscreen mode

Tải gói ngoài bằng $$.liveRequire()

Nếu package không có sẵn, dùng $$.liveRequire():

$$.liveRequire('nanoid', (nanoid) => {
  const id = nanoid.nanoid();

  pm.environment.set('request_id', id);
});
Enter fullscreen mode Exit fullscreen mode

Cách này yêu cầu kết nối internet vì Apidog tải package khi script chạy.

Gỡ lỗi bằng console

Dùng một trong hai cách:

pm.console.log('Giá trị biến:', pm.environment.get('auth_token'));
Enter fullscreen mode Exit fullscreen mode

Hoặc:

console.log('Chữ ký đã tạo:', signature);
Enter fullscreen mode Exit fullscreen mode

Cả pm.console.log() và console.log() đều in ra console của Apidog. Đây là cách nhanh nhất để kiểm tra payload, signature, token hoặc dữ liệu phản hồi.

Hai giới hạn cần lưu ý

pm.sendRequest() dùng callback thay vì Promise. Không dùng await:

pm.sendRequest('https://example.com/api', function (error, response) {
  if (error) {
    console.log(error);
    return;
  }

  console.log(response.json());
});
Enter fullscreen mode Exit fullscreen mode

Ngoài ra, pm.nextRequest() của Postman không được hỗ trợ.

Khi cần điều phối workflow có nhánh, điều kiện hoặc nhiều bước, hãy dùng Kịch bản kiểm thử (Test Scenarios). Bạn có thể sắp xếp request trực quan với các bước Condition và If-Else.

Tự động hóa workflow với Apidog CLI

Script không chỉ chạy khi bạn nhấn nút Send. Khi đóng gói request và assertion trong một Test Scenario đã lưu, bạn có thể chạy toàn bộ kịch bản bằng Apidog CLI, bao gồm cả Pre Processors và Post Processors.

Cài đặt CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Đăng nhập bằng access token:

apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Chạy một test scenario:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
Enter fullscreen mode Exit fullscreen mode

Ý nghĩa các cờ:

Cờ Ý nghĩa
-t ID của Test Scenario
-e ID môi trường
-r Reporter: cli, html hoặc junit

Bạn có thể dùng nhiều reporter, phân tách bằng dấu phẩy.

Tạo access token trong cài đặt tài khoản Apidog, xuất thành biến APIDOG_ACCESS_TOKEN, rồi chạy command này trong CI.

Lưu ý: script phụ thuộc vào tài nguyên chỉ có trên máy local, chẳng hạn tệp cục bộ hoặc package chỉ từng được tải thủ công, có thể chạy trong desktop app nhưng thất bại trong CLI. Để script chạy nhất quán, ưu tiên thư viện tích hợp sẵn hoặc $$.liveRequire().

Câu hỏi thường gặp

Script Apidog có tương thích với script Postman hiện có không?

Phần lớn là có. Apidog sử dụng cùng API đối tượng pm, nên các lệnh sau hoạt động theo cách quen thuộc:

pm.environment.set();
pm.response.json();
pm.test();
pm.expect();
Enter fullscreen mode Exit fullscreen mode

Khác biệt chính là tên tab:

  • Apidog: Pre Processors và Post Processors
  • Postman: Pre-request Script và Tests

Một số API như pm.nextRequest() không được hỗ trợ.

Vì sao pm.response là undefined trong Pre Processor?

Vì phản hồi chưa tồn tại. Pre Processors chạy trước khi request được gửi.

Mọi code đọc status, body hoặc header từ pm.response phải nằm trong Post Processors. Nếu cần dữ liệu ở giai đoạn trước, lấy từ pm.request, biến môi trường hoặc thư viện phù hợp. Xem thêm cách lấy request params trong pre/post request scripts.

Làm cách nào để chia sẻ script cho nhiều request?

Dùng Public Scripts tại Settings > Public Scripts.

Viết logic một lần, sau đó đính kèm vào Pre Processors hoặc Post Processors của từng request. Public Script chạy trước Custom Script trong cùng danh sách.

Nếu Custom Script cần gọi hàm từ Public Script, khai báo hàm ở phạm vi toàn cục:

myFunction = function () {
  // logic dùng chung
};
Enter fullscreen mode Exit fullscreen mode

Tôi có thể dùng package npm không có sẵn trong Apidog không?

Có. Dùng:

$$.liveRequire('tên-gói', (pkg) => {
  // sử dụng pkg
});
Enter fullscreen mode Exit fullscreen mode

Lệnh này tải package khi chạy nên cần internet.

Với package tích hợp sẵn như crypto-js, moment hoặc uuid, chỉ cần dùng require():

const CryptoJS = require('crypto-js');
Enter fullscreen mode Exit fullscreen mode

Bạn phải import toàn bộ module, không dùng đường dẫn submodule.

Xem log từ script ở đâu?

Dùng:

pm.console.log('debug message');
Enter fullscreen mode Exit fullscreen mode

Hoặc:

console.log('debug message');
Enter fullscreen mode Exit fullscreen mode

Sau khi gửi request, xem kết quả trong console của Apidog.

Tóm lại

Pre Processors và Post Processors giúp request tự chuẩn bị và tự xác minh:

  • Ký request trước khi gửi.
  • Trích xuất token sau khi nhận phản hồi.
  • Xác nhận status code và cấu trúc dữ liệu.
  • Lưu biến để tái sử dụng trong các request tiếp theo.
  • Đưa logic dùng chung vào Public Scripts.
  • Chạy toàn bộ kịch bản trong CI bằng Apidog CLI.

Mở Apidog, chọn một request và thêm Custom Script đầu tiên để tự động hóa luồng API của bạn.

Top comments (0)