Devam Ettirilebilir Yükleme Gerçekleştirme

Bu sayfada, Street View Publish API'de nasıl devam ettirilebilir yükleme isteğinde bulunulacağı açıklanmaktadır. Bu protokol, bir iletişim hatası veri akışını kesintiye uğrattığında yükleme işlemini devam ettirmenizi sağlar. Bu seçeneği şu durumlarda kullanın:

  • Büyük dosyalar yüklüyorsanız
  • Ağ kesintisi veya başka bir aktarım hatası olasılığı yüksektir (ör. mobil uygulamadan dosya yüklüyorsanız).

Devam ettirilebilir yüklemeler, ağda kesinti olduğunda büyük dosya yüklemelerini baştan başlatmanız gerekmediğinden bant genişliği kullanımınızı da azaltabilir.

Küçük dosyaları güvenilir bir ağ bağlantısı üzerinden gönderiyorsanız basit bir yükleme yöntemini kullanabilirsiniz.

Devam ettirilebilir yükleme oturumu başlatma

uploadUrl aldıktan sonra devam ettirilebilir bir yükleme oturumu başlatabilirsiniz:

  1. uploadUrl için POST isteği oluşturun.

  2. Aşağıdaki HTTP üstbilgilerini ekleyin:

    • X-Goog-Upload-Protocol: resumable olarak ayarlandı.
    • X-Goog-Upload-Header-Content-Length: Sonraki isteklerde aktarılacak dosya verilerinin toplam bayt sayısına ayarlanır.
    • X-Goog-Upload-Header-Content-Type: Dosya verilerinin MIME türüne ayarlanır.
    • X-Goog-Upload-Command: start olarak ayarlanır.

  3. İsteği gönderin.

Örnek: Devam ettirilebilir yükleme oturumu başlatma

Aşağıdaki örnekte, yeni bir dosya yüklemek için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir. Bu durumda dosya bir resimdir ve dosyadaki toplam bayt sayısı 4200000'dir. İsteğin gövdesinin boş olduğunu, bu nedenle Content-Length başlığının 0 olarak ayarlandığını unutmayın.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Devam ettirilebilir oturum URL'sini kaydetme bölümünde, devam ettirilebilir yükleme oturumunu başlatma isteğinin yanıtının nasıl işlenmesi gerektiği açıklanmaktadır.

Devam ettirilebilir oturum URL'si kaydediliyor

Devam ettirilebilir bir yükleme oturumu başlatmak için gönderilen istek, sunucu tarafından aşağıdaki üstbilgi de dahil olmak üzere 200 OK HTTP durum koduyla yanıtlanır:

  • X-Goog-Upload-URL: Kalan tüm istekler aracılığıyla yüklemeyi tamamlamak için kullanılması gereken benzersiz bir URL.

Devam ettirilebilir yeniden gönderme URL'sini kopyalayıp kaydedin. Böylece sonraki istekler için kullanabilirsiniz.

Örnek: Devam ettirilebilir oturum URL'sini kaydetme

Aşağıdaki örnekte, devam ettirilebilir bir oturum URL'si ve boyut ayrıntı düzeyi şartı içeren bir yanıt gösterilmektedir.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Dosyayı yükleme

Devam ettirilebilir bir oturumla dosya yüklemenin iki yolu vardır:

  1. Tek bir istekte. Daha az istek gerektirdiği ve dolayısıyla daha iyi performans sağladığı için bu yaklaşım genellikle en iyisidir.
  2. Birden fazla parça halinde Aşağıdaki durumlarda bu yaklaşımı kullanın:
    • Tek bir istekte aktarılan veri miktarını azaltmanız gerekir. Tek tek istekler için sabit bir zaman sınırı olduğunda bunu yapmanız gerekebilir.
    • Yükleme ilerlemesini gösteren özelleştirilmiş bir gösterge sağlamanız gerekir.
    • Verileri ne zaman silmenin güvenli olduğunu bilmeniz gerekir.

Tek İstek

Dosyayı tek bir istekte yüklemek için:

  1. Devam ettirilebilir oturum URL'sine bir POST isteği oluşturun.
  2. Dosyanın verilerini istek gövdesine ekleyin.

  3. Aşağıdaki HTTP üstbilgilerini ekleyin:

    • Content-Length: Dosyadaki bayt sayısına ayarlanır.
    • X-Goog-Upload-Command: upload, finalize olarak ayarlanır.

  4. İsteği gönderin.

Yükleme isteği kesintiye uğrarsa veya 5xx yanıtı alırsanız Kesintiye uğrayan bir yüklemeyi devam ettirme başlıklı makaledeki prosedürü uygulayın.

Birden fazla büyük parça

Dosyayı birden fazla parça halinde yüklemek için:

  1. Devam ettirilebilir oturum URL'sine bir POST isteği oluşturun.
  2. Parçanın verilerini istek gövdesine ekleyin. Yüklemeyi tamamlayan son parça hariç, 2 MiB (meb)'nin katları olacak şekilde parçalar oluşturun. Yüklemenin verimli olması için parça boyutunu mümkün olduğunca büyük tutun.

  3. Aşağıdaki HTTP üstbilgilerini ekleyin:

    • Content-Length: Parçadaki bayt sayısına ayarlanır.
    • X-Goog-Upload-Command: upload olarak ayarlanır. Son parça için upload, finalize olarak ayarlayın.
    • X-Goog-Upload-Offset: Baytların yazılacağı ofset olarak ayarlanır. Baytların seri olarak yüklenmesi gerektiğini unutmayın.

  4. İ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.

  5. Dosyadaki kalan her bir parça için 1 ile 4 arasındaki adımları tekrarlayın.

Örnek: Dosyayı yükleme

Tekli İstek

Aşağıdaki örnekte, önceki adımda elde edilen devam ettirilebilir oturum URL'sini kullanarak 4.200.000 baytlık bir JPEG dosyasının tamamını tek bir istekle yüklemek için devam ettirilebilir bir istek gösterilmektedir:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

İstek başarılı olursa 200 OK HTTP durum kodu alırsınız.

Birden fazla büyük parça

Aşağıdaki örnekte, devam ettirilebilir oturum URL'si ve önceki adımda elde edilen boyut ayrıntı düzeyi kullanılarak 4.200.000 baytlık bir JPEG dosyasını birden çok parça halinde yüklemek için devam ettirilebilir bir istek gösterilmektedir. Bu örnekte 2097.000 baytlık bir yığın boyutu kullanılmaktadır. Bu, 2 MiB'ın (mebibayt) katlarıdır.

İlk parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

İkinci parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Son parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Kesintiye uğrayan yüklemeyi devam ettirme

Yükleme isteği kesintiye uğrarsa veya 200 dışında bir HTTP durum kodu alırsanız yüklemenin ne kadarının başarılı olduğunu öğrenmek için sunucuyu sorgulayın:

  1. Devam ettirilebilir oturum URL'sine bir POST isteği oluşturun.
  2. X-Goog-Upload-Command değerini query olarak ayarlayın.
  3. İsteği gönderin.

Sunucu, 200 OK HTTP durum kodu ve yüklemenin mevcut boyutuyla yanıt verir:

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Ardından, bu ofsetten itibaren yüklemeyi devam ettirebilirsiniz. Yükleme ve tamamlama komutunu birlikte göndermediğiniz sürece sunucu tarafından sağlanan ofset değerinden devam etmeniz gerekir. Bu durumda 0 ofsetinden de devam edebilirsiniz.

Sorgu komutunuzun HTTP yanıtında X-Goog-Upload-Status başlığı mevcutsa ve değer active değilse yükleme zaten sonlandırılmıştır.