REST API ile klasör ve dosyaları listeleyin

Okuma izinli anahtarla GET /api/files çağırın. Tek çalışma alanı veya klasörde sayfaları izleyin. Erişim, kilit, gizli içerik ve izin kapsamı retlerini yorumlayın.

Son inceleme

Ekran görüntülerinde İngilizce arayüz gösterilir.

Tek çalışma alanı konumunda görünen klasör ve dosyaları listelemek için GET https://api.dosya.dev/api/files kullanın. İstek üstveri, gezinti yolu, izinler ve dosya sayfalaması döndürür. Dosya baytlarını döndürmez, paylaşım bağlantısı oluşturmaz.

Erişim bilgisi ve izin gereksinimleri

Protokoller altında REST API izni olan Salt okunur veya Tam erişim API anahtarı oluşturun. Entegrasyon başka çalışma alanlarını listelememeliyse hedef çalışma alanıyla sınırlayın. Normal klasöre bağlı API anahtarları REST üzerinde reddedilir. Bu uç noktada kök klasör seçmeden çalışma alanıyla sınırlayın.

Anahtar kendisini oluşturan hesabın erişimini daraltır. Hesap yine çalışma alanına üye olmalı, rolünde access_files bulunmalıdır. Liste dönmeden önce klasör sınırı, gizli klasör kuralları, tam kilitler ve çalışma alanı üyeliği denetlenir.

Yalnızca yükleme anahtar bu GET uç noktasını çağıramaz. Ret mesajı işlemi tam adıyla belirtir: This credential's scope is 'upload' and cannot perform GET /api/files.

Çalışma alanı kimliği ve okuma anahtarından sayfalı üstveriye ve erişim sınırı kontrollerine uzanan REST listeleme akışı.
Bilinen bir çalışma alanı kökünü listeleyip sayfaları izleyin. Kısıtlı veya gizli içeriğin yanıtta görünmediğini doğrulayın. Ekran görüntüsünü tam boyutta açın.

Adımlar

Gizli anahtarı özel olarak ayarlayın. GET /api/workspaces yanıtından gelen çalışma alanı kimliğini kullanın:

read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
export DOSYA_WORKSPACE_ID='ws_REPLACE_ME'

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' \
  --data-urlencode 'sort=name' \
  --data-urlencode 'dir=asc' \
  -o files-page-1.json

python3 -m json.tool files-page-1.json

workspace_id zorunludur. Eksikse workspace_id is required döner. folder_id yoksa çalışma alanı kökü listelenir. Hesap bir klasörle sınırlıysa bunun yerine üyenin sınırlandırıldığı kök listelenir.

Başarılı JSON şunları içerir:

  • folders: mevcut konumdaki alt klasörlerin üstverisi.
  • files: dosya üstverisinin mevcut sayfası. Sonraki dosya yollarında kullanılan kimlikler dahildir.
  • breadcrumbs: alt klasör listelenirken kökten mevcut klasöre gezinti yolu etiketleri.
  • workspace_id ve çözümlenen folder_id.
  • can_lock, can_hide ve folder_view_only: çağıranın mevcut rolü ve klasör durumuna göre.
  • pagination.page, per_page, total_files ve total_pages.

Klasörler ve dosyalar ayrı dizilerdir. total_files ve total_pages alt klasör sayısını değil dosya sayfasını tanımlar.

REST ile klasör ve dosya üstverisi listelemeye uygun Salt okunur seçeneği bulunan dosya.dev API anahtarı izin seçicisi.
**Salt okunur** anahtar listeleme için yeterlidir. Aynı erişim bilgisiyle yükleme, taşıma, paylaşma ve silmeyi engeller. Ekran görüntüsünü tam boyutta açın.

Alt klasörü listeleme veya ada göre süzme

Bir klasörün doğrudan alt öğelerini listelemek için bilinen klasör kimliğini gönderin:

DOSYA_FOLDER_ID='fld_REPLACE_ME'
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 "folder_id=$DOSYA_FOLDER_ID" \
  --data-urlencode 'q=invoice' \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100'

q baştaki ve sondaki boşluklardan arındırılır. Adlarla büyük/küçük harfe duyarsız biçimde eşleştirilir. Özel joker karakterler ham SQL deseni değil arama metni sayılır. Klasörle sınırlı üye izinli alt ağaç dışında klasör belirtirse HTTP 403 ile This folder is outside the folder you're confined to alır.

Desteklenen sıralama anahtarları: name, size, created, modified, taken, type, extension, version, uploader, region, origin, shares ve comments. Yalın anahtarla dir=asc veya dir=desc kullanın. newest, oldest, largest ve smallest gibi eski değerler de kabul edilir. Tanınmayan değerde güvenli varsayılan kullanılır: en yeni öğe önce gelir.

Tüm dosya sayfalarını alın

Varsayılan sayfa boyutu 100 olur. per_page, 10–500 aralığına çekilir. page 1 ile başlar. Dönen sayfa pagination.total_pages değerine ulaşana kadar devam edin:

import json, os, urllib.parse, urllib.request

base = 'https://api.dosya.dev/api/files'
workspace = os.environ['DOSYA_WORKSPACE_ID']
key = os.environ['DOSYA_API_KEY']
page = 1

while True:
    query = urllib.parse.urlencode({
        'workspace_id': workspace,
        'page': page,
        'per_page': 500,
        'sort': 'name',
        'dir': 'asc',
    })
    req = urllib.request.Request(base + '?' + query,
        headers={'Authorization': 'Bearer ' + key})
    with urllib.request.urlopen(req) as response:
        body = json.load(response)
    for item in body['files']:
        print(item['id'], item['name'], item['size_bytes'])
    if page >= body['pagination']['total_pages']:
        break
    page += 1

Konum tabanlı sayfalar arasında dosyalar değişebilir. Tutarlı dışa aktarma için eşzamanlı ad değiştirme, yükleme ve silmeden kaçının. Yinelenen satırları dosya kimliğine göre kaldırın.

Erişim ve kilit yanıtlarını yorumlayın

YanıtAnlamı ve sonraki adım
401, Not authenticated veya geçersiz anahtar metniTam taşıyıcı belirteci yeniden sağlayın. Geçerlilik süresini veya geçersiz kılınmayı kontrol edin.
403, This API key is not permitted to use the api surfaceREST API içeren protokol seçimiyle anahtar oluşturun.
403, Not a member of this workspaceÇalışma alanı kimliğini doğrulayıp üyeliği yeniden sağlayın. Anahtar üyelik veremez.
403, You don't have access to the files pageMevcut rolde access_files yoktur. Çalışma alanı yöneticisinden ayarlamasını isteyin.
error: "folder_locked" ve lock_mode: "full_lock" içeren 403Yetkili akışla klasör kilidini açın. Entegrasyon kilitli klasör destekliyorsa mevcut ut belirtecini sağlayın.
404, Folder not foundBu istek sahibi açısından klasör yoktur. Gizli klasör veya gizli üst klasördeki klasör de olabilir. Yanıttan gizli içerik sonucu çıkarmayın.

Çağıranın gizli içerik yönetme izni yoksa gizli dosya ve klasörler normal sonuçlardan çıkarılır. view_only klasör listelenebilir. Yanıtta folder_view_only: true ayarlanır. Böylece istemci indirme işlemlerini gizleyebilir.

Beklenen sonuç

Her istek HTTP 200 ile erişim bilgisi sahibinin istenen konumda görebildiği klasör ve dosyaları döndürür. pagination.total_pages izlenerek bayt indirmeden veya çalışma alanını değiştirmeden erişilebilir dosyalar alınır.

İlgili rehberler

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.

    Yeniden denemeden önce sonucu kontrol edin

    Bir işlemi yeniden kontrol etmeniz gerektiğinde bu rehberlerden yararlanın.