Çok adımlı API izleme

Çok adımlı API monitörü, bir API'nin gerçek kullanım akışını sırayla çalıştırır: örneğin giriş yap → token al → token ile kayıt oluştur → kaydı sil. Her adım bir HTTP isteğidir; bir adımın yanıtından değer çıkarıp sonraki adımlarda kullanabilir, her adımda durum kodu, JSON, başlık ve yanıt süresi doğrulayabilirsiniz. Parola ve anahtar gibi sırlar Gizli değişkenler kasasında saklanır ve adımlarda adıyla kullanılır.

Bu tür ücretli paketlerde bulunur; paketinize göre monitör başına en fazla 5 veya 10 adım tanımlayabilirsiniz. En kısa kontrol aralığı 1 dakikadır.

Adımlar

Panelde Monitörler → Yeni monitör → Çok adımlı API seçin. Her adımın üç sekmesi vardır:

Adımlar yukarı/aşağı okla sıralanır, çoğaltılır veya silinir. Adımlar sırayla çalışır; bir adım başarısız olursa akış durur ve monitör kesinti sayılır. Hata metni hangi adımda neyin beklendiğini söyler: “3. adım (Sipariş durumu) başarısız: beklenen 200, gelen 500”.

Ortak ayarlar: adım zaman aşımı (her istek için, 1–30 sn), toplam süre sınırı (tüm akış, en fazla 60 sn; kontrol aralığından kısa olmalı), isteğe bağlı yavaşlık eşiği (toplam süre bunu aşarsa “performans sorunu”) ve IP sürümü.

Değişkenler ve şablonlar

Adım alanlarında {{ad}} biçiminde şablon kullanabilirsiniz. Alanın yanındaki Değişken düğmesi kullanılabilir değişkenleri listeler ve imlecin olduğu yere ekler.

Bir değişken yalnızca onu çıkaran adımdan sonraki adımlarda kullanılabilir; tanımsız değişken kayıtta reddedilir.

Değer çıkarma

• JSON yolu: $.access_token, $.data.items[0].id. Metin değerler olduğu gibi, sayı/nesne/dizi JSON metni olarak alınır.
• Yanıt başlığı: örn. Location; isteğe bağlı başlangıç/bitiş işaretleriyle bir kısmı (Location başlığında /orders/ sonrası gibi).
• Gövde (işaretler arası): başlangıç işaretinden sonra, ardından gelen ilk bitiş işaretinden önceki metin. Düzenli ifade (regex) desteklenmez.

Değer bulunamazsa, null ise veya 4 KB'den büyükse adım başarısız olur. Çıkarılan değerler varsayılan olarak gizlidir: sonuç tablosunda ve hata kanıtında maskelenir ([gizli]). Sipariş numarası gibi sır olmayan değerler için Görünür kutusunu işaretleyin.

Değerler nasıl eklenir (kaçış)

• URL: şablon yalnızca yol ve sorgu dizesinde kullanılabilir; şema ve host her adımda sabittir (https://{{x}}.ornek.com gibi adresler reddedilir). Değer URL kodlanarak eklenir: /, ?, &, # gibi karakterler adresi değiştiremez.
• JSON gövde: şablon yalnızca tırnak içindeki metin değerlerde kullanılabilir ("id": "{{siparis_id}}"); değer JSON kaçışıyla eklenir. Sayı alanına değişken koymak için API'niz metin kabul etmelidir.
• Form gövde: satır başına anahtar=değer; değerler eklendikten sonra kodlanır, bu yüzden değişkendeki & veya = yeni alan oluşturmaz.
• Başlıklar ve kimlik bilgisi: olduğu gibi eklenir; satır sonu içeren bir değer başlığa konamaz (adım “şablon hatası” ile başarısız olur).

Gizli değişkenler

Ayarlar → Gizli değişkenler sayfasında API parolası, istemci sırrı veya anahtar gibi değerleri saklayın ve adımlarda {{secret.AD}} olarak kullanın.

• Değerler şifreli saklanır ve yalnızca yazılır: panel, API, dışa aktarımlar, denetim kaydı ve bildirimler değeri hiçbir zaman göstermez. Değeri değiştirmek için yenisini yazın; boş bırakırsanız kayıtlı değer korunur.
• Değer yalnızca kontrolü çalıştıran ajana, o kontrol için iletilir; sonuçlarda ve hata kanıtında (JSON, URL ve base64 kodlanmış biçimleri dahil) maskelenir.
• Ad büyük harf, rakam ve _ içerir (API_PAROLA) ve sonradan değiştirilemez. Kullanımdaki değişken silinemez.
• İzinli hostlar (isteğe bağlı): değişkenin gönderilebileceği hostlar (api.ornek.com.tr, *.ornek.com.tr). Boşsa değişken yalnızca doğrulanmış hedeflerinize giden adımlarda kullanılabilir. Özel lokasyon monitörlerinde izinli host tanımlamak zorunludur.
• Yönetim için monitör yönetimi yetkisi ve parola onayı gerekir; her değişiklik denetim kaydına (değer olmadan) yazılır.

Güvenliğiniz için adım tanımına sır yazılamaz: Basic parolası ve Bearer token alanları, Authorization, Cookie, X-Api-Key gibi kimlik bilgisi başlıkları, gövdedeki ve sorgu dizesindeki password, client_secret, access_token, api_key gibi alanlar bir gizli değişken veya çıkarılmış değişken içermelidir. Düz metin (raw) gövde taranmaz; sırları burada da {{secret.AD}} ile kullanın.

Hedef doğrulaması ve güvenlik

• Genel lokasyonlarda her adımın hostu organizasyonunuzun doğrulanmış hedefi olmalıdır. Doğrulaması kaldırılan bir host kullanılıyorsa monitör duraklatılır.
• İç ağdaki API'ler için özel lokasyon kullanın; burada hedef doğrulaması gerekmez, gizli değişkenler için izinli host gerekir.
• Yönlendirmeler HTTP monitörüyle aynı kurallara tabidir: https → http yönlendirmesi reddedilir, başka bir kaynağa yönlendirmede kimlik bilgisi taşıyan başlıklar (Authorization, Cookie, özel başlıklar) silinir, GET/HEAD dışındaki yöntemlerde başka hosta yönlendirme izlenmez.
• Yanıt gövdesi en fazla 1 MiB okunur; istek gövdesi (değişkenler eklendikten sonra) en fazla 16 KiB olabilir.

Başarısız olsa da devam et (temizlik adımları)

Bir adımda Başarısız olsa da devam et işaretliyse o adım başarısız olduğunda akış durmaz; sonraki adımlar (örneğin oluşturulan kaydı silen DELETE adımı) yine çalışır. Kontrol yine başarısız sayılır ve hata metni ilk başarısız adımı gösterir. Başarısız adımın çıkaracağı değişkene ihtiyaç duyan adımlar atlanır.

Örnek akış:

1. Giriş — POST https://api.ornek.com.tr/login, JSON gövde {"kullanici": "izleme", "parola": "{{secret.API_PAROLA}}"}, değişken token ← $.access_token
2. Kayıt oluştur — POST https://api.ornek.com.tr/siparisler, Bearer {{token}}, beklenen 201, değişken siparis_id ← $.id (görünür)
3. Kaydı doğrula — GET https://api.ornek.com.tr/siparisler/{{siparis_id}}, JSON $.durum eşittir olusturuldu, başarısız olsa da devam et
4. Temizlik — DELETE https://api.ornek.com.tr/siparisler/{{siparis_id}}, Bearer {{token}}, beklenen 204

Şimdi çalıştır ve sonuçlar

Kaydedilmiş bir monitörün düzenleme sayfasındaki Şimdi çalıştır düğmesi akışı hemen bir ajanda çalıştırır ve adım adım sonucu gösterir (kaydedilmemiş değişiklikler kullanılmaz; önce kaydedin). Monitör sayfasında Adım akışı kartı son çalıştırmanın adım tablosunu (sonuç, durum kodu, süre, çıkarılan değişkenler) gösterir. Başarısız kontrollerde Kanıtı göster, başarısız adımların (en fazla 3) yanıt başlıklarını, gövde önizlemesini ve zamanlamasını adım sekmeleriyle gösterir; sırlar maskelenir.

REST API ve Terraform

API'de tür http_steps, ayarlar http_steps nesnesindedir:

{
  "name": "Sipariş API akışı", "type": "http_steps", "interval_seconds": 300, "timeout_ms": 10000,
  "http_steps": {
    "total_timeout_ms": 30000,
    "steps": [
      {"name": "Giriş", "method": "POST", "url": "https://api.ornek.com.tr/login", "body_type": "json",
       "body": "{\"kullanici\":\"izleme\",\"parola\":\"{{secret.API_PAROLA}}\"}",
       "extract": [{"var": "token", "source": "json", "path": "$.access_token"}]},
      {"name": "Profil", "url": "https://api.ornek.com.tr/me", "auth_type": "bearer", "auth_token": "{{token}}",
       "assertions": [{"path": "$.aktif", "op": "equals", "value": "true"}]}
    ]
  }
}

Adım tanımı sır içermediği için GET /api/v1/monitors/{id} yanıtındaki definition.http_steps olduğu gibi döner ve aynen gönderilebilir. Terraform sağlayıcısında aynı nesne config içinde verilir; gizli değişkenler panelden yönetilir.

Ajan sürümü

Çok adımlı API kontrolleri ajan 1.6.0 ve üzeri tarafından çalıştırılır. Özel lokasyonunuzdaki ajan daha eskiyse bu monitörler “veri yok” durumunda kalır; ajanı güncelleyin.