Yeni Başlayanlar İçin curl: Kapsamlı Bir Kılavuz

Bu yazıyı kimin yazdığına dair kısa bir not. Biz Geonode olarak proxy satışı yapıyoruz; bu nedenle, bir sorunu teşhis ederken insanlara en sık kullanmalarını önerdiğimiz araç curl’dur. Yeni başlayanlar için dürüst bir açıklama: curl bir proxy aracı değildir ve onu öğrenmek için proxy’ye ihtiyacınız yoktur. Aşağıdaki tüm işlemler, kendi bağlantınız üzerinden halka açık uç noktalara karşı ücretsiz olarak gerçekleştirilir. Proxy'ler, çok daha sonra, hedef sitenin size hız sınırlaması uygulayacak kadar çok istek gönderdiğinizde veya bir sayfanın başka bir ülkeden nasıl göründüğünü kontrol etmeniz gerektiğinde önem kazanır. Bunların ikisi de yeni başlayanlar için bir sorun değildir. Önce aracı öğrenin.

curl Nedir ve Ne İçin Kullanılır?

curl, URL’leri kullanarak veri aktarımı için kullanılan bir komut satırı programıdır. Kendi kılavuzunda, programın “DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS ve WSS" protokollerini desteklediği belirtilse de, pratikte neredeyse herkes onu HTTP ve HTTPS için kullanır.

Ne için kullanılır:

• Bir terminalden veya komut dosyasından API'yi çağırmak
• Bir URL'nin çalışıp çalışmadığını ve ne döndürdüğünü kontrol etmek
• Sunucunun tam olarak ne gönderdiğini, başlıklar dahil her şeyi görmek
• Dosya indirmek
• Hata ayıklama: Sorunun kodunuzda mı yoksa sunucuda mı olduğunu bulmak için uygulamanızın dışında bir isteği yeniden oluşturmak

Nedir değil: bir tarayıcı. JavaScript'i çalıştırmaz, hiçbir şeyi görüntülemez ve siz talimat vermedikçe oturum tutmaz. Tarayıcıda dolu görünen bir sayfa, curl'a neredeyse boş bir iskelet döndürebilir ve bu, bir hata değil, beklenen bir durumdur.

İlk İstekleriniz

curl https://example.com

Bu komut bir GET isteği gerçekleştirir ve yanıt gövdesini terminalinize yazdırır. Çıktı uzun bir HTML metni ise, curl düzgün çalışıyor demektir.

Hemen kullanabileceğiniz dört farklı seçenek:

Gövdenin yanı sıra başlıkları da görüntüleyin: -i

komutuyla; bu komutun açıklaması -i, --show-headers

adresinde bulunabilir: "Çıktıda yanıt başlıklarını göster."

curl -i https://example.com

Bir dosyaya kaydedin: -o

(seçtiğiniz ad) veya -O

(uzak ad) ile:

curl -o page.html https://example.com
curl -O https://example.com/file.zip

Yönlendirmeleri takip edin: -L

ile: "HTTP yönlendirmelerini takip edin ve istekleri başlangıçta belirtilen yöntemle tekrarlayın." Bu seçenek kullanılmadığında, curl ilk yönlendirmede durur ve hedef sayfa yerine yönlendirme sayfasını gösterir.

curl -L https://example.com

-sS

ile hareketsiz kalın ama hataları yine de bildirin. -s

ilerleme çubuğunu gizler, -S

hata mesajlarını gösterir. İkisi birlikte herhangi bir komut dosyasında aradığınız şeydir.

curl -sS https://example.com

Bu makaleden tek bir satır hatırlayacaksanız, bu satır olsun:

curl -sSL https://example.com

Yanıtı Okuma

Yeni başlayanlar, cevap başlıklarda yer almasına rağmen genellikle gövde kısmına odaklanırlar.

curl -i https://example.com

HTTP/2 200
content-type: text/html; charset=UTF-8
content-length: 1256

İlk satır durum kodudur. 200

, işlemin başarılı olduğunu gösterir. 301

ve 302

, yönlendirmelerdir — -L

ekleyin. 401

ve 403

, erişim izninizin olmadığını gösterir. 404

, sayfanın mevcut olmadığını gösterir. 429

, çok hızlı hareket ettiğinizi gösterir. 500

ve üzeri değerler, sunucuda bir sorun olduğunu gösterir.

content-type

size gerçekte ne aldığınızı gösterir ve birçok kafa karışıklığını giderir. JSON bekleyerek bir API'yi çağırdıysanız ve text/html

mesajını gördüyseniz, bir hata sayfası veya oturum açma yönlendirmesi almışsınız demektir ve karşılaşmak üzere olduğunuz ayrıştırma hatası, sorunun nedeni değil, bir belirtisidir.

Gövde olmadan başlıkları almak için:

curl -sS -o /dev/null -D - https://example.com

Bu komut normal bir GET isteği yapar, gövdeyi atar ve başlıkları gösterir. Bu, HEAD

isteği gönderen ve farklı davranabilen -I

adresinden daha güvenilirdir — bu ayrım, curl HEAD istekleri kılavuzumuzda ele alınmıştır.

Ham başlıkların yerine bir özet için, -w

seçilen değerleri yazdırır:

curl -sS -o /dev/null -w 'status=%{response_code} time=%{time_total}s\n' https://example.com

Başlıkları doğru şekilde okumakla ilgili daha fazla bilgi için curl ile yanıt başlıklarını gösterme bölümüne bakabilirsiniz.

Veri Gönderme

İşin diğer yarısı.

Form verileriyle bir POST isteği:

curl -d "name=Ada&role=engineer" https://api.example.com/users

-d kullanımı, POST yöntemini ima eder ve Content-Type: application/x-www-form-urlencoded ayarını yapar.

JSON içeren bir POST isteği — ve bu, yeni başlayanların en sık yaptığı hatadır; çünkü -d tek başına bir JSON içerik türü ayarlamaz:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","role":"engineer"}'

Bu başlığı göz ardı ederseniz, birçok API 415 Unsupported Media Type hatasını döndürür; bu, hatanın verileriniz yerine Content-Type adresine atıfta bulunduğunu anlayana kadar kafa karıştırıcı bir hatadır. Bu hatayla ilgili ayrıntıları 415 durum kodu nedir başlıklı yazımızda ele aldık.

Bir dosyadan alınan veriler; "bu dosyayı oku" anlamında @ kullanılarak:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

Sorgu parametreleri içeren bir GET; anahtar-değer çiftlerinden oluşturulur ve -G kullanılır:

curl -G https://api.example.com/search -d "q=proxy" -d "limit=10"

-X ile diğer yöntemler. Bunu yalnızca özel bir seçeneği olmayan yöntemler için kullanın — PUT, DELETE, PATCH. Kılavuzdaki şu uyarıya dikkat edin: -X "yalnızca HTTP isteğinde kullanılan kelimeyi değiştirir, curl'ün davranışını değiştirmez"; bu nedenle -X HEAD çalışmaz ve -I vardır.

Başlıklar, Kimlik Doğrulama ve Çerezler

-H

ile özel başlıklar, tekrarlanabilir:

curl -H "Authorization: Bearer eyJhbG..." \
     -H "Accept: application/json" \
     https://api.example.com/me

-u

ile temel kimlik doğrulama:

curl -u username:password https://api.example.com/private

Şifreyi belirtmezseniz, curl şifreyi sorar; bu sayede şifre, kabuk geçmişinizde yer almaz:

curl -u username https://api.example.com/private

-A

ile bir kullanıcı ajanı, çünkü curl varsayılan olarak kendisini curl olarak tanımlar ve bazı sunucular farklı yanıtlar verir:

curl -A "Mozilla/5.0 (compatible; MyBot/1.0; +https://example.com/bot)" https://example.com

Otomatik bir istemci yazıyorsanız, iletişim URL'si içeren dürüst bir kullanıcı ajanı hem iyi bir davranış hem de pratik bir avantajdır — kimliği belirli otomasyon, kimliği belirsiz otomasyona göre çok daha kolay engellenir.

Çerezler. curl, siz talep etmedikçe çağrılar arasında çerezleri saklamaz:

curl -c cookies.txt -d "user=ada&pass=secret" https://example.com/login
curl -b cookies.txt https://example.com/dashboard

-c

bir çerez kavanozu yazar, -b

ise bir çerez kavanozunu okur. Oturum gerektiren her şeyi bu şekilde halledebilirsiniz.

Kablodan Gerçekte Ne Geçtiğini Görmek

Hata ayıklamayı hızlı yapanlarla, sadece tahminde bulunanları ayıran alışkanlık.

curl -v https://example.com

Kılavuzda önekler şöyle açıklanmaktadır: ">

curl tarafından gönderilen başlık, <

curl tarafından alınan başlık, }

curl tarafından gönderilen veri, {

curl tarafından alınan veri, *

curl tarafından sağlanan ek bilgi."

Yalnızca gönderdiğiniz bilgileri görmek için:

curl -v https://example.com 2>&1 | grep '^>'

Bu, bir dizi karışıklığı ortadan kaldırır; çünkü kodda ayarladığınız başlık her zaman iletilen başlık olmayabilir. Kütüphaneler varsayılan değerler ekler, değerleri geçersiz kılar ve sıralamayı değiştirir. Bir sunucu başlığınızı "görmezden gelirse", önce onu gerçekten gönderip göndermediğinizi kontrol edin.

Ayrıntılı çıktı stderr'e gönderilir; bu nedenle, boruya aktarmadan önce 2>&1

komutunun kullanılması gerekir — bu kasıtlıdır, böylece stdout'taki gövde temiz kalır.

Kılavuzda yer alan ve tekrarlanmaya değer bir uyarı: ayrıntılı ve izleme çıktıları "kullanıcı adları, kimlik bilgileri veya gizli veri içeriği dahil olmak üzere hassas veriler içerebilir". Bir bilete yapıştırmadan önce bu bilgileri gizleyin.

Ezberlemeye Değer Bayraklar

Yukarıdaki her şey küçük bir kümeye indirgenebilir.

Son ikisi, yeni başlayanların atladığı ve daha sonra pişman olduğu seçeneklerdir.

--fail önemlidir çünkü curl, varsayılan olarak 404 adresini başarılı bir aktarım olarak değerlendirir — hata sayfasını indirir ve 0 çıkış kodu verir. Bir komut dosyasında bu, HTML hata sayfasını installer.dmg adıyla kaydedip işleme devam ettiğiniz anlamına gelir. --fail, HTTP hatalarının sıfırdan farklı bir çıkış kodu üretmesini ve çıktı vermemesini sağlar.

Zaman aşımları önemlidir çünkü curl'ün varsayılan olarak genel bir zaman sınırı yoktur. Takılan bir istek, betiğinizi süresiz olarak askıya alır. --connect-timeout 5 -m 30 komutu bunu sınırlar. Bu konu hakkında daha fazla bilgi için curl ile zaman aşımı ayarlama bölümüne bakabilirsiniz.

Her betiğe eklenmesi gereken satır:

curl --fail --silent --show-error --location --connect-timeout 5 --max-time 30 "$URL"

Baştan Sona Bir Uygulama Örneği

Gerçekçi bir görevde parçaları bir araya getirme: halka açık bir API’yi çağırma, çalışıp çalışmadığını kontrol etme ve hata durumunu yönetme.

Birinci adım — uç noktanın ne döndürdüğüne bakın. Gövdeyle değil, başlıklarla başlayın:

curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl

Bir durum satırı ve başlıklar alırsınız. Durum 200

ise ve content-type

JSON diyorsa, doğru yerle iletişim kuruyorsunuz demektir.

İkinci adım — biçimlendirilmiş gövdeye bakın. Tek satırda ham JSON okunamaz, bu yüzden jq

üzerinden geçirin:

curl -sS https://api.github.com/repos/curl/curl | jq '{name, stargazers_count, language}'

jq

yüklü değilse, python3 -m json.tool

ek bir bağımlılık olmadan biçimlendirme işini halleder.

Üçüncü adım — gönderdiğiniz veriyi kontrol edin. Bir şey yolunda gitmiyorsa, tahminde bulunmak yerine isteğe bakın:

curl -v https://api.github.com/repos/curl/curl 2>&1 | grep '^>'

Dördüncü adım — komut dosyası için güvenli hale getirin. Hata işleme ve zaman sınırlamaları ekleyin ve durumu gövdeden ayrı olarak yakalayın:

#!/usr/bin/env bash
set -euo pipefail

URL="https://api.github.com/repos/curl/curl"
BODY=$(mktemp)

STATUS=$(curl --silent --show-error --location \
              --connect-timeout 5 --max-time 30 \
              --write-out '%{response_code}' --output "$BODY" \
              "$URL")

case "$STATUS" in
  200) jq -r '.stargazers_count' < "$BODY" ;;
  404) echo "not found" >&2; exit 1 ;;
  429) echo "rate limited, retry after: $(date)" >&2; exit 1 ;;
  *)   echo "unexpected status $STATUS" >&2; head -c 200 "$BODY" >&2; exit 1 ;;
esac

rm -f "$BODY"

Buradaki üç noktayı yazdığınız her şeye uygulamaya değer. --write-out '%{response_code}'

ile --output

, durumu gövdeden ayırır, böylece buna göre dallanma yapabilirsiniz. Beklenmeyen bir durumda gövdenin ilk 200 karakterini yazdırmak, gizemi okunabilir bir hataya dönüştürür. Ve --connect-timeout

ile --max-time

, ağ bağlantısı kesilse bile komut dosyasının tamamlanmasını sağlar.

Beşinci adım — hız sınırına uyun. Genel API’ler sınırlarını başlıklarda yayınlar. Bunları okumak hiçbir maliyeti yoktur ve engellenmenin en yaygın nedenini önler:

curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl | grep -i ratelimit

Yeni Başlayanların Sık Yaptığı Hatalar

-L'i unutmak. Yönlendirme bildirimi içeren kısa bir yanıt alırsınız ve URL'nin bozuk olduğu sonucuna varırsınız. Oysa bozuk değildir.

Komut dosyalarında --fail'i unutmak. 404 adresi, kaydedilmiş bir hata sayfası ve sıfır çıkış kodu haline gelir. Bu durum fark edilmez, ancak ileride maliyetli sonuçlar doğurur.

Content-Type ayarını yapmadan JSON ile -d kullanmak. Sunucuda 415 hatası veya kafa karıştırıcı bir ayrıştırma hatası ortaya çıkar.

Shell tırnak işaretleri. Tek tırnak işaretleri her şeyi olduğu gibi korur; çift tırnak işaretleri ise shell'in $ ve ters tırnak işaretlerini genişletmesine izin verir. Çift tırnak işaretleri içeren bir JSON gövdesi için, bunu tek tırnak işaretleri içine alın. Verilerinizde tek tırnak işaretleri de varsa, bunları bir dosyaya kaydedin ve -d @file.json komutunu kullanın.

curl'un tarayıcının gördüklerini gördüğünü varsaymak. curl, JavaScript'i çalıştırmaz. Tarayıcıda dolu görünen bir sayfadan gelen neredeyse boş bir yanıt, içeriğin istemci tarafında işlendiği anlamına gelir ve curl doğru şekilde çalışmaktadır.

Durum kodunu göz ardı etmek. 200 durum koduyla "hata" yazan bir gövde ile 500 durum koduyla "hata" yazan bir gövde, farklı sorunlardır. Her ikisini de okuyun.

Komut satırına kimlik bilgilerini girmek. Bu bilgiler kabuk geçmişine kaydedilir ve makinedeki diğer kullanıcılar tarafından işlem listesinde görülebilir. -u user kullanın ve curl'un kullanıcıdan bilgi istemesini sağlayın ya da bir ortam değişkeninden okumasını sağlayın.

Bir şeyin çalışması için sertifika doğrulamasını devre dışı bırakmak. -k, size bir şey anlatan bir uyarıyı susturur. Önce ne olduğunu öğrenin.

Bundan Sonra Nereye?

Temel konuları iyice kavradıktan sonra, doğal olarak atılacak sonraki adımlar şunlardır:

Düzgün indirme — kesintiye uğrayan aktarımları devam ettirme, paralel indirme, hız sınırlama. Bu konular curl ile dosya indirme başlığında ele alınmıştır.

Zaman aşımları ve yeniden denemeler; işte bu noktada komut dosyaları artık kırılgan olmaktan çıkar. curl ile zaman aşımı ayarlama başlığına bakın.

Başlıkları veri olarak okuma; %{header_json} komutu, ayrıştırmanız gereken metin yerine JSON çıktısı verir.

curl ile wget karşılaştırması; bu iki araç kısmen örtüşse de farklı alanlarda başarılıdır — curl ile wget karşılaştırması başlığı, ne zaman hangisini kullanmanız gerektiğini ele alır.

Proxy'ler, sonunda bunlara ihtiyacınız olduğunda: -x http://host:port bir isteği bir proxy üzerinden yönlendirir. Coğrafi kontroller ve trafik dağıtımı için gerçekten kullanışlıdır; öğrenme amaçlı veya sınırlı kullanım için ise gerçekten gereksizdir.

Kılavuz. man curl uzun bir belgedir ve bu konuda en yetkili kaynaktır. Halihazırda kullandığınız bir bayrakla ilgili maddeyi okumak, aslında aradığınız seçeneği bulmanın güvenilir bir yoludur.

Kullanıcılar Ayrıca Şunları Soruyor

curl ne için kullanılır?

Komut satırından veya bir komut dosyasından URL’ler üzerinden veri aktarımı yapmak — API’leri çağırmak, sunucunun ne döndürdüğünü kontrol etmek, dosya indirmek ve bir sorunu izole etmek için uygulama dışında bir isteği yeniden oluşturmak. Birçok protokolü destekler, ancak ağırlıklı olarak HTTP ve HTTPS için kullanılır.

curl ile GET isteği nasıl yapılır?

curl https://example.com. GET varsayılan ayardır, bu nedenle herhangi bir bayrak gerekmez. Yönlendirmeleri takip etmek için -L ve yanıt gövdesi ile birlikte yanıt başlıklarını görmek için -i ekleyin.

curl ile JSON'u nasıl gönderirim?

curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL. Başlık çok önemlidir — tek başına -d, form kodlu içerik türü gönderir ve JSON bekleyen API'ler genellikle bunu 415 hatasıyla reddeder.

curl neden hiçbir şey döndürmüyor?

Birkaç olasılık vardır: yanıt gövdesi gerçekten boş, takip etmediğiniz bir yönlendirmeye uymuşsunuz (-L ekleyin), içerik curl tarafından çalıştırılmayan JavaScript tarafından oluşturuluyor veya istek başarısız oldu ve -S olmadan -s kullandığınız için hatayı görmediniz. Durum kodunu görmek için -i ile çalıştırın.

curl'da -o ve -O arasındaki fark nedir?

-o filename, seçtiğiniz bir adla kaydeder. -O, URL'deki dosya adını kullanarak kaydeder ve yolu atlar. URL'de kullanışlı bir dosya adı yoksa veya belirli bir ad kullanmanız gerekiyorsa -o komutunu kullanın.

curl'un gönderdiği isteği nasıl görebilirim?

curl -v URL komutunu çalıştırın ve > ile başlayan satırları arayın. Ayrıntılı çıktı stderr'e gönderilir, bu nedenle boruya aktarmadan önce 2>&1 ekleyin. Bu, yapılandırdığınız bir başlığın gerçekten ağa ulaştığını doğrulamanın en hızlı yoludur.

curl varsayılan olarak yönlendirmeleri takip eder mi?

Hayır. -L ekleyin. Bu, yeni başlayanların curl komutlarının beklenmedik şekilde kısa bir yanıt döndürmesinin en yaygın nedenidir — hedef adresi değil, yönlendirmeyi görüyorsunuz.

curl'u kullanmak için bir proxy'ye ihtiyacım var mı?

Hayır. curl, kendi bağlantınız üzerinden halka açık uç noktalara sorunsuz bir şekilde çalışır. Proxy'ler, yalnızca hız sınırlamasına tabi olacak kadar çok istek gönderdiğinizde veya bir sitenin başka bir ülkede ne sunduğunu görmeniz gerektiğinde önem kazanır. Öğrenme aşamasındayken bunların hiçbiri bir şey satın almanız için bir neden değildir.

Sonuç

curl, göz korkutucu sayıda seçeneğe sahip olmakla birlikte, gerçekten kullanışlı olan çekirdek kısmı oldukça küçüktür. Başlıkları görmek için -i, yönlendirmeleri takip etmek için -L, kaydetmek için -o, başlık eklemek için -H, veri göndermek için -d, kimlik doğrulama için -u, ne olduğunu görmek için -v ve gözetimsiz çalışan her şey için --fail artı bir zaman aşımı. Çoğu kişi için gerekli olan tüm işlevler bunlardır.

Herhangi bir bayraktan daha önemli olan iki alışkanlık vardır: gövdeyi okumadan önce durum kodunu ve Content-Type adresini okuyun, çünkü bunlar genellikle sorunu doğrudan belirtir; ve -v adresini kullanarak göndermek istediğiniz şey yerine gerçekte ne gönderdiğinizi kontrol edin, çünkü bu ikisi arasındaki fark, şaşırtıcı derecede çok sayıda hatanın kaynağıdır.

Bunların ötesindeki her şey kılavuzda yer alır; bu kılavuz uzundur, yetkili bir kaynaktır ve bir geçici çözüm yazarken göz atmaya değer. Genellikle aradığınız seçenek mevcuttur.