Google Drive API, File
oluştururken veya güncellerken dosya verilerini yüklemenize olanak tanır. Klasör gibi yalnızca meta veri içeren dosya oluşturma hakkında bilgi edinmek için Yalnızca meta veri içeren dosyalar oluşturma başlıklı makaleyi inceleyin.
Üç tür yükleme yapabilirsiniz:
Basit yükleme (
uploadType=media
): Meta veri sağlamadan küçük bir medya dosyasını (5 MB veya daha az) aktarmak için bu yükleme türünü kullanın. Basit bir yükleme yapmak için Basit yükleme yapma başlıklı makaleyi inceleyin.Çok parçalı yükleme (
uploadType=multipart
): "Küçük bir dosyayı (5 MB veya daha az) dosyayı açıklayan meta verilerle birlikte tek bir istekle aktarmak için bu yükleme türünü kullanın. Çok parçalı yükleme yapmak için Çok parçalı yükleme yapma başlıklı makaleyi inceleyin.Devam ettirilebilir yükleme (
uploadType=resumable
): Büyük dosyalar (5 MB'tan büyük) ve ağ kesintisi olasılığının yüksek olduğu durumlarda (ör. mobil uygulamadan dosya oluştururken) bu yükleme türünü kullanın. Devam ettirilebilir yüklemeler, küçük dosyalar için de kullanılabilir. Bu yükleme türü, yükleme başına ek bir HTTP isteği maliyeti ile çalışır. Bu nedenle, çoğu uygulama için iyi bir seçimdir. Devam ettirilebilir yükleme yapmak için Devam ettirilebilir yükleme yapma başlıklı makaleyi inceleyin.
Google API istemci kitaplıkları, bu yükleme türlerinden en az birini uygular. Türlerin her birinin nasıl kullanılacağıyla ilgili ek ayrıntılar için istemci kitaplığı dokümanlarına bakın.
PATCH
ve PUT
kullanımı
PATCH
HTTP fiili, kısmi dosya kaynağı güncellemesini desteklerken PUT
HTTP fiili, tam kaynak değişimini destekler. PUT
, mevcut bir kaynağa yeni bir alan eklerken önemli değişikliklere neden olabileceğini unutmayın.
Dosya kaynağı yüklerken aşağıdaki yönergeleri kullanın:
- Devam ettirilebilir yüklemenin ilk isteği veya basit ya da çok bölümlü yüklemenin tek isteği için API referansında belirtilen HTTP fiili kullanın.
- İstek başladıktan sonra devam ettirilebilir yükleme için sonraki tüm istekler için
PUT
değerini kullanın. Bu istekler, çağrılan yönteme bakılmaksızın içerik yükler.
Basit bir yükleme yapma
Basit bir yükleme yapmak için uploadType=media
ile files.create
yöntemini kullanın.
Aşağıda basit bir yüklemenin nasıl yapılacağı gösterilmektedir:
HTTP
uploadType=media
sorgu parametresini kullanarak yöntemin /upload URI'sine birPOST
isteği oluşturun:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Dosyanın verilerini istek gövdesine ekleyin.
Aşağıdaki HTTP üst bilgilerini ekleyin:
Content-Type
. Yüklenen nesnenin MIME medya türüne ayarlanır.Content-Length
. Yüklediğiniz bayt sayısına ayarlayın. Parçalara ayrılmış aktarım kodlaması kullanıyorsanız bu üstbilgi gerekli değildir.
İsteği gönderin. İstek başarılı olursa sunucu, dosyanın meta verileriyle birlikte
HTTP 200 OK
durum kodunu döndürür. {HTTP}
Basit bir yükleme yaptığınızda temel meta veriler oluşturulur ve MIME türü veya modifiedTime
gibi bazı özellikler dosyadan çıkarılır. Küçük dosyalarınız varsa ve dosya meta verileri önemli değilse basit yükleme yöntemini kullanabilirsiniz.
Çok parçalı yükleme gerçekleştirme
Çok parçalı yükleme isteği, meta verileri ve verileri aynı istekle yüklemenize olanak tanır. Gönderdiğiniz veriler, bağlantı başarısız olursa tekrar yüklenebilecek kadar küçükse bu seçeneği kullanın.
Çok parçalı yükleme yapmak için uploadType=multipart
ile files.create
yöntemini kullanın.
Aşağıda, çok parçalı yüklemenin nasıl yapılacağı gösterilmektedir:
Java
Python
Node.js
PHP
.NET
HTTP
uploadType=multipart
sorgu parametresini kullanarak yöntemin /upload URI'sine birPOST
isteği oluşturun:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
İsteğin gövdesini oluşturun. Gövdeyi, iki bölümden oluşan çok parçalı/ilgili içerik türü RFC 2387'ye göre biçimlendirin:
- Meta veriler. Meta veriler önce gelmelidir ve
Content-Type
application/json;
charset=UTF-8
olarak ayarlanmış birapplication/json;
başlığı olmalıdır. Dosyanın meta verilerini JSON biçiminde ekleyin. - Medya. Medya ikinci sırada gelmelidir ve herhangi bir MIME türünde bir
Content-Type
üstbilgisi içermelidir. Dosyanın verilerini medya bölümüne ekleyin.
Her bölümü, iki kısa çizginin önüne eklenmiş bir sınır dizesiyle tanımlayın. Ayrıca, son sınır dizesi sonrasında iki kısa çizgi ekleyin.
- Meta veriler. Meta veriler önce gelmelidir ve
Aşağıdaki üst düzey HTTP üst bilgilerini ekleyin:
Content-Type
.multipart/related
olarak ayarlayın ve isteğin farklı bölümlerini tanımlamak için kullandığınız sınır dizesini ekleyin. Örneğin:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. İstek gövdesinde bulunan toplam bayt sayısına ayarlanır.
İsteği gönderin.
Yalnızca meta veri bölümünü, ilişkili veriler olmadan oluşturmak veya güncellemek için standart kaynak uç noktasına bir POST
veya PATCH
isteği gönderin:
https://www.googleapis.com/drive/v3/files
İstek başarılı olursa sunucu, dosyanın meta verileriyle birlikte HTTP 200 OK
durum kodunu döndürür.
Dosya oluştururken dosyanın name
alanında bir dosya uzantısı belirtmelidirler. Örneğin, bir fotoğraf JPEG dosyası oluştururken meta verilerde "name": "photo.jpg"
gibi bir şey belirtebilirsiniz. files.get
için yapılan sonraki çağrılar, name
alanında orijinal olarak belirtilen uzantıyı içeren salt okunur fileExtension
mülkünü döndürür.
Devam ettirilebilir yükleme yapma
Devam ettirilebilir yükleme, iletişim hatası nedeniyle veri akışı kesintiye uğradıktan sonra yükleme işlemini devam ettirmenize olanak tanır. Büyük dosya yüklemelerini baştan başlatmanız gerekmediğinden, devam ettirilebilir yüklemeler ağda kesinti olması durumunda bant genişliği kullanımınızı da azaltabilir.
Devam ettirilebilir yüklemeler, dosya boyutlarınız büyük ölçüde değişebileceğinde veya istekler için sabit bir zaman sınırı olduğunda (ör. mobil işletim sistemi arka plan görevleri ve belirli App Engine istekleri) kullanışlıdır. Devam ettirilebilir yüklemeleri, yükleme ilerleme çubuğunu göstermek istediğiniz durumlarda da kullanabilirsiniz.
Devam ettirilebilir yükleme, birkaç genel adımdan oluşur:
- İlk isteği gönderin ve devam ettirilebilir oturum URI'sini alın.
- Verileri yükleyin ve yükleme durumunu izleyin.
- (isteğe bağlı) Yükleme kesintiye uğrarsa yüklemeyi devam ettirin.
İlk isteği gönderme
Devam ettirilebilir bir yükleme başlatmak için uploadType=resumable
ile files.create
yöntemini kullanın.
HTTP
uploadType=resumable
sorgu parametresini kullanarak yöntemin /upload URI'sine birPOST
isteği oluşturun:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Başlatma isteği başarılı olursa yanıtta
200 OK
HTTP durum kodu yer alır. Ayrıca, devam ettirilebilir oturum URI'sini belirten birLocation
üst bilgisi içerir:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Dosya verilerini yükleyip yükleme durumunu sorgulayabilmek için devam ettirilebilir oturum URI'sini kaydedin. Devam ettirilebilir oturum URI'sinin süresi bir hafta sonra dolar.
Dosyanın meta verileri varsa meta verileri JSON biçiminde istek gövdesine ekleyin. Aksi takdirde istek metnini boş bırakın.
Aşağıdaki HTTP üst bilgilerini ekleyin:
X-Upload-Content-Type
. İsteğe bağlı. Sonraki isteklerde aktarılan dosya verilerinin MIME türüne ayarlanır. Verilerin MIME türü meta verilerde veya bu başlık aracılığıyla belirtilmezse nesneapplication/octet-stream.
olarak yayınlanır.X-Upload-Content-Length
. İsteğe bağlı. Sonraki isteklerde aktarılan dosya verilerinin bayt sayısına ayarlanır.Content-Type
. Dosyanın meta verileri varsa gereklidir.application/json;
charset=UTF-8
olarak ayarlayın.Content-Length
. Parçalara ayrılmış aktarım kodlaması kullanmıyorsanız gereklidir. Bu ilk istekteki gövdedeki bayt sayısına ayarlanır.
İsteği gönderin. Oturum başlatma isteği başarılı olursa yanıtta
200 OK HTTP
durum kodu bulunur. Ayrıca yanıt, devam ettirilebilir oturum URI'sini belirten birLocation
üstbilgisi içerir. Dosya verilerini yüklemek ve yükleme durumunu sorgulamak için devam ettirilebilir oturum URI'sini kullanın. Devam ettirilebilir oturum URI'sinin süresi bir hafta sonra dolar.Devam ettirilebilir oturum URL'sini kopyalayıp kaydedin.
İçeriği yükle'ye devam edin.
İçeriği yükleme
Devam ettirilebilir oturumla dosya yüklemenin iki yolu vardır:
- İçeriği tek bir istekle yükleme: Dosya tek bir istekle yüklenebiliyorsa, tek bir istek için sabit bir zaman sınırı yoksa veya yükleme ilerleme göstergesi göstermeniz gerekmiyorsa bu yaklaşımı kullanın. Daha az istek gerektirdiği ve daha iyi performans sağladığı için bu yaklaşım en iyisidir.
İçeriği birden fazla parçaya ayırarak yükleyin: Tek bir istekte aktarılan veri miktarını azaltmanız gerekiyorsa bu yaklaşımı kullanın. Belirli App Engine istek sınıflarında olduğu gibi, bağımsız istekler için sabit bir zaman sınırı olduğunda aktarılan verileri azaltmanız gerekebilir. Bu yaklaşım, yükleme ilerleme durumunu göstermek için özelleştirilmiş bir gösterge sağlamanız gerektiğinde de yararlıdır.
HTTP - tek istek
- Devam ettirilebilir oturum URI'sine bir
PUT
isteği oluşturun. - Dosyanın verilerini istek gövdesine ekleyin.
- Dosyadaki bayt sayısına ayarlanmış bir Content-Length HTTP üstbilgisi ekleyin.
- İsteği gönderin. Yükleme isteği kesintiye uğrarsa veya
5xx
yanıtı alırsanız Devam eden bir yüklemeyi devam ettirme başlıklı makaledeki prosedürü uygulayın.
HTTP - birden çok istek
Devam ettirilebilir oturum URI'sine bir
PUT
isteği oluşturun.Parçanın verilerini istek gövdesine ekleyin. Yüklemeyi tamamlayan son parça hariç, 256 KB'lık (256 x 1024 bayt) çoklu parçalar oluşturun. Yüklemenin verimli olması için parça boyutunu mümkün olduğunca büyük tutun.
Aşağıdaki HTTP üst bilgilerini ekleyin:
Content-Length
. Geçerli parçadaki bayt sayısına ayarlanır.Content-Range
: Yüklediğiniz dosyanın hangi baytlarını göstereceğini ayarlayın. Örneğin,Content-Range: bytes 0-524287/2000000
, 2.000.000 baytlık bir dosyanın ilk 524.288 baytını (256 x 1024 x 2) yüklediğinizi gösterir.
İsteği gönderin ve yanıtı işleyin. Yükleme isteği kesintiye uğrarsa veya
5xx
yanıtı alırsanız Kesintiye uğrayan yüklemeyi devam ettirme başlıklı makaledeki prosedürü uygulayın.Dosyada kalan her bir parça için 1 ile 4 arasındaki adımları tekrarlayın. Bir sonraki parçanın nereden başlayacağını belirlemek için yanıttaki
Range
başlığını kullanın. Sunucunun önceki istekte gönderilen tüm baytları aldığını varsaymayın.
Dosya yüklemenin tamamı tamamlandığında, kaynakla ilişkili tüm meta verilerle birlikte bir 200 OK
veya 201 Created
yanıtı alırsınız.
Kesintiye uğrayan yüklemeyi devam ettirme
Yükleme isteği yanıt almadan sonlandırılırsa veya 503
Service Unavailable
yanıtı alırsanız kesintiye uğrayan yüklemeyi devam ettirmeniz gerekir.
HTTP
Yükleme durumunu istemek için devam ettirilebilir oturum URI'sine boş bir
PUT
isteği oluşturun.Dosyadaki mevcut konumun bilinmediğini belirtmek için bir
Content-Range
üstbilgisi ekleyin. Örneğin, toplam dosya uzunluğunuz 2.000.000 bayt iseContent-Range
değerini*/2000000
olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanızContent-Range
değerini*/*
olarak ayarlayın.İsteği gönderin.
Yanıtı işleme:
200 OK
veya201 Created
yanıtı, yüklemenin tamamlandığını ve başka bir işlem yapılmasına gerek olmadığını gösterir.308 Resume Incomplete
yanıtı, dosyayı yüklemeye devam etmeniz gerektiğini gösterir.404 Not Found
yanıtı, yükleme oturumunun süresinin dolduğunu ve yüklemenin baştan başlatılması gerektiğini gösterir.
308 Resume Incomplete
yanıtı aldıysanız sunucunun hangi baytları aldığını belirlemek için yanıtınRange
üst bilgisini işleyin. YanıttaRange
üst bilgisi yoksa hiçbir bayt alınmamıştır. Örneğin,bytes=0-42
değerine sahip birRange
başlığı, dosyanın ilk 43 baytının alındığını ve yüklenecek bir sonraki parçanın 44. baytla başlayacağını gösterir.Yüklemeyi nereden devam ettireceğinizi öğrendiğinize göre, bir sonraki bayttan başlayarak dosyayı yüklemeye devam edin. Dosyanın hangi bölümünü gönderdiğinizi belirtmek için bir
Content-Range
başlığı ekleyin. Örneğin,Content-Range: bytes 43-1999999
44 ila 2.000.000 bayt gönderdiğinizi gösterir.
Medya yükleme hatalarını giderme
Medya yüklerken hataları ele almak için aşağıdaki en iyi uygulamaları uygulayın:
5xx
hataları için bağlantı kesintileri nedeniyle başarısız olan yüklemeleri devam ettirin veya yeniden deneyin.5xx
hatalarını ele alma hakkında daha fazla bilgi için 500, 502, 503, 504 hataları başlıklı makaleyi inceleyin.403 rate limit
hataları için yüklemeyi tekrar deneyin.403 rate limit
hatalarını işleme hakkında daha fazla bilgi için 403 hatası:rateLimitExceeded
başlıklı makaleyi inceleyin.- Devam ettirilebilir yükleme sırasında
4xx
hataları (403
dahil) oluşursa yüklemeyi yeniden başlatın. Bu hatalar, yükleme oturumunun süresinin dolduğunu ve yeni bir oturum URI'si isteyerek yeniden başlatılması gerektiğini gösterir. Yükleme oturumlarının süresi de bir hafta boyunca işlem yapılmadığında dolar.
Google Dokümanlar'a aktarma türleri
Drive'da oluşturduğunuz dosyaları Google Dokümanlar veya E-Tablolar gibi Google Workspace dosya türlerine dönüştürebilirsiniz. Örneğin, favori kelime işlemcinizdeki bir dokümanı, özelliklerinden yararlanmak için Dokümanlar'a dönüştürmek isteyebilirsiniz.
Bir dosyayı belirli bir Google Workspace dosya türüne dönüştürmek için dosyayı oluştururken Google Workspace mimeType
dosya türünü belirtin.
Aşağıda, bir CSV dosyasının Google Workspace e-tablosuna nasıl dönüştürüleceği gösterilmektedir:
Java
Python
Node.js
PHP
.NET
Dönüşümün kullanılıp kullanılamayacağını görmek için dosyayı oluşturmadan önce about
kaynağının importFormats
dizisini kontrol edin.
Desteklenen dönüşümler bu dizi içinde dinamik olarak kullanılabilir. Sık kullanılan bazı içe aktarma biçimleri şunlardır:
Nereden | Alıcı |
---|---|
Microsoft Word, OpenDocument Metin, HTML, RTF, düz metin | Google Dokümanlar |
Microsoft Excel, OpenDocument E-Tablosu, CSV, TSV, düz metin | Google E-Tablolar |
Microsoft PowerPoint, OpenDocument Sunusu | Google Slaytlar |
JPEG, PNG, GIF, BMP, PDF | Google Dokümanlar (resmi bir dokümana yerleştirir) |
Düz metin (özel MIME türü), JSON | Google Apps Komut Dosyası |
Dokümanlar, E-Tablolar veya Slaytlar dosyasına yönelik bir update
isteği sırasında medya yükleyip dönüştürdüğünüzde, dokümanın tüm içeriği değiştirilir.
Drive, bir resmi Dokümanlar dosyasına dönüştürdüğünüzde optik karakter tanıma (OCR) özelliğini kullanarak resmi metne dönüştürür. ocrLanguage
parametresinde geçerli BCP 47 dil kodunu belirterek OCR algoritmasının kalitesini artırabilirsiniz. Ayıklanan metin, yerleştirilmiş resmin yanında dokümanda görünür.
Dosya yüklemek için önceden oluşturulmuş bir kimlik kullanma
Drive API, kaynak yüklemek ve oluşturmak için kullanılan önceden oluşturulmuş dosya kimliklerinin listesini almanıza olanak tanır. Yükleme ve dosya oluşturma isteklerinde bu önceden oluşturulmuş kimlikler kullanılabilir. Dosya meta verilerinde id
alanını ayarlayın.
Önceden oluşturulmuş kimlikler oluşturmak için oluşturulacak kimlik sayısını belirterek files.generateIds
işlevini çağırın.
Belirsiz bir sunucu hatası veya zaman aşımı varsa yüklemeleri önceden oluşturulmuş kimliklerle güvenle yeniden deneyebilirsiniz. Dosya başarıyla oluşturulduysa sonraki yeniden denemelerde HTTP 409
hatası döndürülür ve yinelenen dosya oluşturulmaz.
Bilinmeyen dosya türleri için dizine eklenebilir metin tanımlama
Kullanıcılar doküman içeriğini bulmak için Drive kullanıcı arayüzünü kullanabilir. Uygulamanızdaki içerikleri aramak için files.list
ve fullText
alanını da kullanabilirsiniz. Daha fazla bilgi için Dosya ve klasör arama başlıklı makaleyi inceleyin.
Drive, metin dokümanları, PDF'ler, metin içeren resimler ve diğer yaygın türler dahil olmak üzere dosya türünü tanıdığında dokümanları arama için otomatik olarak dizine ekler. Uygulamanız başka dosya türleri (ör. çizimler, videolar ve kısayollar) kaydediyorsa dosyanın contentHints.indexableText
alanına dizine eklenebilir metin ekleyerek keşfedilebilirliği artırabilirsiniz.
Dizine eklenebilir metin hakkında daha fazla bilgi için Dosya meta verilerini yönetme başlıklı makaleyi inceleyin.