Google Drive API, bir File
oluşturduğunuzda veya güncellediğinizde dosya verilerini yüklemenize olanak tanır. Klasör gibi yalnızca meta veri dosyalarını oluşturma hakkında bilgi edinmek için Yalnızca meta veri dosyaları oluşturma bölümüne bakın.
Gerçekleştirebileceğiniz üç tür yükleme vardır:
Basit yükleme (
uploadType=media
): Meta veri sağlamadan küçük bir medya dosyasını (5 MB veya daha küçük) aktarmak için bu yükleme türünü kullanın. Basit bir yükleme yapmak için Basit yükleme yapma bölümünü inceleyin.Çok parçalı yükleme (
uploadType=multipart
): "Küçük bir dosyayı (5 MB veya daha küçük) ve dosyayı tanımlayan meta verileri tek bir istekte aktarmak için bu yükleme türünü kullanın. Çok parçalı bir yükleme gerçekleştirmek için Çok parçalı yükleme gerçekleştirme bölümüne bakın.Devam ettirilebilir yükleme (
uploadType=resumable
): Bu yükleme türünü, büyük (5 MB'tan büyük) dosyalar için ve mobil uygulamadan dosya oluşturmak gibi ağ kesintisi ihtimali yüksek olduğunda kullanın. Devam ettirilebilir yüklemeler, yükleme başına minimum bir HTTP isteği karşılığında küçük dosyalarda da çalıştıkları için çoğu uygulama için iyi bir seçenektir. Devam ettirilebilir bir yükleme gerçekleştirmek için Devam ettirilebilir yükleme gerçekleştirme bölümüne bakın.
Google API istemci kitaplıkları, bu yükleme türlerinden en az birini uygular. Her bir türün nasıl kullanılacağıyla ilgili ek ayrıntılar için istemci kitaplığı belgelerini inceleyin.
PATCH
ve PUT
kullanın
Hatırlatmak gerekirse PATCH
HTTP fiili, kısmi dosya kaynağı güncellemesini desteklerken PUT
HTTP fiili tam kaynak değiştirmeyi destekler. PUT
işlevinin, mevcut bir kaynağa yeni bir alan eklerken değişikliklere yol açabileceğini unutmayın.
Bir dosya kaynağı yüklerken aşağıdaki yönergeleri kullanın:
- Devam ettirilebilir bir yüklemenin ilk isteği veya basit ya da çok parçalı bir yüklemenin tek isteği için API referansında belgelenen HTTP fiilini kullanın.
- İstek başladıktan sonra, devam ettirilebilir yükleme için sonraki tüm istekler için
PUT
kullanın. Bu istekler, çağrılan yöntemden bağımsız olarak içerik yükler.
Basit bir yükleme işlemi gerçekleştirin
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 gerçekleştirileceği gösterilmektedir:
HTTP
uploadType=media
sorgu parametresiyle yöntemin /upload URI'sına birPOST
isteği oluşturun:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Dosya verilerini istek gövdesine ekleyin.
Şu HTTP üstbilgilerini ekleyin:
Content-Type
. Yüklenen nesnenin MIME medya türüne ayarlayın.Content-Length
. Yüklediğiniz bayt sayısını ayarlayın. Parçalı aktarım kodlaması kullanıyorsanız bu başlık 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 gerçekleştirdiğinizde, temel meta veriler oluşturulur ve dosyadan MIME türü veya modifiedTime
gibi bazı özellikler tahmin edilir. Küçük dosyalarınızın olduğu ve dosya meta verilerinin önemli olmadığı durumlarda basit bir yükleme kullanabilirsiniz.
Çok parçalı yükleme gerçekleştir
Çok parçalı yükleme isteği, meta verileri ve verileri aynı isteğe yüklemenize olanak tanır. Gönderdiğiniz veriler, bağlantı başarısız olması durumunda tamamen tekrar yüklenecek kadar küçükse bu seçeneği kullanın.
Çok parçalı bir yükleme gerçekleştirmek için uploadType=multipart
ile files.create
yöntemini kullanın.
Aşağıda, çok parçalı bir yüklemenin nasıl gerçekleştirileceği gösterilmektedir:
Java
Python
Node.js
PHP
.NET
HTTP
uploadType=multipart
sorgu parametresiyle yöntemin /upload URI'sına 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üne göre RFC 2387'ye göre biçimlendirin:
- Meta veriler. Meta veriler önce gelmeli ve
Content-Type
üst bilgisiapplication/json;
charset=UTF-8
olarak ayarlanmalıdır. Dosyanın meta verilerini JSON biçiminde ekleyin. - Medya. Medya ikinci sırada yer almalı ve herhangi bir MIME türünde
Content-Type
üstbilgisine sahip olmalıdır. Dosya verilerini medya bölümüne ekleyin.
Her bölümü, önünde iki kısa çizgi bulunan bir sınır dizesiyle tanımlayın. Ayrıca, son sınır dizesinden sonra iki kısa çizgi ekleyin.
- Meta veriler. Meta veriler önce gelmeli ve
Şu üst düzey HTTP üstbilgilerini ekleyin:
Content-Type
.multipart/related
değerine ayarlayın ve isteğin farklı kısımlarını tanımlamak için kullandığınız sınır dizesini ekleyin. Örnek:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. İstek gövdesindeki toplam bayt sayısına ayarlayın.
İsteği gönderin.
İlişkili veriler olmadan yalnızca meta veri bölümünü 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ı belirtmelidir. Örneğin, bir fotoğraf JPEG dosyası oluştururken meta verilerde "name": "photo.jpg"
gibi bir şey belirtebilirsiniz. files.get
öğesine yapılan sonraki çağrılar, başlangıçta name
alanında belirtilen uzantıyı içeren salt okunur fileExtension
özelliğini döndürür.
Devam ettirilebilir yükleme gerçekleştir
Devam ettirilebilir yükleme, bir iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemini devam ettirebilmenizi sağlar. Büyük dosya yüklemelerini baştan başlatmanıza gerek olmadığı için devam ettirilebilir yüklemeler, ağ hatası durumunda bant genişliği kullanımınızı da azaltabilir.
Devam ettirilebilir yüklemeler, dosya boyutlarınızın büyük ölçüde farklılık gösterdiği durumlarda veya istekler için sabit bir süre sınırı varsa (ör. mobil işletim sistemi arka plan görevleri ve belirli App Engine istekleri) kullanışlıdır. Yükleme ilerleme çubuğu göstermek istediğiniz durumlarda devam ettirilebilir yüklemeleri de kullanabilirsiniz.
Devam ettirilebilir bir yükleme birkaç üst düzey adımdan oluşur:
- İlk isteği gönderin ve devam ettirilebilir oturum URI'sını alın.
- Verileri yükleyin ve yükleme durumunu izleyin.
- (İsteğe bağlı) Yükleme kesintiye uğradıysa 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 parametresiyle yöntemin /upload URI'sına 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ıt,
200 OK
HTTP durum kodunu içerir. Ayrıca, devam ettirilebilir oturum URI'sını 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ükleyebilmek ve yükleme durumunu sorgulayabilmek için devam ettirilebilir oturum URI'sını kaydedin. Devam ettirilebilir bir oturum URI'sının süresi bir hafta sonra dolar.
Dosya için meta verileriniz varsa meta verileri istek gövdesine JSON biçiminde ekleyin. Aksi takdirde, isteğin gövde metnini boş bırakın.
Şu HTTP üstbilgilerini ekleyin:
X-Upload-Content-Type
. İsteğe bağlı. Sonraki isteklerde aktarılacak dosya verilerinin MIME türüne ayarlayın. Verilerin MIME türü meta verilerde veya bu üstbilgide belirtilmemişse nesneapplication/octet-stream.
olarak sunulurX-Upload-Content-Length
. İsteğe bağlı. Sonraki isteklerde aktarılacak dosya verilerinin bayt sayısını ayarlayın.Content-Type
. Dosya için meta verileriniz varsa gereklidir.application/json;
charset=UTF-8
olarak ayarlayın.Content-Length
. Parçalı aktarım kodlaması kullanmıyorsanız zorunludur. Bu ilk isteğin gövdesindeki bayt sayısına ayarlayın.
İsteği gönderin. Oturum başlatma isteği başarılı olursa yanıtta bir
200 OK HTTP
durum kodu görüntülenir. Buna ek olarak, yanıt devam ettirilebilir oturum URI'sını belirten birLocation
üst bilgisi içerir. Dosya verilerini yüklemek ve yükleme durumunu sorgulamak için devam ettirilebilir oturum URI'sını kullanın. Devam ettirilebilir bir oturum URI'sının süresi bir hafta sonra dolar.Devam ettirilebilir oturum URL'sini kopyalayıp kaydedin.
İçeriği yükleme bölümüne geçin.
İçeriği yükleyin
Devam ettirilebilir oturumu olan bir dosyayı iki şekilde yükleyebilirsiniz:
- Tek bir istekte içerik yükleme: Dosya tek bir istekte yüklenebiliyorsa, herhangi bir tek istek için sabit bir zaman sınırı yoksa veya yükleme ilerleme durumu 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ça halinde yükleyin: Tek bir istekte aktarılan veri miktarını azaltmanız gerekiyorsa bu yaklaşımı kullanın. Belirli App Engine isteği sınıflarında olduğu gibi, tek tek istekler için sabit bir süre sınırı varsa, aktarılan veri miktarını 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ı olur.
HTTP - tekli istek
- Devam ettirilebilir oturum URI'sı için bir
PUT
isteği oluşturun. - Dosya verilerini istek gövdesine ekleyin.
- Dosyadaki bayt sayısına ayarlanmış bir İçerik Uzunluğu HTTP üstbilgisi ekleyin.
- İsteği gönderin. Yükleme isteği kesilirse veya
5xx
yanıtı alırsanız Kesintiye uğrayan yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.
HTTP - birden çok istek
Devam ettirilebilir oturum URI'sı için bir
PUT
isteği oluşturun.Parçanın verilerini istek gövdesine ekleyin. Yüklemeyi tamamlayan son parça hariç, 256 KB (256 x 1.024 bayt) boyutundaki katlar halinde parçalar oluşturun. Yüklemenin verimli olması için parça boyutunu mümkün olduğunca büyük tutun.
Şu HTTP üstbilgilerini ekleyin:
Content-Length
. Geçerli yığındaki bayt sayısına ayarlayın.Content-Range
. Yüklediğiniz dosyadaki hangi baytları gösterecek şekilde ayarlayın. ÖrneğinContent-Range: bytes 0-524287/2000000
, 2.000.000 baytlık bir dosyaya ilk 524.288 baytı (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 bir yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.Dosyada kalan her parça için 1-4 arasındaki adımları tekrarlayın. Bir sonraki parçanın nereden başlatılacağını belirlemek için yanıttaki
Range
üst bilgisini kullanın. Sunucunun önceki istekte gönderilen tüm baytları aldığını varsaymayın.
Dosya yükleme işleminin 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 bir yüklemeyi devam ettirme
Yükleme isteği yanıtlanmadan önce 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'sına boş bir
PUT
isteği oluşturun.Dosyadaki mevcut konumun bilinmediğini belirtmek için bir
Content-Range
üst bilgisi ekleyin. Örneğin, toplam dosya uzunluğunuz 2.000.000 baytsaContent-Range
alanını*/2000000
olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanızContent-Range
özelliğini*/*
olarak ayarlayın.İsteği gönderin.
Yanıtı işleyin:
200 OK
veya201 Created
yanıtı, yüklemenin tamamlandığını ve başka bir işleme gerek olmadığını gösterir.308 Resume Incomplete
yanıtı, dosyayı yüklemeye devam etmeniz gerektiğini belirtir.404 Not Found
yanıtı, yükleme oturumunun sona erdiğini ve yüklemenin baştan başlatılması gerektiğini belirtir.
Bir
308 Resume Incomplete
yanıtı aldıysanız sunucunun hangi baytları aldığını belirlemek için yanıtınRange
üstbilgisini işleyin. YanıttaRange
üst bilgisi yoksa hiç bayt alınmamıştır. Örneğin,bytes=0-42
türündekiRange
üst bilgisi, dosyanın ilk 43 baytının alındığını ve yüklenecek bir sonraki parçanın 44 bayt ile başlayacağını belirtir.Yüklemeyi nerede devam ettireceğinizi öğrendiğinize göre, sonraki bayttan başlayarak dosyayı yüklemeye devam edebilirsiniz. Dosyanın hangi bölümünü gönderdiğinizi belirtmek için bir
Content-Range
üst bilgisi ekleyin. ÖrneğinContent-Range: bytes 43-1999999
, 44 ile 2.000.000 arasında bayt gönderdiğinizi belirtir.
Medya yükleme hatalarını işleme
Medya yüklerken hataları ele almak için aşağıdaki en iyi uygulamaları izleyin:
5xx
hataları için, bağlantı kesintileri nedeniyle başarısız olan yüklemeleri devam ettirin veya yeniden deneyin.5xx
hatalarının ele alınması hakkında daha fazla bilgi için 500, 502, 503, 504 hatalarına bakın.403 rate limit
hata varsa yüklemeyi tekrar deneyin.403 rate limit
hatalarının işlenmesi hakkında daha fazla bilgi için 403 hatası:rateLimitExceeded
bölümüne bakın.- Devam ettirilebilir yükleme sırasında oluşan
4xx
hataları (403
dahil) için yüklemeyi yeniden başlatın. Bu hatalar, yükleme oturumunun sona erdiğini 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 hiçbir işlem yapılmadığında dolar.
Google Dokümanlar türlerine aktar
Drive'da bir dosya oluşturduğunuzda bu dosyayı Google Dokümanlar veya E-Tablolar gibi bir Google Workspace dosya türüne dönüştürmek isteyebilirsiniz. Örneğin, bir dokümanı favori kelime işlemcinizden Google Dokümanlar'a dönüştürmek, bunların özelliklerinden yararlanmak isteyebilirsiniz.
Bir dosyayı belirli bir Google Workspace dosya türüne dönüştürmek için, dosyayı oluştururken Google Workspace mimeType
değerini belirtin.
Aşağıda, CSV dosyasının Google Workspace e-tablosuna nasıl dönüştürüleceği gösterilmektedir:
Java
Python
Node.js
PHP
.NET
Bir dönüşümün kullanılabilir olup olmadığını görmek için dosyayı oluşturmadan önce about
kaynağının importFormats
dizisini kontrol edin.
Desteklenen dönüşümler bu dizide dinamik olarak mevcuttur. Bazı yaygın içe aktarma biçimleri şunlardır:
En düşük | Alıcı |
---|---|
Microsoft Word, OpenDocument Metni, 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ı |
update
isteği sırasında bir Dokümanlar, E-Tablolar veya Slaytlar dosyasına medya
yükleyip dönüştürdüğünüzde,
dokümanın tüm içeriği değiştirilir.
Bir resmi Dokümanlar'a dönüştürdüğünüzde Drive, resmi metne dönüştürmek için Optik Karakter Tanıma (OCR) özelliğini kullanır. ocrLanguage
parametresinde geçerli BCP 47 dil kodunu belirterek OCR algoritmasının kalitesini iyileştirebilirsiniz. Çıkarılan metin, Dokümanda, yerleştirilen resmin yanında 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 istekleri, önceden oluşturulmuş bu kimlikleri kullanabilir. Dosya meta verilerinde id
alanını ayarlayın.
Önceden oluşturulmuş kimlikler oluşturmak için oluşturulacak kimlik sayısıyla birlikte files.generateIds
çağrısı yapı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 denemeler HTTP 409
hatası döndürür ve kopya dosyalar oluşturmaz.
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ızdan içerik aramak için files.list
ve fullText
alanını da kullanabilirsiniz. Daha fazla bilgi için Dosya ve klasör arama bölümüne bakın.
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, arama için dokümanları otomatik olarak dizine ekler. Uygulamanız diğer dosya türlerini (ör. çizim, video ve kısayollar) kaydediyorsa dosyanın contentHints.indexableText
alanına dizine eklenebilir metin sağlayarak bulunabilirliği artırabilirsiniz.
Dizine eklenebilir metin hakkında daha fazla bilgi için Dosya meta verilerini yönetme başlıklı makaleye bakın.