Bu belgede, dosyaları adlandırma ve meta verilerle (ör. dizine eklenebilir metin ve küçük resimler) çalışma ile ilgili önemli noktalar ele alınmaktadır. Dosya ekleme ve alma hakkında bilgi edinmek için files kaynağına bakın.
Meta veriye genel bakış
Google Drive API'sinde files kaynağı, meta verileri temsil eder. Meta verilerin alt nesne olduğu API'lerin aksine, Drive API, files kaynağının tamamını meta veri olarak değerlendirir. Meta verilere doğrudan files kaynağındaki get veya list yöntemleriyle erişebilirsiniz.
Varsayılan olarak, get ve list yöntemleri yalnızca kısmi bir alan kümesi döndürür. Belirli verileri almak için isteğinizde fields sistem parametresini tanımlamanız gerekir. Atlanırsa sunucu, yönteme özgü alanların varsayılan bir alt kümesini döndürür. Örneğin, list yöntemi her dosya için yalnızca kind, id, name, mimeType ve resourceKey alanlarını döndürür. Farklı alanları döndürmek için Belirli alanları döndürme başlıklı makaleye bakın.
Ayrıca, meta veri görünürlüğü kullanıcının dosyadaki rolüne bağlıdır. permissions kaynağı, kullanıcının bir dosya veya klasörde yapmasına izin verilen işlemleri belirlemez. Bunun yerine, files kaynağında bir grup Boole capabilities alanı bulunur. Google Drive API, bu capabilities değerlerini dosya veya klasörle ilişkili permissions kaynağında türetir. Daha fazla bilgi için Dosya özelliklerini anlama başlıklı makaleyi inceleyin.
Drive API, iki kısıtlanmış meta veri kapsamı sunar: drive.metadata
ve drive.metadata.readonly. drive.metadata kapsamı, dosya meta verilerini görüntülemenize ve yönetmenize olanak tanırken drive.metadata.readonly salt okunurdur. Her ikisi de dosya içeriğine erişimi kesinlikle yasaklar. Daha fazla bilgi için Google Drive API kapsamlarını seçme başlıklı makaleyi inceleyin.
Son olarak, izinler ve kapsamlarla ilgili mantığınızı her zaman doğrulayın. Örneğin, bir kullanıcı tam izinlere sahip bir dosyanın sahibi olabilir ancak uygulamanızın yalnızca drive.metadata.readonly kapsamı varsa Drive API, dosyayı değiştirme veya indirme girişimlerini engeller.
Dosya adlarını ve uzantılarını belirtme
Uygulamalar, Google Drive API ile dosya eklerken name özelliğinde dosya uzantısını belirtmelidir. Örneğin, bir JPEG dosyası ekleme işlemi, meta verilerde "name": "cat.jpg" gibi bir değer belirtmelidir.
Sonraki GET yanıtları, name özelliğinde başlangıçta belirtilen uzantıyla doldurulmuş salt okunur fileExtension özelliğini içerebilir. Bir Google Drive kullanıcısı dosya indirme isteğinde bulunduğunda veya dosya senkronizasyon istemcisi üzerinden indirildiğinde Drive, ada göre tam bir dosya adı (uzantıyla birlikte) oluşturur. Uzantının eksik olduğu durumlarda Drive, dosyanın MIME türüne göre uzantıyı belirlemeye çalışır.
Dizin oluşturulabilir metni kaydetme
Drive, dosya türünü tanıdığında (metin belgeleri, PDF'ler, metin içeren resimler ve diğer yaygın türler dahil) belgeleri arama için otomatik olarak dizine ekler. Uygulamanız başka türde dosyalar (ör. çizimler, videolar ve kısayollar) kaydediyorsa dosyanın contentHints.indexableText alanına dizine eklenebilir metin sağlayarak keşfedilebilirliği artırabilirsiniz.
Dizine eklenebilir metin, HTML olarak dizine eklenir. Dizinlenebilir metin dizesini <section attribute="value1">Here's some text</section> olarak kaydederseniz "Burada biraz metin var" dizine eklenir ancak "değer1" eklenmez. Bu nedenle, XML'yi dizine eklenebilir metin olarak kaydetmek, HTML'yi kaydetmek kadar kullanışlı değildir.
indexableText değerini belirtirken aşağıdakileri de göz önünde bulundurun:
contentHints.indexableTextiçin boyut sınırı 128 KB'tır.- Kullanıcının aramasını beklediğiniz temel terimleri ve kavramları yakalayın.
- Dizin oluşturucu, metni sizin için verimli bir şekilde sıraladığından metni önem sırasına göre sıralamaya çalışmayın.
- Uygulamanız, her kaydetme işleminde dizine eklenebilir metni güncellemelidir.
- Metnin, dosyanın içeriği veya meta verileriyle ilgili olduğundan emin olun.
Bu son nokta bariz gibi görünebilir ancak önemlidir. Bir dosyanın arama sonuçlarında görünmesini sağlamak için sık aranan terimleri eklemek iyi bir fikir değildir. Bu durum kullanıcıları rahatsız edebilir ve hatta dosyayı silmeye teşvik edebilir.
Küçük resim yükleme
Drive, Google Dokümanlar, E-Tablolar ve Slaytlar gibi birçok yaygın dosya türü için otomatik olarak küçük resimler oluşturur. Küçük resimler, kullanıcının Drive dosyalarını daha iyi tanımlamasına yardımcı olur.
Drive'ın standart küçük resim oluşturamadığı dosya türleri için uygulamanız tarafından oluşturulan bir küçük resim sağlayabilirsiniz. Dosya oluşturma veya güncelleme sırasında, files kaynağında contentHints.thumbnail alanını ayarlayarak bir küçük resim yükleyin.
Özellikle:
contentHints.thumbnail.imagealanını URL ve dosya adı için güvenli Base64 kodlu resim olarak ayarlayın (bkz. RFC 4648 bölüm 5).contentHints.thumbnail.mimeTypealanını küçük resim için uygun MIME türüne ayarlayın.
Drive, dosyadan küçük resim oluşturabiliyorsa otomatik olarak oluşturulan küçük resmi kullanır ve yüklediğiniz küçük resimleri yok sayar. Küçük resim oluşturamıyorsa sizin sağladığınız küçük resmi kullanır.
Küçük resimler aşağıdaki kurallara uygun olmalıdır:
- PNG, GIF veya JPG biçimlerinde yüklenebilir.
- Önerilen genişlik 1.600 pikseldir.
- Minimum genişlik 220 pikseldir.
- Maksimum dosya boyutu 2 MB'tır.
- Bunlar, her kaydetme işleminde uygulamanız tarafından güncellenmelidir.
Daha fazla bilgi için files kaynağına bakın.
Küçük resimleri alma
Drive dosyaları için küçük resimler de dahil olmak üzere meta verileri alabilirsiniz.
Küçük resim bilgileri, files kaynağının thumbnailLink alanında yer alır.
Belirli bir küçük resmi döndürme
Aşağıdaki kod örneğinde, belirli bir dosyanın thumbnailLink meta verilerini döndürmek için sorgu parametresi olarak birden fazla alan içeren bir get yöntemi isteği gösterilmektedir. Daha fazla bilgi için Bir dosya için belirli alanları döndürme başlıklı makaleyi inceleyin.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID yerine, bulmak istediğiniz dosyanın fileId değerini girin.
İstek, varsa dosyanın küçük resmine yönelik kısa ömürlü bir URL döndürür.
Bağlantı genellikle birkaç saat geçerli olur. Bu alan yalnızca istekte bulunan uygulama dosyanın içeriğine erişebildiğinde doldurulur. Dosya herkese açık olarak paylaşılmıyorsa thumbnailLink içinde döndürülen URL, kimlik bilgileriyle yapılan bir istek kullanılarak getirilmelidir.
Küçük resim listesi döndürme
Aşağıdaki kod örneğinde, bir dosya listesinin thumbnailLink meta verilerini döndürmek için sorgu parametresi olarak birden fazla alan içeren bir list yöntemi isteği gösterilmektedir. Daha fazla bilgi için Dosya ve klasör arama başlıklı makaleyi inceleyin.
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
Arama sonuçlarını belirli bir dosya türüyle sınırlamak için MIME türünü ayarlayan bir sorgu dizesi uygulayın. Örneğin, aşağıdaki kod örneğinde listenin Google E-Tablolar dosyalarıyla nasıl sınırlandırılacağı gösterilmektedir. MIME türleri hakkında daha fazla bilgi için Google Workspace ve Google Drive'da desteklenen MIME türleri başlıklı makaleyi inceleyin.
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)