Bulut depolama REST API başlangıç kılavuzu
Salt okunur REST anahtarı oluşturun. curl ile çalışma alanlarını ve dosyaları listeleyin. Verileri değiştirmeden kimlik doğrulama, erişim ve yeniden deneme yanıtlarını inceleyin.
Son inceleme
Ekran görüntülerinde İngilizce arayüz gösterilir.
Çalışma alanlarınızı listelemek, hedef seçmek ve dosyalarını okumak için https://api.dosya.dev/api adresindeki bulut depolama REST API’sini kullanın. Bu kılavuz, kayıtlı dosyaları değiştirmeyen kimliği doğrulanmış okuma istekleri gönderir. API yolu /api şeklindedir. /v1 veya /v2 eklemeyin.
Test için erişim bilgileri oluşturun
- Profil → API anahtarları sayfasında oturum açıp Yeni API anahtarı seçin.
- Ne için kullanılacak? alanına tanıyacağınız bir ad yazın. Hangi işlemleri yapabilir? altında Salt okunur seçin.
- Kısıtlamalar ve geçerlilik süresi bölümünü genişletin. Protokoller altında Yalnızca seçtiklerim seçip REST API kutusunu işaretleyin. Entegrasyon tek bir çalışma alanına erişecekse ilgili Çalışma alanı seçimini yapın. Klasör alanını boş bırakın. REST, bir kök klasöre bağlı normal anahtarları reddeder.
- 30 gün sonra sona erer seçin, özeti kontrol edip Anahtar oluştur seçin. hazır iletişim kutusunda
dos_belirtecinin tamamını Tamam seçmeden kopyalayın. Anahtar listesinde sonradan görüntülenemez.
Ücretsiz hesapta en fazla üç API anahtarı bulunabilir. Diğer planlarda hesap genelindeki sınır 20’dir. Süresi dolmuş mevcut anahtarlar da sayılır. Anahtar izinleri hesabınızın erişimini daraltır. Size çalışma alanı üyeliği veya rolünüzde bulunmayan bir izin vermez.

Adımlar: ilk isteği gönderin
Örnekler için komut kabuğu, curl ve Python 3 gerekir. DOSYA_API_KEY değişkenini sır yöneticisiyle veya etkileşimli istemle ayarlayın. Kaydedilen bir komutta değişkenin yerine gerçek belirteci asla yazmayın. Bash için etkileşimli bir yöntem:
read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
curl --fail-with-body --silent --show-error \
'https://api.dosya.dev/api/workspaces' \
-H "Authorization: Bearer $DOSYA_API_KEY" \
-o workspaces.json
python3 -c 'import json; d=json.load(open("workspaces.json")); print([(w["id"],w["name"]) for w in d["workspaces"]])'
Başarılı istek, ok: true ve workspaces dizisiyle HTTP 200 döndürür. Çalışma alanının görünen adını değil, dönen kimliğini kullanın. Bir çalışma alanına bağlı anahtar yalnızca o alanı görür. Boş dizi, hesapta hiç çalışma alanı olmadığını kanıtlamaz. Anahtarın erişim sınırlarını ve mevcut üyeliğinizi kontrol edin.
Bir çalışma alanının kök klasöründeki dosyaları okuyun:
DOSYA_WORKSPACE_ID='REPLACE_WITH_RETURNED_WORKSPACE_ID'
curl --fail-with-body --silent --show-error --get \
'https://api.dosya.dev/api/files' \
-H "Authorization: Bearer $DOSYA_API_KEY" \
--data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
--data-urlencode 'page=1' --data-urlencode 'per_page=100' \
-o files.json
python3 -m json.tool files.json
Dosya listesi sayfa başına varsayılan 100 öğe döndürür. per_page değeri 10–500 olabilir. Bilinen bir alt klasörü listelemek için folder_id belirtin. Dönen dosya kimlikleri üstveri ve indirme yollarında kullanılır. Çalışma alanı rolünüz dosyalar sayfasına erişime izin vermelidir. Gizli içerik ve klasör kısıtlamaları listeyi daraltabilir.
Yazma işlemleri eklemeden hataları kontrol edin
| Yanıt | Yapılacak değişiklik |
|---|---|
401, Invalid or expired API key | Belirtecin tamamını kullanın. Geçerlilik süresini ve geçersiz kılınıp kılınmadığını kontrol edin. Authorization: Bearer … üstbilgisini aynen koruyun. |
403, This API key is not permitted to use the api surface | Anahtarın protokol seçimine REST API’yi ekleyin. |
403, This API key is anchored at a folder and can only be used over WebDAV or the S3 gateway | Kök klasöre bağlı olmayan, bir çalışma alanına bağlı REST anahtarı oluşturun. |
403, This API key is restricted to specific source addresses | İzin verilen bir adresten gönderin. Yönlendirme üstbilgilerini sahtelemeyin. |
403, This API key is being used outside its allowed hours | Saat dilimini, seçili günleri ve haftalık zaman aralığını kontrol edin. |
429, Retry-After ile | Belirtilen saniye kadar bekleyin. Sürekli yeniden denemek yerine eşzamanlı istekleri yavaşlatın. |
503, Service temporarily unavailable | Erişim bilgilerini koruyun. Yanıttaki beş saniyelik beklemeden sonra yeniden deneyin. Bu kimlik doğrulama sorgusu hatası, anahtarı değiştirme nedeni değildir. |
Kimlik doğrulamadan sonra protokol, adres/zaman, kök klasör, izin kapsamı ve bağlı çalışma alanı denetlenir. Anahtarın istek sayacı ancak bunlardan sonra işler. Salt okunur anahtar listeleyip indirebilir. Yazma girişimi ise kapsam, yöntem ve yolu belirten mesajla reddedilir. Tam erişimli anahtarla değerli veriler üzerinde bu sınırı denemeyin.
HTTP durumu ve JSON error hatayı tanımlar. Birçok JSON yanıtında ok bulunur. İndirme URL’si uç noktası ise url, size, name ve region döndürür, ok alanı içermez. Tek bir evrensel biçim varsaymayın. Uç noktanın gerçek yanıtını doğrulayın. Durumu, hatayı ve varsa istek kimliğini saklayın. Yetkilendirme üstbilgisini gizleyin.
Beklenen sonuç ve testten sonra güvenli temizlik
Dönen çalışma alanı kimliklerini ve dosya adlarını oturum açtığınız uygulamayla karşılaştırın. Listeleme yükleme, silme veya paylaşım bağlantısı oluşturma işlemi yapmaz. Bu istekler hiçbir alıcıya dosya göndermez. Yalnızca saklama izniniz olan üstveriyi kaydedin.
Test bitince Profil → API anahtarları bölümüne dönün. Test anahtarını genişletip Geçersiz kıl seçin, ardından tekrar Geçersiz kıl ile onaylayın. Bu işlem geri alınamaz. Anahtarı kullanan entegrasyonların kimlik doğrulaması durur. Anahtar oluşturma, listeleme ve kimlikle silme için açık oturum gerekir. Taşıyıcı anahtar başka anahtar oluşturamaz veya yönetemez. Üretimde okuma, yükleme ve yönetim için ayrı erişim bilgileri kullanın. Bir isteği yinelemeden önce sonucu belirsiz yazma işleminin durumunu netleştirin.
İlgili kılavuzlar
Bu rehber yararlı oldu mu?
Değerlendirmeler yükleniyor…
Yanıtınızı değiştirebilmeniz için oy verdiğinizde gerekli bir oylama çerezi kaydedilir. Bu çerez en fazla 180 gün saklanır.
Sorular ve yanıtlar
Bu rehberdeki adımlar hakkında soru sorun. Sorular yayımlanmadan önce incelenir.
Herkese açık sorularda hesap bilgisi, erişim bilgisi veya özel dosya paylaşmayın. Bunlar için özel destek kanalını kullanın.
Sorular yükleniyor…
dosya.dev hesabınızda oturum açın ve sorunuzu sorun.