Apidog'da Ortamlar ve Gizli Değişkenler Nasıl Yönetilir? (Dev, Staging, Prod)

Her API ekibi aynı duvara çarpar. Oluşturduğunuz ilk istekler, tek bir sunucuya, bir başlığa yapıştırılmış tek bir belirteçle işaret eder. Sonra hazırlık (staging) ortamı belirir. Sonra üretim (production) ortamı. Aniden, her çalıştırmadan önce URL'leri elle düzenlemeye başlarsınız ve biri eski bir temel URL yüzünden üretim ortamına karşı bir silme uç noktasını test eder. API ortam değişkenleri, bu tür hataların tamamını ortadan kaldırmak için vardır ve Apidog bunları ürüne sonradan eklemek yerine çekirdeğine dahil eder.

Bu kılavuz, Apidog'da geliştirme (dev), hazırlık (staging) ve üretim (prod) ortamlarını nasıl kuracağınızı, belirteçleri (token) ve API anahtarlarını sabit kodlanmış dizeler yerine değişkenler olarak nasıl saklayacağınızı, gerçek sırları yerel değerlerle buluttan uzak tutacağınızı ve Apidog CLI aracılığıyla ortamları CI'a nasıl aktaracağınızı gösterir. Bir ortam ve sır yönetimine sahip API istemcisinin neyi ele alması gerektiğine dair daha geniş bir resim istiyorsanız, bunu ayrı olarak ele aldık. Burada pratiğe geçiyoruz.

Sabit kodlanmış URL'ler ve belirteçler neden ikinci bir ortamla birlikte bozulur?

Tek bir ortamla, sabit kodlama iyi çalışır. https://api.acmepay.dev her istekte yer alır, belirteciniz her Yetkilendirme (Authorization) başlığında bulunur ve henüz hiçbir şey canınızı sıkmaz.

Acı, ikinci bir ortamın ortaya çıktığı an başlar:

• Her isteğin yeniden hedeflenmesi için düzenlenmesi gerekir. Geliştirme ortamını işaret eden elli uç nokta, hazırlık ortamını test etmek için elli URL düzenlemesi, sonra geri dönmek için elli tane daha demektir. Birini kaçırırsınız.
• Belirteçler sınırlar arasında sızar. Bir üretim API anahtarı bir istek gövdesine yapıştırıldığında projeyle birlikte kaydedilir, ekiple paylaşılır ve koleksiyonla birlikte dışa aktarılır. Twelve-Factor App metodolojisi bu konuda nettir: yapılandırma dağıtımlar arasında değişir, kod değişmez, bu nedenle yapılandırma asla paylaştığınız eserin bir parçası olmamalıdır.
• Çalıştırmalar tekrarlanabilir olmaktan çıkar. URL ve kimlik bilgileri her isteğin içinde bulunduğunda, “hazırlık ortamına karşı duman testlerini çalıştır” tek tıklamayla bir geçiş yerine manuel bir bul ve değiştir ritüeline dönüşür.

Çözüm eski ve kanıtlanmıştır: istek tanımını (metot, yol, gövde, iddialar) dağıtım bağlamından (temel URL, kimlik bilgileri, ortama özgü kimlikler) ayırın. İstekler her yerde aynı kalır. Sadece bağlam değişir.

Apidog ortamları ve değişkenleri nasıl modeller

Apidog sorunu birlikte çalışan iki parçaya ayırır.

Bir ortam, Dev, Staging veya Prod gibi adlandırılmış bir bağlamdır. Her ortamın kendi temel URL'si (isteklerin gönderildiği sunucu) ve kendi değişken değerleri seti vardır. Ortamı değiştirdiğinizde, projedeki her istek ortam yönetimi belgelerinde açıklandığı gibi anında yeniden hedeflenir.

Bir değişken, bir değerin bulunduğu herhangi bir yerde (URL'ler, sorgu parametreleri, başlıklar, istek gövdeleri ve betikler) {{variable_name}} olarak referans gösterdiğiniz adlandırılmış bir yer tutucudur. Çalışma zamanında, Apidog yer tutucuyu aktif ortama ve oyundaki diğer kapsamlara göre çözer.

Değişken kapsamları ve hangisinin kazandığı

Apidog değişkenleri beş kapsam aracılığıyla çözer. En düşükten en yükseğe öncelik sırasına göre: genel (global), modül (module), ortam (environment), veri (data) ve yerel (local).

Öncelik sırası pratikte önemlidir. {{auth_token}} öğesini genel bir geri dönüş olarak tanımlayın ve her yerde çalışır, ancak Staging ortamınız kendi {{auth_token}} öğesini tanımladığı anda, Staging aktifken ortam değeri kazanır. İstediğiniz tam olarak budur: altta paylaşılan varsayılanlar, üstte ortama özgü geçersiz kılmalar. Her kapsamın daha derinlemesine bir incelemesi için, Apidog'da değişkenlere hakim olma kılavuzumuza bakın.

İnsanları şaşırtan bir davranış: yerel değişkenler tasarım gereği geçicidir. Bir betikte ayarlayın ve çalıştırma tamamlandığında kaybolur. Bu, bir test senaryosundaki geçici değerler için bir özelliktir ve kalıcı olmasını bekliyorsanız zihinsel modelinizde bir hatadır. Yarın ihtiyacınız olan her şey bir ortam veya genel değişkende yer almalıdır.

Apidog'da geliştirme (dev), hazırlık (staging) ve üretim (prod) ortamlarını kurun

Üç dağıtıma sahip bir ödeme API'si için iş akışı aşağıdadır.

1. Üç ortamı oluşturun

Projenin sağ üst köşesinden ortam yönetimini açın ve her dağıtım için yeni bir ortam oluşturun. Her birine bir ad ve bir temel URL verin:

• Dev → https://api-dev.acmepay.dev
• Staging → https://api-staging.acmepay.dev
• Prod → https://api.acmepay.com

Temel URL'leri protokol ön ekli ve sonunda eğik çizgi olmadan tutun, böylece yollar temiz bir şekilde birleşir.

2. Her ortamda aynı değişken adlarını tanımlayın

Tutarlılık işin püf noktasıdır. Her ortam, farklı değerlerle aynı değişken adlarını tanımlar:

3. İsteklerde değişkenleri referans alın, asla ham değerleri değil

Bir ödeme oluşturma isteği şimdi her yerde şöyle görünür:

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

Temel URL hiç görünmez; Apidog aktif ortamın temel URL'sini otomatik olarak öne ekler. İstek tanımında hiçbir şey bir ortamı adlandırmaz, bu da onu taşınabilir kılar.

4. Seçici ile geçiş yapın

Ortam seçici Apidog penceresinin sağ üst köşesinde yer alır. Staging'i seçtiğinizde, projedeki her istek, test senaryosu ve betik, staging'in temel URL'sine ve staging'in değişken değerlerine göre çözümlenir. Düzenleme yok, bul ve değiştir yok. Hangi dağıtım katmanında neyin yer alması gerektiğini düşünüyorsanız, sandbox ve test ortamlarının karşılaştırmamız takımların bunları tipik olarak nasıl ayırdığını kapsar.

Postman'den mi geliyorsunuz? Mevcut ortamlarınız aktarılır. Postman geçiş kılavuzu, koleksiyonları ve ortamları değişken değerleri dahil birkaç tıklamayla nasıl içe aktaracağınızı anlatır.

Sırları yerel tutun: paylaşılan değerler ve yerel değerler

Bu, çoğu ekibin yanlış yaptığı ve Apidog'un tasarımının değerini gösterdiği kısımdır.

Apidog'daki her ortam ve genel değişken, değişkenler referansında belgelendiği gibi iki değer tutabilir:

• Paylaşılan değer: Apidog'un sunucularıyla senkronize edilir ve projede herkese görünürdür.
• Yerel değer: yalnızca makinenizdeki istemcinizin önbelleğinde depolanır. Asla bulutla senkronize olmaz ve ekip arkadaşları asla görmez.

Her ikisi de mevcut olduğunda, istemciniz yerel değeri kullanır. Bu nedenle sırlar için güvenli desen basittir:

1. Değişkeni, örneğin {{auth_token}} öğesini, her ortamda oluşturun.
2. Paylaşılan değeri boş bırakın veya SET_LOCALLY gibi bir yer tutucuya ayarlayın.
3. Gerçek belirteci kendi makinenizdeki yerel değere yerleştirin.

Değişken yapısı ekiple senkronize edilir. Sır senkronize olmaz. Her mühendis kendi kimlik bilgilerini bir kez girer ve her paylaşılan istek onlar için anında çalışır. Bu, OWASP Sır Yönetimi Hile Sayfası ile uyumludur: sırları sıkıca kapsamlandırın, kontrollü kanallar aracılığıyla paylaşın ve geniş çapta çoğaltılan her şeyden uzak tutun.

Bilmeye değer iki uyarı. Yerel değerler istemci önbelleğinde yaşar, bu nedenle Apidog'un önbelleğini temizlemek onları siler ve yeni bir dizüstü bilgisayara geçmek, onları yeniden girmek anlamına gelir. Bunun için beş dakika ayırın, bir üretim anahtarı on iki kişiye senkronize olduğu için beş saatlik olay incelemesi değil.

Ayrıca tüm bir ortamı paylaşılan yerine özel olarak işaretleyebilirsiniz. Yalnızca dağıtım yapan iki kişiye görünen bir Prod ortamı meşru bir kurulumdur ve derinlemesine savunma için yerel değerlerle birleşir.

Test senaryolarında ve CI'da ortamları kullanın

Ortamlar doğrudan Apidog'un test senaryolarına aktarılır. Bir senaryoyu bir kez oluşturun (ödeme oluştur, durumu sorgula, ödemeyi doğrula), ardından yürütme zamanında hangi ortamda çalıştırılacağını seçin. Aynı senaryo, geliştirme ortamınızın duman testi ve hazırlık ortamınızın regresyon paketi olur.

Betikler aynı kapsamları okur ve yazar. Bir giriş yanıtından yeni bir belirteç yakalayan bir son işlemci şöyle görünür:

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

Senaryodaki sonraki istekler {{auth_token}} öğesini yakalanan değere çözer. İstek parametrelerini betiklere çekme gibi desenler için, istek öncesi/sonrası betiklerinde istek parametrelerini alma konusuna bakın.

CI için, Apidog CLI ortamı bir bayrak olarak alır:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

-e, ortamı ID'ye göre seçer. CLI'ın makinenizin yerel değerlerini değil, paylaşılan değerleri çözdüğünü unutmayın; bu doğru davranıştır: kişisel sırlarınıza bir derleme aracısından zaten erişilememelidir. Bunun yerine gerçek kimlik bilgilerini çalışma zamanında, key=value biçimindeki --env-var ve --global-var geçersiz kılmalarıyla veya tüm bir dosyayı yüklemek için --variables ile enjekte edin. Gerçek sırları CI sağlayıcınızın sır deposunda (GitHub Actions sırları, GitLab CI değişkenleri) saklayın ve bunları geçirin. Pipeline asla düz metin bir belirteç içermez ve bir kimlik bilgisini döndürmek, bir CI sırrını güncellemek anlamına gelir.

Bundan doğan ekip iş akışı

Bir araya getirildiğinde, iş bölümü nettir:

• Paylaşılan, senkronize edilmiş: ortam adları, temel URL'ler, değişken adları, yer tutucu paylaşılan değerler, test senaryoları.
• Kişisel, yerel: her mühendisin belirteçleri ve anahtarları yerel değerler olarak.
• CI'a ait: CI sır deposundaki pipeline kimlik bilgileri, CLI bayrakları aracılığıyla enjekte edilir.

Yeni bir ekip arkadaşı katılır, projeyi açar ve her değişkenin adlandırılmış ve belgelenmiş olduğu üç hazır ortam görür. Kendi geliştirme belirteçlerini bir yerel değer alanına yapıştırır ve çalışmaya başlar. Kimse bir üretim anahtarını DM'den göndermez. Kimse güncel olmayan bir “mevcut hazırlık ortamı URL'si” wiki sayfası tutmaz.

Kaçınılması gereken yaygın tuzaklar

• Gerçek belirteçleri paylaşılan değerlere işlemek. Açık ara en yaygın hata. Bir sırrın ekip arkadaşlarına ulaşması gerekiyorsa, senkronize bir değişken aracılığıyla değil, bir parola yöneticisi veya kasası aracılığıyla gitmelidir. Paylaşılan değerlerinizi bir kez denetleyin; canlı bir kimlik bilgisine benzeyen her şey yerel değerlere taşınmalı ve döndürülmelidir.
• Hangi ortamın aktif olduğunu unutmak. Kas hafızası, gözler seçiciyi kontrol etmeden önce istekleri gönderir. Yıkıcı işlemleri yanlışlıkla yapmayı zorlaştırın: Prod ortamını daha az kişiye özel tutun ve yalnızca üretim ortamına özgü değişkenlere farklı adlar veya yer tutucu paylaşılan değerler verin, böylece yanlış ortamda yapılan bir çalıştırma sessizce başarılı olmak yerine kimlik doğrulamada yüksek sesle başarısız olur.
• Geçici değişkenlerin kalıcı olmasını beklemek. Bir çalıştırma sırasında ayarlanan yerel kapsamlı değişkenler, çalıştırma bittiğinde kaybolur. Kalıcı olan her şeyi betiğinizde açıkça ortam kapsamına yükseltin.
• Ortamlar arasında farklı değişken adları. Geliştirme ortamı onu {{token}}, hazırlık ortamı ise {{auth_token}} olarak adlandırıyorsa, ortamları değiştirmek isteklerinizin yarısını bozar. Her yerde aynı adlar, yalnızca farklı değerler olmalıdır.
• Her şey için tek bir devasa ortam. Eğer dev_base_url ve prod_base_url'i tek bir ortama tıkıyorsanız, sabit kodlama sorununu ek adımlarla yeniden inşa etmişsiniz demektir. Dağıtım bağlamı başına bir ortam olmalıdır.

Bunu kurmaya hazır mısınız? Ücretsiz olarak Apidog'u indirin, üç ortamınızı oluşturun ve ilk belirtecinizi yerel bir değere taşıyın. Mevcut bir proje için yaklaşık on dakika sürer.

Sıkça Sorulan Sorular

Sırları paylaşılan Apidog projelerinden nasıl uzak tutarım?

Onları yerel değerler olarak depolayın. Her değişkenin paylaşılan bir değeri (ekiple senkronize edilir) ve yerel bir değeri (yalnızca makinenizde önbelleğe alınır) vardır. Paylaşılan değeri bir yer tutucu olarak bırakın ve gerçek belirteci yerel tutun. Ekstra izolasyon için, Prod gibi hassas ortamları özel olarak işaretleyin, böylece yalnızca belirli kişiler onları görebilir.Genel ve ortam değişkenleri arasındaki fark nedir?

Genel değişkenler, hangi ortamın aktif olduğuna bakılmaksızın tüm projede geçerlidir; bunları bir API sürüm dizesi gibi dağıtımlar arasında asla değişmeyen değerler için kullanın. Ortam değişkenleri tek bir ortama aittir ve her ikisi de aynı adı tanımladığında genel değişkenlere karşı kazanır. Değişkenler kılavuzumuz, modül, veri ve yerel dahil olmak üzere beş kapsamı da ayrıntılı olarak açıklar.Testim neden Apidog istemcisinde başarılı oluyor da CI'da başarısız oluyor?

Genellikle istemci yerel değerleri çözerken, CLI paylaşılan değerleri çözdüğü içindir. Belirteciniz yalnızca yerel bir değerde bulunuyorsa, CLI boş veya yer tutucu bir değişken görür. Kimlik bilgisini açıkça pipeline'da --env-var "auth_token=$YOUR_CI_SECRET" ile geçirin, böylece CI çalışma zamanında kendi sırrını sağlar.Postman ortamlarımı Apidog'a taşıyabilir miyim?

Evet. Apidog, Postman koleksiyonlarını ve ortamlarını doğrudan içe aktarır, değişken adlarını ve değerlerini sağlam tutar, böylece {{base_url}} referanslarınız geçişten sonra da çalışmaya devam eder. İçe aktarılan değerleri daha sonra gözden geçirin ve gerçek kimlik bilgilerini yerel değerlere taşıyın, çünkü Postman dışa aktarımları sırları düz metin olarak taşıyabilir.