Bazı isteklerin makinenizden ayrılmadan önce işlenmesi gerekirken, bazıları da bir yanıt geldiği anda işlenmelidir. Bir ödeme API'si, bir zaman damgası ve sırrınızdan hesaplanan bir HMAC imzası ister. Bir giriş uç noktası, daha sonraki her çağrı için gerekli olan bir belirteç (token) döndürür. Bir ödeme akışı, yanıtın gerçekten bir 200 döndürdüğünü ve doğru sipariş kimliğini doğrulamalıdır. Tüm bunları elle yapabilirsiniz, ancak bu hızla sıkıcı hale gelir ve isteği bir ekip arkadaşınızla paylaştığınız anda bozulur.
Betikler bunu düzeltir. Apidog'da, otomatik olarak çalışan küçük JavaScript parçalarını bir isteğe eklersiniz: biri istek gönderilmeden önce, diğeri yanıt döndükten sonra çalışır. Daha önce Postman betikleri yazdıysanız, Apidog'un motoru aynı pm nesne API'si ile uyumlu olduğundan kas hafızanız devam edecektir. Bu kılavuz, gerçekçi bir örnekle her iki aşamayı da ele almaktadır: bir ön istek betiğinde bir isteği imzalama, ardından bir yanıt sonrası betiğinde bir belirteci (token) çıkarma. Davranışın tamamı Apidog betikleme belgelerinde açıklanmıştır, ancak sekme adları ve birkaç davranış Postman'dan farklıdır ve bu farklılıklar önemlidir.
düğme
Ön ve Son Betikler Gerçekte Ne Yapar?
Apidog betikleri iki aşamada çalıştırır ve bunları açıkça adlandırır.
Ön İşleyiciler (Pre Processors) istek sunucuya gönderilmeden önce çalışır. Burası, şeyleri hazırladığınız yerdir: bir zaman damgası oluşturmak, bir imza hesaplamak, rastgele bir sipariş Kimliği ayarlamak veya bir değişkeni okuyup bir başlığa dönüştürmek. Bu noktada yanıt henüz mevcut değildir, bu nedenle bir yanıtı inceleyen her şey burada kullanılamaz.
Son İşleyiciler (Post Processors) yanıt alındıktan sonra çalışır. Burası, gelen verileri doğrulamalarla kontrol ettiğiniz ve daha sonra yeniden kullanmak üzere gövdeden değerleri çektiğiniz yerdir. Bir kimlik doğrulama belirteci çıkarın, yeni oluşturulan bir kaynak Kimliğini alın, durum kodunu kontrol edin, sayfalama için bir imleç kaydedin.
Bu ayrımdan iki kural çıkar. İlk olarak, pm.response (kodu, durumu, başlıkları, yanıt süresi, yanıt boyutu, text() ve json() ile birlikte) yalnızca Son İşleyicilerde çalışır. Göndermeden önce okunacak bir yanıt yoktur, bu nedenle bir Ön İşleyicide çağırmak size yardımcı olmayacaktır. İkinci olarak, iki aşamanın birbirleriyle konuşmasının yolu değişkenlerdir. Bir Ön İşleyici bir değer ayarlar, istek bunu kullanır ve bir Son İşleyici bunu okuyabilir veya üzerine yazabilir.
Postman'dan geliyorsanız, etiket değişikliğine dikkat edin. Apidog'un sekmeleri "Pre-request Script" ve "Tests" yerine Ön İşleyiciler (Pre Processors) ve Son İşleyiciler (Post Processors)'dır. Davranışlar yakından eşleşse de, ekrandaki isimler farklıdır.
Kurulum: bir istek açın ve sekmeleri bulun
Takip etmek için Apidog'u indirin. Ücretsizdir ve macOS, Windows ve Linux'ta çalışır, bu yüzden henüz sahip değilseniz Apidog İndirme sayfasından edinin.
Betiklemek istediğiniz API isteğini Apidog içinde açın. Her uç nokta, alışılagelmiş Params, Headers ve Body sekmelerinin yanı sıra bir Ön İşleyiciler (Pre Processors) sekmesi ve bir Son İşleyiciler (Post Processors) sekmesine sahiptir. Herhangi bir aşamaya mantık eklemek için sekmeyi açın ve Özel Bir Betik Ekle (add a Custom Script) seçeneğini seçin. Bu, pm nesnesine karşı düz JavaScript yazdığınız bir kod düzenleyiciyi açar.
Herhangi bir şey yazmadan önce, değerlerin nerede yaşadığını bilmek faydalıdır. Apidog, değişkenleri bu öncelik sırasına göre çözer:
Yerel Değişkenler > Ortam Değişkenleri > Proje İçinde Paylaşılan Genel Değişkenler > Ekip İçinde Paylaşılan Genel Değişkenler.
Bu nedenle, aynı ada sahip bir yerel değişken, bir ortam değişkeninden önceliklidir ve liste bu şekilde devam eder. Bir değer beklediğiniz gibi olmadığında bunu aklınızda bulundurun: sıradaki daha yüksek bir şey muhtemelen onu gölgeliyordur. Birçok istek arasında kalıcı olacak değerler istiyorsanız, Apidog'daki genel parametreler öncelik sırasında daha alt sıralarda yer alır ve istikrarlı, proje çapında ayarlar için iyi bir yer sağlar.
Ön İşleyici örneği: bir isteği HMAC ile imzalama
Her isteği bir HMAC-SHA256 imzasıyla kimlik doğrulayan bir ödeme uç noktasını çağırdığınızı varsayalım. Bu, birçok sağlayıcının webhook doğrulama için kullandığı aynı kalıptır ve Stripe'ın imza belgeleri bunu iyi açıklar: sunucu, bir zaman damgası ve bu zaman damgası ile istek gövdesi üzerinden hesaplanan, API sırrınızla anahtarlanmış bir imza bekler. Her gönderimde her ikisini de yeni baştan oluşturmanız gerekir.
Apidog, crypto-js'i yerleşik bir kütüphane olarak sunar, bu nedenle hiçbir şey kurmanıza gerek yoktur. Ön İşleyiciler (Pre Processors) sekmesini açın, Özel Bir Betik Ekle (add a Custom Script) seçeneğini seçin ve şunu yazın:
// Ön İşleyici: istek gönderilmeden önce isteği imzala
const CryptoJS = require('crypto-js');
// saniye cinsinden mevcut unix zaman damgası
const timestamp = Math.floor(Date.now() / 1000).toString();
// sırrı bir ortam değişkeninden oku
const secret = pm.environment.get('payments_api_secret');
// imzalanacak dizeyi oluştur: zaman damgası + yeni satır + ham gövde
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;
// HMAC-SHA256 imzasını hesapla, hex olarak kodlanmış
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
// her iki değeri de isteğin kullanması için ortam değişkenleri olarak sakla
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);
pm.console.log('Signed request at ' + timestamp);
Bu betik imzayı hesaplar ve hem zaman damgasını hem de imzayı ortam değişkenlerine kaydeder. Şimdi bunları isteğe bağlayın. **Başlıklar (Headers)** sekmesinde, depolanan değerlere {{değişkenAdı}} sözdizimiyle referans verin:
X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Gönderdiğinizde, Apidog önce Ön İşleyiciyi çalıştırır, iki değişkeni ayarlar, ardından bunları başlıkların yerine koyar. Sunucuya, her zaman gönderim anında geçerli olan bir imza ulaşır, hiçbir manuel adım gerektirmez. require('crypto-js') çağrısının tüm modülü çektiğine dikkat edin. Tüm kütüphaneyi içe aktarırsınız, bir alt modülü değil, bu nedenle require('crypto-js') çalışır ancak require('crypto-js/sha256') çalışmaz.
Dikkat edilmesi gereken bir şey: değişken işlemleri yalnızca geçerli değerlere dokunur, ortam düzenleyicisine yazmış olabileceğiniz başlangıç değerlerine değil. İmza geçici olması gerektiğinden, burada istediğiniz de budur. Postman tarafı için de imzalama kalıplarının açıklanmasına ihtiyacınız varsa, Postman ön istek betikleri hakkındaki kılavuz, Postman'ın etiketleriyle aynı fikri ele alır ve Apidog'un Ön İşleyicilerine sorunsuz bir şekilde eşlenir.
Son İşleyici örneği: bir belirteç (token) çıkarın ve doğrulayın
Şimdi diğer aşama. Daha sonraki her kimliği doğrulanmış çağrı için ihtiyacınız olan bir belirteç (token) döndüren bir giriş isteğini hayal edin:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": 4812, "email": "dana@example.com" },
"expires_in": 3600
}
Son İşleyiciler (Post Processors) sekmesini açın, **Özel Bir Betik Ekle (add a Custom Script)** seçeneğini seçin ve belirteci (token) gövdeden çekerek daha sonraki istekler için kaydedin:
// Son İşleyici: yanıtı doğrula, ardından belirteci (token) çıkar
pm.test('Status is 200', function () {
pm.response.to.have.status(200);
});
const jsonData = pm.response.json();
pm.test('Response returns a token', function () {
pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});
pm.test('User id is present', function () {
pm.expect(jsonData.user.id).to.be.a('number');
});
// diğer isteklerin gönderebilmesi için belirteci (token) sakla
pm.environment.set('auth_token', jsonData.token);
pm.console.log('Saved token for user ' + jsonData.user.email);
Burada iki şey olur. pm.test() blokları, Apidog'un doğal olarak desteklediği Chai tarzı pm.expect() eşleştiricilerini kullanarak yanıtın beklediğiniz gibi şekillendiğini doğrular. Ve pm.environment.set('auth_token', jsonData.token) belirteci (token) ortama kaydeder. Artık sonraki herhangi bir istek, hiçbir şeyi elle kopyalamanıza gerek kalmadan Authorization: Bearer {{auth_token}} gönderebilir.
Bunun doğrulama kısmı kendi başına dikkat çekmeyi hak ediyor. İyi yanıt sonrası kontroller, manuel tıklama ve gözle incelemeyi gerçek bir teste dönüştüren şeydir ve Apidog'daki API doğrulamaları kılavuzumuz, bilinmesi gereken eşleştiriciler ve kalıplar hakkında daha derinlemesine bilgi verir. Bu akışlara gerçekçi sahte veriler de beslemek isterseniz, Apidog'da Faker.js yukarıda gösterilen değişken ayarlama ile iyi bir şekilde eşleşir.
Son İşleyicilerde akılda tutulması gereken birkaç davranış. pm.iterationData (test verileriniz) salt okunurdur, bu nedenle veri odaklı bir değeri okuyabilirsiniz ancak bir betikten ona geri yazamazsınız. Ve pm.cookies, isteğinizle giden çerezi değil, sunucunun geri gönderdiği yanıttan gelen çerezi döndürür.
Mantığı Genel Betikler ile Yeniden Kullanma
Bu HMAC imzalama bloğunu yazdıktan sonra, muhtemelen birden fazla istekte kullanmak isteyeceksiniz. On farklı uç noktaya kopyala-yapıştır yapmak, algoritma değiştiğinde düzeltilmesi gereken on yer anlamına gelir. Apidog'un yanıtı ise Genel Betikler (Public Scripts)'dir: bir kez yazdığınız ve ihtiyaç duyulan yere eklediğiniz yeniden kullanılabilir kod parçaları.
Ayarlar (Settings) > Genel Betikler (Public Scripts) altında bir tane oluşturun, ardından bir isteğin **Ön İşleyiciler (Pre Processors)** veya **Son İşleyiciler (Post Processors)** sekmesine ekleyin. Bir işlemci listesinin içinde, bir Genel Betik ve bir Özel Betik yan yana bulunur ve sıra önemlidir: genel betikler aynı listedeki özel betiklerden önce çalışır ve birden fazla genel betiğiniz varsa, bunlar listedeki sıraya göre yukarıdan aşağıya doğru çalışır.
İnsanların takıldığı bir püf noktası var. Bir Özel Betiğin, bir Genel Betikte tanımlanmış bir işlevi çağırmasını istiyorsanız, o işlevin global olması gerekir. Normal bir function bildirimi veya const ile bağlanmış bir işlev, kendi betiğine özeldir ve bir sonraki betik tarafından görünmez. Bunu var, let veya const kullanmadan atama yaparak bildirin:
// Genel Betikte: anahtar kelimeyi atlayarak sign() işlevini global yap
sign = function (payload, secret) {
const CryptoJS = require('crypto-js');
return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
// Altındaki Özel Betikte: global işlevi adıyla çağır
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));
Önce Genel Betiği ekleyin, Özel Betiği altına koyun, böylece çağrı çözümlenir. Sırayı yanlış yaparsanız veya bir const eklerseniz, tanımlanmamış işlev hatası alırsınız.
Kütüphaneler, harici paketler ve hata ayıklama
Yukarıdaki crypto-js içe aktarımı, Apidog'un hiçbir kurulum gerektirmeden birlikte sunduğu kütüphanelerden biridir. Bunlardan herhangi birini doğrudan require() edebilirsiniz:
crypto-js(v3.1.9-1) karma ve HMAC içinjsrsasign(v10.3.0) JWT ve RSA çalışmaları için, Apidog 1.4.5 veya sonrası gerektirirchai(v4.2.0) doğrulama eşleştiricileri içinlodash,moment,uuid,xml2js,cheerio,postman-collection,atob,btoa,csv-parse/lib/sync,tv4,ajv- Node'un yerleşik bileşenleri:
path,assert,buffer,util,url,querystring,streamveeventsgibi
Bu listede olmayan bir şeye ihtiyacınız varsa, paketi anında getiren `$$.liveRequire()` ile çalışma zamanında dahil edin:
$$.liveRequire('nanoid', (nanoid) => {
const id = nanoid.nanoid();
pm.environment.set('request_id', id);
});
Bu yol bir internet bağlantısı gerektirir, çünkü Apidog betik çalıştığında paketi indirir. Yerleşik kütüphaneler için bu gerekmez.
Bir betik hatalı davrandığında, konsola yazarak çözümleyin. Hem pm.console.log() hem de sade console.log() Apidog'un konsoluna çıktı verir, böylece hesaplanmış bir imzayı veya çıkarılmış bir alanı dökebilir ve isteğin gönderilmesinden önce veya döndükten sonra betiğin tam olarak ne ürettiğini görebilirsiniz.
Sizi şaşırtmaması için adlandırılmaya değer iki sınırlama daha. Bir betik içinde fazladan bir HTTP çağrısı tetiklemek için pm.sendRequest(), Promise'lar yerine bir geri çağırma (callback) deseni kullanır, bu nedenle onu await ile değil, bir geri çağırma ile yazın. Ve Postman'ın istekleri zincirlemek için kullandığı pm.nextRequest() burada desteklenmez. Dallanma ve koşullu adımlarla gerçek iş akışı düzenlemesine ihtiyacınız olduğunda, Apidog bunun yerine, istekleri görsel olarak Koşul ve Eğer-Değilse adımlarıyla sıraladığınız Test Senaryolarını kullanır. Çok fazla betik yazıyorsanız, yerleşik Apidog Betik Oluşturucu, size bir başlangıç noktası sağlamak için doğal dil açıklamasından bir taslak da oluşturabilir.
İş akışını Apidog CLI ile otomatikleştirme
Betikler sadece Gönder'e tıkladığınızda çalışmaz. İsteklerinizi ve doğrulamalarınızı kaydedilmiş bir Test Senaryosu halinde paketlediğinizde, Apidog CLI bu senaryonun tamamını başsız (headless) olarak çalıştırır, buna Ön İşleyiciler ve Son İşleyiciler de dahildir; bu da imzalama ve belirteç (token) çıkarma mantığınızı manuel bir adım yerine CI'ın bir parçası haline getirir.
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
-t bayrağı test senaryo kimliğidir, -e ortam kimliğidir ve -r raporlayıcıyı seçer (cli, html veya junit, birden fazla için virgülle ayrılır). Apidog hesap ayarlarınızda erişim belirtecini oluşturun, onu APIDOG_ACCESS_TOKEN olarak dışa aktarın ve masaüstünüzde çalışan aynı senaryo şimdi CI'da çalışır, Ön İşleyiciler ve Son İşleyiciler dahil.
Dürüst bir uyarı: yalnızca makinenizde bulunan bir şeye (yerel bir dosya veya bir kez yüklediğiniz bir paket) dayanan bir betik, masaüstü uygulamasında geçebilir ancak CLI'da başarısız olabilir, çünkü çalıştırıcıda bu bağımlılık yoktur. Betikleri yerleşik kütüphanelerle veya `$$.liveRequire()` ile sınırlı tutun ki her yerde aynı şekilde çalışsınlar.
Sıkça Sorulan Sorular (SSS)
Apidog betikleri mevcut Postman betiklerimle uyumlu mu?
Çoğunlukla evet. Apidog'un motoru aynı pm nesne API'sini kullanır, bu nedenle pm.environment.set(), pm.response.json(), pm.test() ve pm.expect() bildiğiniz gibi davranır. Unutulması gereken iki fark, sekme adlarıdır (Pre-request Script ve Tests yerine Ön İşleyiciler ve Son İşleyiciler) ve pm.nextRequest() gibi birkaç desteklenmeyen çağrıdır. Çoğu betik yapıştırılıp çalıştırılabilir.
Ön istek betiğimde neden pm.response tanımsız (undefined) döndürüyor?
Çünkü henüz bir yanıt yok. Ön İşleyiciler istek gönderilmeden önce çalışır, bu nedenle incelenecek bir şey geri dönmemiştir. pm.response'u (durumu, gövdesi, başlıkları) okuyan herhangi bir kod bir Son İşleyiciye aittir. Ön aşamada bir değere ihtiyacınız varsa, onu pm.request'ten, bir değişkenden veya bir kütüphaneden alın.
Bir betiği birden çok istek arasında nasıl paylaşırım?
Ayarlar (Settings) > Genel Betikler (Public Scripts) altındaki Genel Betikleri kullanın. Mantığı bir kez yazın, her isteğin Ön İşleyiciler veya Son İşleyiciler sekmesine ekleyin ve genel betiklerin aynı listedeki özel betiklerden önce çalıştığını unutmayın. Bir Özel Betikten bir Genel Betik işlevini çağırmak için, onu var, let veya const kullanmadan atama yaparak global olarak bildirin.
Apidog'un birlikte sunmadığı bir npm paketini içe aktarabilir miyim?
Evet, paketi çalışma zamanında indiren ve internet bağlantısı gerektiren `$$.liveRequire('paket-adı', (pkg) => { ... })` ile. `crypto-js`, `moment` veya `uuid` gibi yerleşik listedeki her şey için, ağa ihtiyaç duymadan sade bir `require()` kullanın. Yalnızca tüm modülü içe aktarabileceğinizi, bir alt modül yolunu değil, unutmayın.
Betiğimin ne yazdırdığını nerede görebilirim?
pm.console.log() veya console.log() kullanın ve isteği gönderdikten sonra Apidog'un konsolundaki çıktıyı okuyun. Bir imzanın hesaplandığını veya bir belirtecin (token) çıkarıldığını bir senaryoda güvenmeden önce doğrulamanın en hızlı yoludur.
Özetleme
Ön İşleyiciler ve Son İşleyiciler, statik bir isteği kendini hazırlayan ve kendi işini kontrol eden bir isteğe dönüştürür. Göndermeden önce imzalayın, aldıktan sonra çıkarın ve doğrulayın ve ortak mantığı Genel Betiklere taşıyın, böylece onu bir kez yazmış olursunuz. pm API'si ve yerleşik kütüphaneler, Postman'dan bildiğiniz çoğu şeyin doğrudan aktarılabileceği anlamına gelir. Apidog'u açın, herhangi bir istek seçin ve her iki aşamanın tek bir gönderimde çalışmasını izlemek için ilk Özel Betiğinizi ekleyin. Başlamak ücretsizdir, kredi kartı gerekmez.