`apidog run` komutunu ilk çalıştırdığınızda ve "No access token found" (Erişim belirteci bulunamadı) hatasıyla durduğunda, komut satırı iş akışının kimsenin sizi uyarmadığı kısmına çarpmış olursunuz. Bayraklar, senaryo kimlikleri, raporlayıcılar bir sekmeden kolayca kopyalanabilir. Kimlik doğrulama, kopyalanan bir komutun makinenizde bozulduğu, bir sırrı bir loga sızdırdığı veya dizüstü bilgisayarınızda sessizce çalışıp CI'da hata mesajının açıklamadığı nedenlerle başarısız olduğu adımdır.
Bu kılavuz, bu adıma özel bir yanıttır. Apidog CLI, Apidog uygulamasında oluşturduğunuz API test senaryolarını doğrudan bir terminalden çalıştıran bir npm paketi olan `apidog-cli`'dir. Bu senaryolar hesabınızda yaşadığı için, CLI'nın bunları getirme ve çalıştırma izni olduğunu kanıtlaması gerekir ve bunu bir erişim belirteciyle yapar. Belirteç yönetimini bir kez doğru yapın, sonraki her çalıştırma temiz tek satırlık bir komut olur. Yanlış yaparsanız, aynı kimlik doğrulama hatasıyla üç farklı ortamda mücadele edersiniz.
Tüm yüzeyi ele alacağız: erişim belirteci oluşturma, `apidog login` ile oturum açma, `apidog whoami` ile kim olarak oturum açtığınızı kontrol etme, belirtecin nerede saklandığı, `apidog run`'ın hangi belirteci kullanacağına nasıl karar verdiği ve çoğu ekibin yanlış yaptığı kısım olan, belirteci bir pipeline dosyasına yapıştırmak yerine CI'da bir sır olarak ele alma. Kurulum mekaniği ayrı bir kılavuzda yer almaktadır; bu kılavuz yalnızca kimlik doğrulama ile ilgilidir. CLI'yı henüz yüklemediyseniz, Apidog CLI kurulum kılavuzu ile başlayın, ardından buraya geri dönün.
CLI neden bir belirtece ihtiyaç duyar?
CLI kendi başına test taşımaz. Apidog projenize erişir, ID'ye göre bir senaryo bulur ve masaüstü uygulamasının yaptığı gibi çalıştırır. Bu tasarımın kimlik doğrulamasına ihtiyaç duymasının nedeni budur: senaryo, ortam değerleri, onaylamalar hepsi hesabınızda sunucu tarafında bulunur, bu nedenle çalıştırıcının sunucu herhangi birini teslim etmeden önce kendini tanıtması gerekir.
Bir erişim belirteci, kendini bu şekilde tanımlar. Belirteç Apidog hesabınıza bağlıdır, bu nedenle belirtecinizle kimliği doğrulanmış bir çalıştırma, sizin yapabildiğiniz her şeyi yapabilir: projelerinizi okuyabilir, senaryolarınızı alabilir, tanımladığınız ortamlara karşı yürütebilir. Bu aynı zamanda belirtecin korumanız gereken bir kimlik bilgisi olmasının nedenidir. Belirteci elinde bulunduran herkes, bu senaryoların hedeflediği ortamlara karşı sizin adınıza senaryo çalıştırabilir. Diğer herhangi bir hizmet için kişisel bir erişim belirtecini nasıl kullanıyorsanız, ona da öyle davranın.
Bu, testlerinizin gerçekleştirdiği kimlik doğrulamadan farklı bir kimlik doğrulama türüdür. Senaryolarınız muhtemelen test edilen uç noktalara kendi taşıyıcı belirteçlerini veya API anahtarlarını gönderir ve bu, API kimlik doğrulama yöntemlerinde ele alınan ayrı bir konudur. CLI'ın erişim belirteci, çalıştırıcıyı Apidog'a doğrular. İsteklerinizin içindeki kimlik bilgileri, isteklerinizi API'nize doğrular. İkisini birbirinden ayırın, çünkü farklı yerlerde bulunurlar ve farklı zaman çizelgelerinde dönerler.
Adım 1: erişim belirteci oluşturun
Belirteci CLI'dan değil, Apidog'da oluşturursunuz. İki yerde karşınıza çıkar ve hangisini kullanacağınız ne yaptığınıza bağlıdır.
Senaryolar arasında yeniden kullanacağınız, hesabınıza özel bir belirteç için, Apidog uygulamasını veya web konsolunu açın, avatarınıza tıklayın ve hesap ayarlarınızın altındaki API erişim belirteci bölümüne bakın.
Bir tane oluşturun, hemen kopyalayın ve bir parola yöneticisi gibi güvenli bir yere kaydedin. Sayfadan ayrıldıktan sonra genellikle tam dizeyi tekrar göremezsiniz, bu kimlik bilgileri için normaldir ve görünür görünmez kopyalamanızın nedenidir.
CI'a bağladığınız belirli bir senaryoya bağlı bir belirteç için daha hızlı bir yol vardır. Test senaryosunu açın, CI/CD sekmesine geçin, komut satırı seçeneğini seçin ve erişim belirteci oluşturmak için tıklayın. Apidog, belirteç, senaryo ID'si ve ortam ID'si zaten doldurulmuş olarak tüm `apidog run` komutunu sizin için oluşturur. Oluşturulan bu komut, standart başlangıç noktasıdır ve onu kopyalamak, bir ID'yi asla elle yazmayacağınız anlamına gelir. Apidog CLI kapsamlı kılavuzu, bu CI/CD sekmesini ayrıntılı olarak ele alır.
Her iki durumda da, çıktı aynıdır: bir belirteç dizesi. Bununla sonra ne yapacağınız, iki kimlik doğrulama stili arasındaki seçimdir.
Adım 2: kimlik doğrulama stilinizi seçin
CLI, belirteci sunmanın iki yolunu destekler ve bunlar farklı durumlara uygundur.
İlki, depolanmış bir oturum açmadır. `apidog login` komutunu bir kez çalıştırırsınız, CLI belirteci makinenize kaydeder ve sonraki her `apidog run` komutu onu otomatik olarak okur. Bundan sonra hiçbir komut satırında belirteç olmaz. Bu, her gün kullandığınız bir geliştirme makinesinde istediğiniz şeydir.
İkincisi, komut başına çalışmadır. `--access-token` parametresini `apidog run` çağrısının kendisine, genellikle bir ortam değişkeninden geçirirsiniz. Hiçbir şey depolanmaz, belirteç her seferinde taze olarak sağlanır ve diskte iz bırakmaz. Bu, çalıştırıcının geçici olduğu ve belirtecin bir sırdan geldiği CI'da istediğiniz şeydir.
Muhtemelen her ikisini de kullanacaksınız, yerel olarak depolanmış oturum açma ve pipeline'da komut başına. Sonraki iki bölüm her birini ele almaktadır.
Adım 3: apidog login ile yerel olarak oturum açın
Kendi makinenizde, bir kez oturum açın ve belirteci unutun. Etkileşimli form sizden onu ister, böylece dize kabuk geçmişinizde asla görünmez:
apidog login
CLI sizden erişim belirtecinizi ister, siz yapıştırırsınız ve Enter'a basarsınız. Arka planda, herhangi bir şeyi kaydetmeden önce belirteci Apidog'a karşı doğrular; geçersiz veya süresi dolmuş bir belirteç, ilk çalıştırmanızda daha sonra başarısız olmak yerine anında reddedilir. Başarılı olduğunda, hangi hesapla oturum açtığını onaylar ve kimlik bilgisini nereye kaydettiğini size bildirir.
Belirteci doğrudan, örneğin bir kurulum betiği içinde geçirmeyi tercih ederseniz, `--with-token` bayrağını kullanın:
apidog login --with-token YOUR_ACCESS_TOKEN
Bu formla ilgili bir uyarı: komut satırındaki bir belirteç, kabuk geçmişinize düşer ve komut çalışırken işlem listesinden okunabilir. Etkileşimli kullanım için interaktif `apidog login`'i tercih edin ve `--with-token`'ı, değeri kontrol ettiğiniz bir değişkenden okuduğunuz etkileşimsiz kurulumlar için saklayın. Gerçek bir belirteci asla taahhüt ettiğiniz bir betiğe koymayın.
Belirteç nereye gider? CLI onu ev dizininizdeki `.apidog` dizini altında bir yapılandırma dosyasına yazar. Bu, kendi makinenizdeki yerel bir kimlik bilgisi deposudur ve asıl nokta da budur: belirteç, yalnızca kullanıcı hesabınızın okuyabileceği bir yerde diskte durur ve CLI, onu her sonraki çalıştırmada sizin yeniden yazmanıza gerek kalmadan alır. Paylaşımlı veya tek kullanımlık bir makinedeyseniz, depolanmış oturum açmayı atlayın ve bunun yerine komut başına belirteci kullanın, böylece ayrıldıktan sonra hiçbir şey kalıcı olmaz.
Adım 4: apidog whoami ile doğrulayın
Oturum açtıktan sonra, ona güvenmeden önce çalıştığını doğrulayın:
apidog whoami
Bu, CLI'nın şu anda kim olarak kimliği doğrulandığını yazdırır. Gerçek bir senaryo çalıştırmadan "oturum açtım mı ve kim olarak?" sorusuna yanıt vermenin en hızlı yoludur. Bir çalıştırma kimlik doğrulama hatasıyla başarısız olduğunda ve sorunun belirteç mi yoksa başka bir şey mi olduğundan emin olmadığınızda bunu kullanın; eğer `whoami` hesabınızı gösteriyorsa, depolanmış oturum açma doğrudur ve başka bir yere bakabilirsiniz.
`apidog whoami`, depolanmış olan yerine belirli bir belirteci kontrol etmek isterseniz `--access-token` parametresini de kabul eder. Bu, bir CI belirtecinin bir pipeline'da güvenmeden önce geçerli olduğunu doğrulamak için kullanışlıdır: belirteci güvenli bir terminalden tek seferlik `apidog whoami --access-token YOUR_ACCESS_TOKEN` komutuna yapıştırın, hangi hesaba çözüldüğünü görün, ardından gizli depolama alanınıza taşıyın.
Paylaşımlı bir makinede işiniz bittiğinde veya farklı bir hesaba geçmek istediğinizde, depolanmış kimlik bilgisini temizleyin:
apidog logout
Bu, kaydedilen belirteci yapılandırma dosyasından kaldırır. Bir sonraki `apidog run`, yeni bir oturum açma veya `--access-token` bayrağı gerektirecektir, ki bu bir makineyi geri verdikten sonra istediğiniz davranıştır.
Adım 5: apidog run bir belirteci nasıl seçer
Çalıştırıcının kontrol sırasını anladığınızda, "No access token found" hatası gizemli olmaktan çıkar. `apidog run` komutunu çağırdığınızda, CLI bir belirteci şu sırayla arar:
- Komutta geçirilen `--access-token` bayrağı, eğer mevcutsa.
- Önceki bir `apidog login` işleminden diskte depolanan belirteç.
İkisini de bulamazsa durur ve önce `login` çalıştırmanızı veya `--access-token` geçirmenizi söyler. Bu öncelik kullanışlıdır: bir bayrak her zaman depolanmış oturum açmaya göre önceliklidir, bu nedenle her gün kendi adınıza oturum açmış olsanız bile, oturumunuzu kapatmadan tek seferlik bir çalıştırma için farklı bir belirteçle geçersiz kılabilirsiniz.
Pratikte bu, yerel çalıştırmalarınızın ID'ler kadar kısa olabileceği anlamına gelir:
apidog run -t 605067 -e 1629989 -n 1 -r cli
Bu satırda belirteç yok, çünkü depolanmış oturum açma onu sağlar. `-t` senaryoyu ID'sine göre adlandırır, `-e` ortamı seçer, `-n 1` bir kez çalıştırır ve `-r cli` okunabilir bir rapor yazdırır. Bunu, hiçbir şey depolanmadığı için belirteci açıkça geçirdiğiniz CI formuna kıyaslayın:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Aynı komut, aynı senaryo, farklı kimlik doğrulama kaynağı. Yerel ve CI kimlik doğrulaması arasındaki tüm fark budur ve bu kılavuzun geri kalanı CI kısmını doğru yapmaktır. Bu çalıştırmaların arkasındaki tam bayrak referansı için, kapsamlı Apidog CLI kılavuzu her seçeneği kapsar.
Adım 6: belirteci CI'da bir sır olarak ele alın
Ekiplerin yandığı yer burasıdır. Çözüm tek bir kuraldır: belirteç CI sisteminizin sır deposunda yaşar ve bir ortam değişkeni olarak komuta ulaşır. Taahhüt edilmiş bir dosyada, repoya işlenmiş bir pipeline tanımında veya bir derleme logunda asla görünmez.
CI içinde oturum açmayın ve belirteci çalıştırıcının oluşturduğu bir dosyaya yazmayın. Maskelenmiş bir sırdan beslenen, komut başına `--access-token` formunu kullanın. Aşağıdaki her örnek aynı şekli takip eder: sır platformda bir kez adlandırılır, çalıştırma adımında `$APIDOG_ACCESS_TOKEN` olarak referans verilir.
GitHub Actions
Belirteci deponun Ayarlarında, Sırlar ve değişkenler altında saklayın, ardından `env` aracılığıyla adıma maruz bırakın:
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
GitHub, sırrı loglarda otomatik olarak maskeler ve `env` aracılığıyla geçirmek, onu görünür komut satırından uzak tutar. Buradaki en yaygın hata bir ad uyuşmazlığıdır: `env` anahtarı, `${{ secrets.X }}` referansı ve Ayarlar'da oluşturduğunuz sırrın hepsi aynı adı kullanmalıdır. Rapor yapıtları dahil olmak üzere tüm iş akışı, GitHub Actions'da Apidog CLI'da yer almaktadır.
GitLab CI
`APIDOG_ACCESS_TOKEN`'ı Ayarlar altında maskelenmiş, korumalı bir CI/CD değişkeni olarak saklayın, asla `.gitlab-ci.yml` dosyasına koymayın. Ardından doğrudan referans verin, çünkü GitLab proje değişkenlerini iş ortamına enjekte eder:
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Değişkeni “masked” olarak işaretlemek GitLab'a onu iş loglarından çıkarmasını söyler; “protected” olarak işaretlemek, korumasız dallardan uzak tutar, böylece bir çatal veya özellik dalı onu sızdıramaz.
Jenkins
Belirteci bir Jenkins kimlik bilgisi olarak saklayın, ardından `environment` bloğunda bağlayın, böylece asla yazdırılmadan bir değişken olarak kullanılabilir:
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
}
}
}
}
Jenkins bu şekilde bağlanmış kimlik bilgilerini konsol çıktısında maskeler. Bu adım etrafında tam pipeline'ı oluşturursanız, Bir CI/CD pipeline'ında Apidog CLI çevresindeki yapıyı kapsar.
Desen her çalıştırıcıda aynıdır: platformda maskelenmiş bir sır, komutta bir ortam değişkeni ve `--access-token` bayrağı ondan okuma yapar. Bu, bir pipeline'daki herhangi bir kimlik bilgisine uygulayacağınız disiplinle aynıdır ve birden fazlasını yönetiyorsanız API anahtarı yönetimi en iyi uygulamalarını okumaya değer.
Belirteçleri döndürme ve iptal etme
Belirteçler sonsuz değildir. Onları belirli bir programda döndürün ve sızmış olabileceği anda iptal edin.
Döndürmek için, Apidog'da yeni bir belirteç oluşturun, onu kullanan her CI sistemindeki sırrı güncelleyin ve yenisinin çalıştığını doğrulamak için bir pipeline çalıştırın. Ardından eski belirteci oluşturduğunuz yerden iptal edin. Yerel olarak, `apidog logout` ardından yeni belirteçle `apidog login` çalıştırın. Sıra önemlidir: iptal etmeden önce CI'ı güncelleyin, aksi takdirde iki adım arasında bir derleme başarısız olacaktır.
Bir belirteç olmaması gereken bir yerde (bir logda, bir ekran görüntüsünde, bir commit'te, paylaşımlı bir terminalde) ortaya çıkarsa hemen iptal edin. İptal etmek, belirteci her yerde aynı anda geçersiz kılar, bu nedenle eski değeri hala kullanan herhangi bir pipeline yüksek sesle başarısız olacaktır, ki istediğiniz sinyal budur. Başarısız bir derleme kurtarılabilir; herkese açık bir logdaki canlı bir kimlik bilgisi kurtarılamaz. Daha geniş alışkanlık için, API anahtarı döndürme en iyi uygulamaları temposu hakkında bilgi verir.
İnce bir tuzak: Apidog'da bir belirteci yeniden oluşturmak, öncekini geçersiz kılar. Eğer yeniden oluşturur ve bir CI sırrını güncellemeyi unutursanız, YAML'da hiçbir şey değişmemiş olsa bile o pipeline bir kimlik doğrulama hatasıyla başarısız olmaya başlar. Daha önce geçen bir derleme aniden kimlik doğrulayamaz duruma geldiğinde ve iş akışı dosyasına dokunmadığınızda, yeniden oluşturulmuş bir belirteç kontrol edilecek ilk şeydir.
Kimlik doğrulama başarısız olduğunda
Kimlik doğrulama hataları birkaç nedenden kaynaklanır. İşte bunları nasıl ayırt edeceğiniz.
"No access token found." (Erişim belirteci bulunamadı.) CLI, `--access-token` bayrağını veya depolanmış bir oturum açmayı bulamadı. Yerel olarak, `apidog login` çalıştırın. CI'da, sırrın doldurulduğundan ve `--access-token` bayrağının ondan okuduğundan emin olun; boş bir ortam değişkeni de aynı mesajı üretir.
"Invalid access token" (Geçersiz erişim belirteci) veya çalıştırma ortasında bir kimlik doğrulama hatası. Belirteç yanlış, süresi dolmuş veya iptal edilmiş. Depolanmış belirteci kontrol etmek için `apidog whoami` çalıştırın veya belirli bir belirteci kontrol etmek için `apidog whoami --access-token YOUR_TOKEN` kullanın. İkisi de hesabınıza çözülmezse, yeni bir belirteç oluşturun ve tekrar oturum açın.
Yerelde çalışıyor, CI'da başarısız oluyor. Klasik uyumsuzluk. Makinenizde depolanmış bir oturum açma var, bu nedenle yerel çalıştırmalar başarılı oluyor; CI çalıştırıcısında hiçbir şey depolanmamış ve tamamen sırra bağlı. Sır adının platform ayarı ile komut arasında tam olarak eşleştiğinden ve değerin bir boşluk veya yeni satır olmadan kaydedildiğinden emin olun, bu yapıştırırken kolayca oluşabilecek bir durumdur.
Belirli bir senaryoda "Access denied" (Erişim reddedildi). Belirteç geçerli ancak arkasındaki hesap o projeye erişemiyor. Proje ve senaryo ID'lerini kontrol edin ve belirtecin hesabının o projeye erişimi olduğunu doğrulayın. Bu bir yetkilendirme sorunudur, kimlik doğrulama değil; CLI kim olduğunu kanıtladı, sunucu o hesabın o senaryoyu çalıştırmasına izin vermiyor.
Belirteç komuta ulaşıyor ancak derleme hala onu sızdırıyor. Ham belirteci bir logda görürseniz, onu bir yere yansıtıyorsunuz demektir, genellikle tüm komutu veya ortamı yazdıran bir hata ayıklama satırıdır. Maskeleyin: doldurulduğunu doğrulamak için belirtecin uzunluğunu yazdırın, asla değerini. Çoğu CI platformu bilinen sırları otomatik olarak düzenler, ancak tüm komutun elle yazılmış bir `echo`'su bunu bozabilir.
Kimlik doğrulamanın daha büyük iş akışına nerede uyduğu
Kimlik doğrulama, sonraki her şeyi mümkün kılan küçük, tek seferlik bir kapıdır. CLI kim olduğunu kanıtlayabildiğinde, bir Apidog senaryosu çalıştırmak tek bir komut haline gelir; yerel olarak düzenleme-test döngünüzde, her push'ta CI'da ve hatta testlerinizi sizin için çalıştıran bir AI kodlama aracısının içinde bile. Aracılarla çalışıyorsanız son desene bir göz atmakta fayda var: API testleri için AI aracıları nasıl kullanılır, oturum açmış bir CLI'nın bir aracının senaryolarınızı çalıştırmasına ve sonucu okumasına nasıl izin verdiğini gösterir ve Apidog MCP sunucusu, spesifikasyonlarınızı doğrudan bu aracılara bağlar.
Zihinsel model basittir. Makinenizde `apidog login` ile bir kez oturum açın, `apidog whoami` ile doğrulayın ve depolanmış belirtecin sonraki her çalıştırmayı taşımasına izin verin. CI'da, oturum açmayı atlayın, belirteci maskelenmiş bir sırda tutun ve `--access-token` ile komut başına geçirin. Belirli bir programa göre döndürün, şüphe durumunda iptal edin ve iptal etmeden önce CI'ı güncelleyin. Tüm kimlik doğrulama hikayesi budur ve bu halledildiğinde CLI, iyi bir test çalıştırıcısının ait olduğu arka plana kaybolur.
Senaryoları Apidog'da görsel olarak yazmaya devam edin ve CLI onları hiçbir insanın izlemediği her yerde çalıştırır. İlk senaryonuzu kurmak için Apidog'u indirin, ardından çalıştırıcıyı ona yönlendirin. Çalıştırıcının kimliği doğrulandıktan sonra yapabileceği her şey için, kapsamlı Apidog CLI kılavuzu açık tutulması gereken referanstır.