Devam Ettirilebilir Yükleme Gerçekleştirme

Bu sayfada, Street View Yayınlama API'sinde nasıl devam ettirilebilir yükleme isteği gönderileceği açıklanmaktadır. Bu protokol, iletişim hatası nedeniyle veri akışı kesintiye uğradıktan sonra yükleme işlemini devam ettirmenize olanak tanır. 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.

Güvenilir bir ağ bağlantısı üzerinden küçük dosyalar gönderiyorsanız bunun yerine basit bir yükleme 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 ayarlanır.
    • 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 üstbilgisinin 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, devam ettirilebilir yükleme oturumunu başlatma isteğinin yanıtının nasıl ele alınacağını açıklar.

Devam ettirilebilir oturum URL'sini kaydetme

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: Yüklemeyi kalan tüm isteklerle 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 oturum URL'si ve boyut ayrıntı düzeyi koşulu 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 oturumla dosya yüklemenin iki yolu vardır:

  1. Tek bir istekte. Bu yaklaşım, daha az istek gerektirdiği ve dolayısıyla daha iyi performans sağladığı için 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 ilerleme durumunu gösteren özelleştirilmiş bir gösterge sağlamanız gerekir.
    • Verileri ne zaman silmenin güvenli olduğunu bilmeniz gerekir.
Tek İstekBirden fazla büyük parça

Dosyayı tek bir istekle 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.

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 kesintiye uğrayan 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

Tek İstekBirden fazla büyük parça

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.

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, 2 MiB'nin (meb) katı olan 2097000 baytlık bir parça boyutu kullanılmaktadı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 olmayan 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ığı varsa ve değer active değilse yükleme zaten sonlandırılmıştır.