Bir dosya alan bir uç nokta oluşturdunuz. Bir kullanıcı profil resmini POST /avatars adresine yüklüyor veya uygulamanız imzalı bir PDF'i POST /documents adresine gönderiyor. Rota kafanızda çalışıyor. Şimdi bunun HTTP üzerinden çalıştığını kanıtlamanız gerekiyor: gerçek bir dosya seçin, bir form alanına ekleyin, isteği gönderin ve yanıtı kontrol edin.
API araçlarının çoğu burada zorlanır. Dosya yüklemeleri JSON değil, multipart/form-data kullanır, bu yüzden bir gövde yapıştırıp gönder tuşuna basamazsınız. Dosya alanlarını anlayan bir istek oluşturucuya ve test daha sonra çalıştırıldığında dosyayı bulabilen bir test çalıştırıcısına ihtiyacınız var. Apidog her ikisini de halleder ve bu kılavuz tüm yolu anlatır: tek bir yükleme gönderme, JSON ile birlikte bir dosya gönderme, yanıtı doğrulama ve ardından kimsenin size uyarmadığı dürüst kısım, yani aynı yükleme adımının Runner veya CLI'da başsız çalıştığında dosyayı bulamamasının ne anlama geldiği. Biçimin arka planını önce öğrenmek isterseniz, API'lerde dosya yükleme başlangıç kılavuzu çok parçalı isteklerin nasıl yapılandırıldığını kapsar. FormData hakkındaki MDN referansı tarayıcı tarafı için iyi bir eşlikçidir.
multipart/form-data nedir ve yüklemeler neden buna ihtiyaç duyar?
Bir API istek gövdesi çeşitli şekillerde olabilir. Apidog'un istek Gövde bölümünde form-data, x-www-form-urlencoded, JSON, XML, raw veya binary seçebilirsiniz. Çoğu zaman JSON'ı tercih edersiniz. Dosya yüklemeleri bir istisnadır.
form-data gövde türü, Content-Type: multipart/form-data başlığına eşlenir. Diğer verilerle birlikte dosya yüklemek için oluşturulmuş bir formattır. Tek bir yığın yerine, gövde her biri kendi adına ve kendi içeriğine sahip parçalara ayrılır. Bir parça bir başlık gibi düz bir dize olabilir, başka bir parça bir görüntünün ham baytları olabilir. Bu nedenle bir fotoğraf yüklemesi ve meta verileri aynı istekte birlikte yolculuk edebilir.
Yakın akrabası x-www-form-urlencoded'dir. Düzenleyicide benzer görünür, gövdede gönderilen anahtar-değer çiftleri, ancak dosyasız basit formlar için tasarlanmıştır. Uç noktanız bir dosya alıyorsa, istediğiniz form-data'dır. x-www-form-urlencoded'i yalnızca her alan kısa bir skaler ise ve hiçbir bayt içermiyorsa kullanın.
form-data'da Apidog her parametreyi bir anahtar-değer çifti olarak gösterir ve her parametre bir tür taşır: dize, tamsayı, dosya vb. Bu parametre başına tür, tüm işin sırrıdır. Bir alanı file olarak ayarlayın ve Apidog değerini gönderilecek bir metin yerine eklenecek bir dosya olarak işler.
Tek bir dosya yüklemesi gönderin ve yanıtı doğrulayın
Diyelim ki POST /avatars'ı test ediyorsunuz. Bir resim içeren avatar adında tek bir alan alır ve depolanan URL ile bir JSON döndürür. İşte adım adım kılavuz.
1. Gövde bölümünü açın ve form-data'yı seçin. Uç noktanızda veya yeni bir istekte, yöntemi POST olarak ve URL'yi avatarlar rotanıza ayarlayın. Gövde sekmesini açın ve form-data gövde türünü seçin. Apidog sizin için Content-Type: multipart/form-data ayarlar.
2. Dosya parametresini ekleyin ve türünü dosya olarak ayarlayın. avatar anahtarına sahip bir parametre ekleyin. Anahtarın yanında, tür seçiciyi kullanarak türünü string'den file'a değiştirin. Değer hücresi bir metin kutusu yerine bir dosya seçiciye dönüşür.
3. Yükle'ye tıklayın ve yerel bir dosya seçin. avatar satırındaki Yükle'ye tıklayın ve makinenizden bir resim seçin, örneğin jane-profile.png. Apidog o dosyanın yolunu kaydeder.
4. İsteği gönderin. Gönder'e tıklayın. Apidog, dosyayı depolanan yerel yoldan okur, çok parçalı gövdeyi oluşturur ve gönderir. Şimdiden bilmekte fayda var: Apidog dosyayı istekte gönderir ancak dosyayı bulutta saklamaz. Sadece yerel yolu kaydeder, baytları değil. Bu ayrıntı daha sonra önemlidir, bu yüzden aklınızda tutun.
Başarılı bir çağrı şöyle bir şeyle geri gelir:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Yanıtı doğrulayın. 200 dönen bir gönderim tek başına başarılı bir test değildir. Kontrolün gerçek olması için doğrulayıcılar ekleyin. Apidog'da bunları uç nokta veya senaryo adımında istek sonrası doğrulayıcılar olarak eklersiniz. Açıkça söylemek gerekirse, durumu ve gövdenin kullanılabilir bir URL taşıdığını doğrulamak istersiniz:
durum kodu == 200
$.avatarUrl mevcut
$.contentType == "image/png"
Bunlar doğrudan Apidog'un doğrulayıcı arayüzüne eşlenir: durum kodu üzerinde bir doğrulayıcı, JSONPath $.avatarUrl'in varlığı üzerinde bir doğrulayıcı, $.contentType üzerinde bir doğrulayıcı. Doğrulayıcılarda yeniyseniz, API doğrulayıcıları kılavuzu operatörlerin tam setini ve JSONPath'in bir alanı nasıl hedeflediğini gösterir.
Araç dışındaki hızlı bir gerçeklik kontrolü için, curl'daki aynı yükleme şöyle görünür:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
-F bayrağı, curl'ün çok parçalı bir parça oluşturma şeklidir ve @ ise dosya içeriklerini okumasını söyler. Apidog'un form-data dosya parametresi, bir bayrak yerine bir seçici ile aynı şeyi yapar.
Bir dosya ve JSON'ı birlikte gönderin
Gerçek uç noktalar nadiren çıplak bir dosya alır. POST /documents dosyanın yanı sıra meta veri de isteyebilir: bir başlık, bir kategori, belki bir etiket dizisi. Bunu tek bir çok parçalı istekte yapmanın iki temiz yolu vardır.
Basit durum skaler alanlardır. Dosya alanınızın yanına daha fazla form-data parametresi ekleyin ve bunları string veya integer olarak bırakın. Bir title dizesi, bir category dizesi, türü file olarak ayarlanmış bir file. Üçü de aynı istekte taşınır.
Meta veri, iç içe bir nesne veya bir dizi gibi yapılandırılmışsa, bunu bir dize parçası içinde JSON olarak gönderirsiniz. metadata adında bir form-data parametresi ekleyin, türünü string olarak tutun ve JSON'ı doğrudan değere yapıştırın:
{
"title": "Q3 Faturası",
"category": "faturalama",
"tags": ["fatura", "2026", "ödendi"]
}
Böylece istek iki parçadan oluşur: q3-invoice.pdf taşıyan file (tür file) ve bu JSON'ı taşıyan metadata (tür string). Sunucu dosyayı bir parçadan okur ve JSON'ı diğerinden ayrıştırır. Birçok genel API yüklemeleri tam olarak bu şekilde alır; Stripe dosya yükleme belgeleri, bir dosya parçasını düz alanlarla eşleştiren gerçek bir çok parçalı uç noktanın iyi bir örneğidir. Bu model o kadar yaygındır ki Postman kullanıcıları da buna denk gelir; geçiş yapıyorsanız, Postman'da dosya ve JSON verilerini yükleme kılavuzu, Apidog'un form-data alanlarına temiz bir şekilde eşlenir.
Birden fazla dosya eklemeniz mi gerekiyor? Türü file olan başka bir parametre ekleyin. Bir ana dosya ve bir küçük resim kabul eden bir POST /documents, her birinin kendi Yükle düğmesi olan file ve thumbnail olmak üzere iki dosya satırı alır. Özel bir çoklu dosya modu yoktur; uç noktanın beklediği her parçayı kapsayana kadar dosya türü parametreleri eklersiniz.
İsteği tekrarlanabilir bir test senaryosuna dönüştürün
Tek bir gönderim, uç noktanın bir kez çalıştığını kanıtlar. Gerilemeleri yakalamak için, isteğe bağlı olarak veya belirli bir programda çalışan, kaydedilmiş bir test senaryosu içinde yükleme yapmak istersiniz. Adımları zincirleyin: avatarı yükleyin, döndürülen id'yi yakalayın, ardından GET /users/{id}'yi çağırın ve avatar URL'sinin kalıcı olduğunu doğrulayın.
Bunu tek isteği oluşturduğunuz gibi oluşturun, ardından bir senaryodaki bir adım olarak kaydedin. Apidog ile test senaryosu nasıl yazılır kılavuzu, adım zincirleme ve adımlar arasında değer geçirmeyi kapsar. Yükleme bir senaryoda yer aldığında, her dağıtım sonrası test ortamına karşı çalıştırabilir, API test senaryolarında koşullu mantık ile koşullu dallar ekleyebilir veya planlanmış API testleri ile bir zamanlayıcıya bağlayabilirsiniz.
Yukarıdaki her şey makinenizde sorunsuz çalışır, çünkü makinenizde dosya vardır. Bu varsayım, bir sonraki bozulacak olan şeydir.
Yakalanan sorun: Başka bir yerde çalışan yüklemeler
İşte mutlu yolun sakladığı kısım. Apidog, dosyanın kendisini değil, dosya yolunu saklar. Dizüstü bilgisayarınızda bu görünmezdir, çünkü yol her seferinde gerçek bir dosyaya çözümlenir. Aynı adım farklı bir makinede çalıştığı anda, yol hiçbir şeye işaret etmez.
Bunu iki yerde göreceksiniz.
Ekip işbirliği. Bir ekip arkadaşınız POST /avatars isteğinizi açtığında, sizin seçtiğiniz dosya parametresini ve yolu görür, örneğin /Users/jane/pics/jane-profile.png. İsteği görebilirler, ancak gönderemezler, çünkü o dosya onların diskinde değil, sizin diskinizde yaşar. Yol, onu seçen makineye özeldir.
Runner ve CLI çalıştırmaları. Otomasyonda can yakan kısım budur. Yükleme senaryonuz yerel olarak geçer, onu Runner'da planlar veya CLI'dan çalıştırırsınız ve dosya yükleme adımı başarısız olur. Doğrulayıcılarınızda yanlış bir şey yoktur. Çalıştırıcı, dizüstü bilgisayarınızın kaydettiği yolda bir dosya bulamaz, çünkü o yol çalıştırıcının ana bilgisayarında mevcut değildir.
Çözüm nedenden gelir. Dosyanın gönderimi yapan makinede bulunması gerekir ve adımın yolu orada ona işaret etmelidir.
Runner için: Runner, birimlerine bağlanan bir ana dizinden dosyaları okur. Bu bağlamayı Runner'ı dağıtırken -v bayrağını kullanarak ayarlarsınız. Yükleme dosyanızı bu bağlı ana dizine kopyalayın. Ardından senaryodaki dosya yükleme adımının adım ayrıntılarını açın, sağ üst köşedeki Toplu Düzenleme düğmesine tıklayın ve dosya alanının değerini Runner'ın dizini içindeki yolla değiştirin, örneğin:
/opt/runner/jane-profile.png
CLI için: aynı şekil. Dosyayı CLI makinesine koyun, ardından adımı Toplu Düzenleme kullanarak yolun oradaki konumuna işaret etmesini sağlayın, örneğin:
/opt/apidog/runner/jane-profile.png
Sabit kodlamadan daha temiz: bir değişken kullanın. Adımda sabit bir yol sabitlemek yerine, değeri bir değişkenle değiştirin ve değişkenin değerini ortama göre gerçek dosya yoluna ayarlayın. Böylece aynı senaryo, her seferinde adımı düzenlemeden dizüstü bilgisayarınızda, Runner'da ve CI'da çalışır. Değişkeni yerel olarak /Users/jane/pics/jane-profile.png'ye ve Runner'da /opt/runner/jane-profile.png'ye işaret edersiniz ve adımın kendisi asla değişmez.
Açıkça belirtmeye değer bir ön koşul: Runner, yalnızca dağıtım sırasında -v bayrağıyla bağladığınız dizinin altında bulunan ana bilgisayar dosyalarına ulaşır. Dosyanız o bağlama altında değilse, hiçbir yol onu bulamaz. Bu bir dağıtım kurulum ayrıntısıdır, bir plan sınırlaması değildir. Apidog'un dosya yükleme istekleri hakkındaki belgeleri, standart versiyonunu isterseniz bağlama ve toplu düzenleme adımlarını açıklar.
İş akışını Apidog CLI ile otomatikleştirin
Yükleme senaryonuz kaydedildikten sonra, onu CI'da başsız çalıştırabilirsiniz. CLI'ı kurun ve kimlik doğrulayın:
npm install -g apidog-cli
apidog login --with-token <ERİŞİM_TOKENİNİZ>
Ardından kaydedilmiş senaryoyu kimliğine göre, bir ortama işaret ederek çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <senaryo_id> -e <ortam_id> -r cli
Burada -t test senaryo kimliği, -e ortam kimliği ve -r raporlayıcıdır (birkaçı için virgülle ayrılmış olarak cli, html veya junit kullanın). CLI, kaydedilmiş senaryolarınızı bulut projesinden çalıştırır ve başarılı/başarısız durumlarını çıkış kodlarıyla raporlar, bu da bir işlem hattını kontrol etmesini sağlar. Kurulum ayrıntıları Apidog CLI kurulum kılavuzunda bulunur.
Bir dürüst uyarı, ve bu son bölümdeki ile aynıdır: dosya yükleme adımı içeren bir senaryonun, dosyanın CLI makinesinde bulunmasını gerektirir ve adımın yolu oradaki dosyayı işaret etmelidir. Dosyayı çalıştırıcıya koyun, ardından çalıştırmadan önce yolu Toplu Düzenleme ile (veya bir değişken kullanarak) yeniden ayarlayın. Bunu atlarsanız, senaryonun geri kalanı iyi olsa bile yükleme adımı dosyayı bulamaz. Satır başına giriş geçirme dahil daha kapsamlı bir CI kurulumu için, Apidog CLI ile veri odaklı test bölümüne bakın.
SSS
Ekip arkadaşım neden dosya yükleme isteğimi gönderemiyor? Apidog, dosyanın kendisini değil, yerel dosya yolunu saklar ve dosyayı asla buluta yüklemez. Ekip arkadaşınız isteği ve sizin seçtiğiniz yolu görür, ancak bu yol onların diskindeki bir dosyaya değil, sizin diskinizdeki bir dosyaya çözümlenir. Onlara dosyanın bir kopyasını kendi makinelerine koymalarını ve alanı kendi yollarına işaret etmelerini söyleyin. Aynı mekanik, planlanmış testlerin ve Runner işlerinin dosyanın çalıştıkları yerde hazırlanması gerektiğini neden açıkladığını da gösterir.
Aynı istekte bir dosya ile JSON'ı nasıl gönderirim? Gövde türünü form-data olarak tutun. Dosya alanınızı file türüyle ekleyin, ardından string türünde başka bir parametre ekleyin ve JSON'ı değerine yapıştırın. Sunucu her iki parçayı da tek bir çok parçalı istekte alır: dosya bir parçada, JSON dizesi diğer parçada. Bu, bir yüklemeye meta veri eklemenin standart yoludur.
Runner'da bir dosya için hangi yolu kullanmalıyım? Dağıtım sırasında -v bayrağıyla Runner'ın birimine bağladığınız ana dizin içindeki bir yolu kullanın, örneğin /opt/runner/dosyanız.jpg. Dosyayı bu bağlı dizine kopyalayın, ardından adımı açın, Toplu Düzenleme'ye tıklayın ve alanın değerini o yola ayarlayın. CLI karşılığı /opt/apidog/runner/dosyanız.jpg gibi görünür.
Dosya boyutu sınırı veya izin verilen dosya türü listesi var mı? Apidog'daki yükleme davranışı, isteğin nasıl oluşturulduğu ve dosyanın nereden okunduğu ile ilgilidir. Boyut ve tür üzerindeki gerçek sınırlamalar test ettiğiniz API'den gelir, bu nedenle sunucunuzun kendi doğrulama kurallarını kontrol edin ve aşırı boyutlu veya reddedilen dosyalar için döndürdüğü yanıtlara karşı doğrulayıcılar yazın.
Yüklemeler için form-data mı yoksa x-www-form-urlencoded mi kullanmalıyım? form-data kullanın. multipart/form-data'ya eşlenir ve dosya taşımak için oluşturulmuştur. x-www-form-urlencoded, dosyasız, kısa skaler alanlardan oluşan basit formlar içindir, bu nedenle resminizi veya PDF'inizi taşımaz.
Özetle
Dosya yükleme testi iki şeye dayanır: çok parçalı isteği doğru oluşturmak ve dosyanın testin çalıştığı her yerde erişilebilir olduğundan emin olmak. Apidog'da Gövdeyi form-data olarak ayarlarsınız, alanınızın türünü file olarak değiştirirsiniz, Yükle'ye tıklarsınız, herhangi bir JSON'ı bir dize parçası olarak eklersiniz, sonra gönderir ve doğrulayıcıları çalıştırırsınız. Aynı senaryoyu Runner veya CLI'ya taşıdığınızda, dosyayı o makinede hazırlayın ve yolu Toplu Düzenleme veya bir değişkenle yeniden işaretleyin, böylece otomatikleştirilmiş çalıştırma yerel çalıştırmanız gibi davranır.
Kendi uç noktanıza karşı denemek ister misiniz? Apidog'u indirin, yükleme rotanıza bir form-data isteği yönlendirin ve yanıtın geri gelmesini izleyin. Başlamak ücretsizdir, kredi kartı gerekmez.