Bir projenizde kırk uç noktanız var ve her biri her çağrıda aynı Authorization: Bearer ... başlığına ve bir X-Api-Version başlığına ihtiyaç duyuyor. Bu iki satırı her isteğe elle eklemek yavaştır ve daha kötüsü, zamanla tutarsızlıklar yaratır. Bir uç nokta jetonu alır, diğeri unutulur ve kırk rotadan sadece üçünde görünen bir 401 hatasını kovalamakla bir öğleden sonranızı harcarsınız.
Daha iyi bir yolu var. Apidog, parametreleri bir kez tanımlamanıza ve bunların her isteğe otomatik olarak uygulanmasını sağlar. Başlığı proje düzeyinde ayarlayın, jetonunuzu bir değişken olarak referans alın ve her uç nokta, siz tek bir isteğe dokunmadan onu miras alır. Bu kılavuz, bunun için belgelenmiş üç anahtarı ele almaktadır: global parametreler, ortam değişkenleri ve klasör kapsamlı bir betik yedeklemesi. Başlangıçta her şeye bir yetkilendirme başlığı ve bir sürüm başlığı ekleyen, ayrıca başlığın gerçekten ağa gönderildiğini kanıtlamanın bir yolunu sunan çalışan bir kurulumla bitireceksiniz. Değişkenler hakkında daha derinlemesine bilgi edinmek isterseniz, Apidog'da değişkenlere hakim olma kılavuzumuz bununla iyi bir şekilde eşleşir.
Her çağrıda standart bir başlık taşıyan bir istek fikri Apidog'a özgü değildir. Bu, MDN HTTP başlıkları referansının açıkladığı aynı desendir: her istekle birlikte giden küçük bir anahtar/değer çiftleri kümesi. Apidog'un görevi, bu kümeyi bir kez ayarlamanıza olanak tanımaktır.
“Global parametreler” aslında ne anlama geliyor
Apidog'da global bir parametre, tek bir uç noktaya değil, tüm projeye uygulanan bir istek parametresidir. Onu bir kez tanımlarsınız ve Apidog onu eşleşen isteklere otomatik olarak ekler.
Global parametreler dört konumu kapsar ve bu, tüm özelliğin anahtarıdır:
AuthorizationveyaX-Api-Versiongibi şeyler için Başlıklar (İstek Başlığı).- Oturum çerezleri için Çerezler (Çerez Bilgileri).
- Her URL'ye eklenen
?api_key=gibi değerler için Sorgu (URL Sorgu Parametresi). - Her istek gövdesinin taşıması gereken bir alan için Gövde (İstek Gövdesi Parametresi).
Yetkilendirme başlığı kullanım durumu için Başlıklar'ı istersiniz. Standart değeriniz bir çerezde, bir sorgu dizesinde veya bir gövde alanında yaşıyorsa, diğer üçü de aynı şekilde çalışır.
Başlamadan önce önemli bir kural var: global parametreler, uç nokta düzeyinde tanımlanan parametrelerden daha düşük önceliğe sahiptir. Belirli bir istek kendi Authorization başlığını zaten ayarlamışsa, bu uç nokta düzeyindeki değer kazanır ve global olan bir kenara çekilir. Global bir parametreyi, bir uç noktanın kendisi için konuşmadığı durumlarda dolduran bir varsayılan olarak düşünün, her şeyi ezen zorlu bir geçersiz kılma olarak değil. Bu öncelik, büyük bir projede globallerin güvenle açılmasını sağlayan şeydir.
Her istekte global bir başlık ayarlama
İşte temel adım adım kılavuz. Amaç: projedeki her uç noktaya, hiçbirini düzenlemeden Authorization ve X-Api-Version eklemek.
Adım 1: Ortam Yönetimi'ni açın
Global parametreler, sayfanın sağ üstünden açtığınız Ortam Yönetimi'nde bulunur. Bu, proje genelinde uygulanan parametreler için giriş noktasıdır ve Apidog belgeleri, her istekle birlikte giden değerlerin evi olarak tanımlar. Açtığınızda, parametreleri konuma göre eklediğiniz bölümleri göreceksiniz.
Adım 2: Başlıklar konumunu seçin
Bir yetkilendirme başlığı eklediğiniz için Başlıklar'ı (İstek Başlığı konumu) seçin. Standart değeriniz bir çerez, bir sorgu parametresi veya bir gövde alanı olsaydı, bunun yerine Çerezler, Sorgu veya Gövde'yi seçerdiniz. Mekanizma dördü için de aynıdır.
Adım 3: Parametre ayrıntılarını doldurun
Her global parametrenin sabit bir özellik kümesi vardır. Bunları ilk başlığınız için doldurun:
- Ad:
Authorization - Tip: parametre tipi (bir başlık değeri için dize).
- Varsayılan Değer:
Bearer {{token}}(o{{token}}parçası hakkında daha fazla bilgi aşağıda). - Açıklama: "Tüm yetkilendirilmiş uç noktalar için Bearer jetonu" gibi kısa bir not.
Gerekli parametrelerde bir `Varsayılan` alanı ve gerekli işaretleyici (bir yıldız `*`) da görünür. Sürüm başlığı için aynı şekilde ikinci bir satır ekleyin:
- Ad:
X-Api-Version - Tip: dize
- Varsayılan Değer:
2024-08-01 - Açıklama: "Her istek için sabitlenmiş API sürümü."
Adım 4: Parametreyi açın
Her parametrenin sağ tarafında bir etkinleştirme/devre dışı bırakma anahtarı bulunur. Parametreyi etkinleştirmek için onu açın. Bu geçiş daha sonra kullanışlıdır: bir hata ayıklama oturumu için global bir başlığı susturmanız gerekirse, onu silmek ve her şeyi yeniden yazmak yerine buradan devre dışı bırakırsınız.
Adım 5: Kaydet
Yapılandırmayı kaydedin. Her iki başlık da artık globaldir. Projedeki her istek, belirli bir uç nokta bunlardan birini geçersiz kılmadığı sürece Authorization ve X-Api-Version taşıyacaktır.
Adım 6: Gerçekten gönderildiğini kanıtlayın
Çalıştığına güvenmeyin; kontrol edin. Projedeki herhangi bir isteği gönderin, ardından yanıt konsolunda Gerçek İstek sekmesini açın. Bu sekme, isteği tam olarak gönderildiği gibi, değişkenler zaten gerçek değerleriyle değiştirilmiş olarak gösterir. Her iki başlığı da orada görmelisiniz:
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Başlıklar Gerçek İstek'te görünüyorsa, ağa gönderilmişlerdir. Bu, tüm kurulumdaki en faydalı adımdır, çünkü "Uygulandığını düşünüyorum" ifadesini "Uygulandığını görebiliyorum" ifadesine dönüştürür.
Sırrı başlıktan uzak tutun: bir değişken kullanın
Yukarıdaki Varsayılan Değer'in `Bearer sk_live_7f3a9c2e1b8d4056` değil, `Bearer {{token}}` olduğuna dikkat edin. Bu çift ayraç sözdizimi, ham jetonu parametreye sabit kodlamak yerine bir değişkeni referans alır. `Bearer` şeması RFC 6750'de tanımlanmıştır ve MDN Yetkilendirme başlığı referansı sunucuların onu nasıl okuduğunu kapsar. Apidog'un belgeleri güvenlik açısı hakkında açıkça bilgi verir: yetkilendirme jetonları ve API anahtarları gibi hassas veriler için, ham değeri düz metin Varsayılan Değer olarak depolamak yerine ortam değişkenlerini kullanın. Bir değişken, birçok istek ve betikte kullandığınız bir değer için dinamik bir yer tutucudur ve sırrı parametre tanımından uzak tutar.
İşte `token` değişkenini nasıl kuracağınız:
- Sağ üstteki ortam simgesine (`≡` simgesi) tıklayın. Bunun Ortam Yönetimi'nden farklı bir giriş noktası olduğuna dikkat edin: `≡` simgesi değişkenlerin yaşadığı yerdir.
- Global Değişkenler bölümünü bulun.
- Örneğin, `token` adında, taşıyıcı sırrınızın değeriyle bir değişken oluşturun.
- Kaydet'e tıklayın.
Artık global başlık değeriniz `Bearer {{token}}` gönderme sırasında `Bearer` olarak çözümlenir ve Gerçek İstek sekmesi yerine koymayı doğrular. Herhangi bir yerdeki bir değişken adının üzerine gelmek, onun mevcut değerini ve kapsamını gösterir, bu da doğru olanı referans aldığınızı kontrol etmenin hızlı bir yoludur.
Bu eşleştirme önerilen desendir: global parametre başlık yuvasına sahiptir ve değişken sırra sahiptir. API istemci ortamı ve sır yönetimi üzerine derinlemesine incelememiz, jetonları paylaşabileceğiniz veya taahhüt edebileceğiniz herhangi bir şeyden nasıl uzak tutacağınız konusunda daha ileri gider.
Ortama göre değerleri değiştirme
Birden fazla değişkeniniz olduğunda değişkenler daha kullanışlı hale gelir. Gerçek projeler Geliştirme, Test ve Üretim için farklı sunuculara erişir ve her biri genellikle farklı bir jeton ister. Her bir kümeyi kendi ortamı altında gruplandırın, ardından `≡` simgesinin yanındaki Ortamlar açılır menüsü ile aralarında geçiş yapın (örnek bir ortam `Local Mock` olarak adlandırılabilir). Bir ortamı değiştirmek, isteklerinizi farklı bir sunucu kümesine yönlendirir ve o ortamın değişken değerlerini değiştirir. Global `Bearer {{token}}` başlığınız aynı kalır; yalnızca çözümlenmiş sır ortamla değişir. Bunun üzerine yetkilendirme akışları oluşturuyorsanız, güvenlik şemaları kılavuzumuzdaki kavramlar, taşıyıcı, API anahtarı ve OAuth tanımlarının gerçek isteklere nasıl eşlendiğini açıklar.
Başlığı sadece bir klasörde istediğinizde
Global parametreler tüm projeyi etkiler. Bazen bu çok geniş olabilir. Diyelim ki sadece `/admin` uç noktalarınızın bir `X-Admin-Scope` başlığına ihtiyacı var ve projenin geri kalanı bunu taşımamalı.
İşte dürüst sınırlama: Apidog'un klasör ayarlarında yerel bir "başlık ekle" alanı yoktur. Doldurulacak klasör düzeyinde bir başlık kullanıcı arayüzü yoktur. Bunun yerine belgelerde belgelenen şey, klasör düzeyinde bir ön istek betiği kullanarak bir çözümdür, böylece o klasördeki her istek başlığı miras alır. Betik, Postman uyumlu `pm.*` betiğini kullanır:
pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Bunu klasöre bir ön istek betiği olarak ekleyin ve klasördeki her istek başlığı alırken, klasör dışındaki istekler almaz. Bu bir betik, ayar geçişi değil, bu nedenle onu birincil yol yerine klasör kapsamlı ihtiyaçlar için kasıtlı bir yedek olarak ele alın. Bunun üzerine oturan daha geniş betik modeli için, Apidog'da ön istek ve sonrası istek betikleri kılavuzumuza bakın.
Hangi kaldıraç, ve ne zaman
Artık uç noktaları düzenlemeden bir başlık eklemenin üç yolu var. Kapsama göre seçin:
- Ortam Yönetimi aracılığıyla Global parametre (Başlıklar): başlık tüm projeye uygulanır. Bu, paylaşılan bir yetkilendirme başlığı veya sürüm başlığı için varsayılanınızdır.
- Ortam değişkeni (
{{token}}): bunu global parametreyle eşleştirin, böylece başlık yuvası global olur ancak sır güvenli bir şekilde depolanır ve ortama göre değişir. - Klasör düzeyinde ön istek betiği (
pm.request.headers.add): başlık sadece bir klasöre uygulanır. Proje geneli çok geniş olduğunda buna başvurun.
Dikkat edilmesi gereken birkaç şey var. İki global başlığın çakışmaması için yinelenen parametre adlarını kontrol edin ve her parametrenin Türünün kullanıldığı şekle uygun olduğundan emin olun. Ve öncelik kuralını unutmayın: kendi Authorization başlığını ayarlayan bir uç nokta, global olanı geçersiz kılar, bu bir rota farklı bir jeton gerektirdiğinde bir özelliktir, ancak o rotanın kendi değeri olduğunu unuttuğunuzda bir sürpriz olabilir. Bu üç özellikten hiçbiri belgelerde herhangi bir plan kısıtlaması taşımaz, bu nedenle bunları kullanmak için belirli bir katmana ihtiyacınız yoktur.
Apidog CLI ile iş akışını otomatikleştirin
Global parametreler ve ortamlar sadece bir GUI kolaylığı değildir; otomatik çalışmalara da taşınırlar. Apidog'da kaydedilmiş bir test senaryosu oluşturup komut satırından çalıştırdığınızda, çalışma kimlik ile geçirdiğiniz bir ortamı miras alır, böylece GUI'de çalışan aynı `Bearer {{token}}` başlığı ve `X-Api-Version` değeri CI'da da aynı şekilde çözümlenir.
CLI'yi (Node.js v16+) kurun ve kimlik doğrulayın:
npm install -g apidog-cli
apidog login --with-token <ERİŞİM_JETONUNUZ>
Ardından, belirli bir ortama karşı kaydedilmiş bir senaryoyu çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <senaryo_kimliği> -e <ortam_kimliği> -r cli
`-e` bayrağı ortamı seçer, böylece senaryo, jetonunuz da dahil olmak üzere o ortamın değişkenlerini alır. `-t` bayrağı test senaryosu kimliğidir ve `-r` raporlayıcıdır (`cli`, `html` veya `junit`). Bağlantı şudur: başlığı ve değişkeni bir kez tanımlayın ve CLI aracılığıyla her senaryo çalışması onları taşır. Kurulum ve jeton ayrıntıları için Apidog CLI kurulum kılavuzuna bakın ve çalıştırmaları otomasyona bağlamak için GitHub Actions'da Apidog CLI kılavuzumuz tam işlem hattını gösterir.
Sıkça Sorulan Sorular
Global parametreler, belirli bir uç noktada ayarladığım bir başlığı geçersiz kılar mı?
Hayır. Global parametreler, uç nokta düzeyindeki parametrelerden daha düşük önceliğe sahiptir. Bir istek kendi `Authorization` başlığını tanımlarsa, o değer kazanır ve global olan o istek için yok sayılır. Globaller, bir uç noktanın kendi değerini ayarlamadığı her yerde doldurularak proje varsayılanı olarak işlev görür.
Gerçek jetonu düz metin olarak görünmemesi için nerede saklamalıyım?
Ham bir Varsayılan Değer yerine bir ortam veya global değişken kullanın. Global başlığı `Bearer {{token}}` olarak ayarlayın ve gerçek sırrı `≡` ortam simgesi aracılığıyla oluşturulan bir değişkende saklayın. Belgeler, hassas veriler için özellikle jetonun satır içinde depolanmaması için değişkenleri veya güvenli yöntemleri önerir. JSONPath ile değişken çıkarma kılavuzumuz, bir giriş yanıtından bir jetonu yakalamayı ve aynı şekilde yeniden kullanmayı kapsar.
Global başlığın gerçekten gönderildiğini nasıl onaylarım?
Herhangi bir istek gönderin, ardından yanıt konsolunda Gerçek İstek sekmesini açın. İsteği gerçekten gönderildiği gibi, `{{token}}` ve diğer değişkenler zaten değerleriyle değiştirilmiş olarak gösterir. Başlığınız orada görünüyorsa, ağa gönderilmiştir.
Tüm proje yerine sadece bir klasöre varsayılan bir başlık ekleyebilir miyim?
Evet, ancak ayarlar alanı aracılığıyla değil, çünkü Apidog'un yerel bir klasör-başlık kullanıcı arayüzü yoktur. Klasöre `pm.request.headers.add({ key, value })` kullanarak bir ön istek betiği ekleyin ve o klasördeki her istek başlığı miras alırken, projenin geri kalanı almaz.
Global parametreleri veya ortam değişkenlerini kullanmak için ücretli bir plana ihtiyacım var mı?
Bu özelliklerin belgelerinde herhangi bir katman kısıtlaması listelenmemiştir. Global parametreler, ortam değişkenleri ve klasör düzeyindeki ön istek betikleri, ücretsiz ile ücretli arasında bir geçiş olmadan belgelenmiştir.
Sonuç
Her istekte bir başlık ayarlamak Apidog'da bir kerelik bir iştir: başlığı Ortam Yönetimi altında global bir parametre olarak tanımlayın, sırrı düz metinden uzak kalması için `{{token}}` değişkeni olarak referans alın ve Gerçek İstek sekmesiyle gönderildiğini onaylayın. Başlığı sadece bir klasörde ihtiyacınız olduğunda, ön istek betiği yedeklemesi bunu karşılar. Kendi projenizde takip etmek için, Apidog'u indirin ve ilk global başlığınızı kurun. Ücretsizdir, kredi kartı gerekmez.