سفارشی‌سازی دکمه Run in Postman

اگر ناشر API هستید، می‌توانید دکمه Run in Postman را فقط به یک لینک ساده محدود نکنید. در نسخه HTML این دکمه، می‌توانید با متد _pm() اطلاعاتی مثل API key، توکن یا مقدارهای اولیه را به environment کاربر اضافه کنید تا کاربر بعد از fork کردن کالکشن، سریع‌تر درخواست‌ها را اجرا کند.

این روش برای وب‌سایت‌هایی مفید است که کاربر در همان صفحه مقدارهایی مثل کلید staging، کلید production یا توکن ورود را وارد می‌کند و شما می‌خواهید این مقدارها هنگام شروع کار در Postman آماده باشند.

ساخت environment جدید

برای ساخت یک environment خالی یا پرشده با مقدارهای اولیه، از env.create استفاده می‌شود:

_pm('env.create', 'environment_name', { key: value }, runButtonIndex);

این متد برای کپی کردن environmentهای موجود نیست. اگر نام environment از قبل وجود داشته باشد، درخواست شکست می‌خورد. همچنین ساخت environment به معنی فعال شدن خودکار آن نیست؛ فقط environment را کنار دکمه در دسترس قرار می‌دهد.

نمونه ساده برای ساخت environment با کلیدهایی که کاربر در سایت وارد کرده است:

function createApiKeysEnvironment() {
  var stagingKey = document.getElementById('staging-key-input').value;
  var productionKey = document.getElementById('production-key-input').value;
  var runButtonIndex = 0;

  _pm('env.create', 'API Keys', {
    stagingKey: stagingKey,
    productionKey: productionKey
  }, runButtonIndex);
}

در صورت موفقیت، env.create تعداد environmentهای مرتبط با دکمه‌های Run in Postman صفحه را برمی‌گرداند. در صورت خطا، مقدار false برمی‌گردد.

ارسال اطلاعات ورود کاربر

اگر کاربر در سایت شما وارد شده یا توکن موقت دارد، می‌توانید یک environment شامل اطلاعات ورود بسازید. دقت کنید فقط مقدارهایی را منتقل کنید که از نظر امنیتی برای کاربر و API شما مناسب هستند.

_pm('env.create', 'API Credentials', {
  user_id: 'example-user',
  authorization: 'Bearer example-token'
});

ویرایش environment موجود

برای تغییر مقدارهای یک environment موجود، از env.assign استفاده کنید:

_pm('env.assign', 'environment_name', {
  key: 'new_value',
  new_key: 'value'
}, preventOverride, runButtonIndex);

این متد فقط روی environmentهایی کار می‌کند که همراه دکمه ساخته شده‌اند یا قبلا با env.create اضافه شده‌اند. اگر environment وجود نداشته باشد، env.assign environment جدید نمی‌سازد و شکست می‌خورد.

اگر preventOverride را فعال کنید، می‌توانید از بازنویسی ناخواسته مقدارهای کاربر جلوگیری کنید. خروجی این متد در حالت موفق true و در حالت ناموفق false است.

جایگزین کردن کامل environment

وقتی می‌خواهید تمام محتوای یک environment موجود را با داده جدید جایگزین کنید، از env.replace استفاده کنید:

_pm('env.replace', 'environment_name', { key: value }, runButtonIndex);

این متد environment جدید نمی‌سازد. اگر environment با آن نام وجود نداشته باشد، عملیات شکست می‌خورد.

حذف environment

برای حذف یک environment موجود از دکمه Run in Postman، از env.remove استفاده کنید:

_pm('env.remove', 'environment_name', runButtonIndex);

environment باید از قبل وجود داشته باشد. در غیر این صورت، متد مقدار false برمی‌گرداند.

چند دکمه در یک صفحه

اگر در یک صفحه چند دکمه Run in Postman دارید و می‌خواهید هر دکمه environment جداگانه داشته باشد، ویژگی segregateEnvironments را فعال کنید:

_pm('_property.set', 'segregateEnvironments', true);

بعد از فعال کردن این ویژگی، باید در متدهای _pm() از runButtonIndex استفاده کنید تا مشخص شود عملیات مربوط به کدام دکمه است. این index بر اساس جایگاه دکمه در DOM صفحه تعیین می‌شود.

var runButtons = Array.prototype.slice.call(
  document.getElementsByClassName('postman-run-button')
);
var runButtonIndex = runButtons.indexOf(elem);

دریافت فهرست environmentها

برای گرفتن همه environmentهای مرتبط با دکمه‌ها، از متد get() استفاده کنید:

_pm('_property.get', 'environments');

پاسخ، آرایه‌ای از environmentها و مقدارهای آن‌هاست. این خروجی برای عیب‌یابی صفحه یا بررسی اینکه کدام مقدارها به دکمه وصل شده‌اند مفید است.

قدم بعدی

بعد از ساخت و سفارشی‌سازی دکمه Run in Postman، بهتر است مستندات API خود را در workspace عمومی آماده کنید و دکمه را در همان جایی قرار دهید که کاربر برای شروع کار به آن مراجعه می‌کند؛ مثل صفحه مستندات، README یا راهنمای توسعه‌دهنده.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.