Devam Ettirilebilir Yükleme Gerçekleştirme

Bu sayfada, Street View Publish API'de devam ettirilebilir yükleme isteğinin nasıl yapılacağı açıklanmaktadır. Bu protokol, bir iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemini devam ettirmenize olanak tanır. Bu seçeneği aşağıdaki durumlarda kullanın:

  • Büyük dosyalar yüklüyorsunuz.
  • Ağ kesintisi veya başka bir iletim hatası olasılığı yüksektir (örneğin, mobil uygulamadan dosya yüklüyorsanız).

Devam ettirilebilir yüklemeler, büyük dosya yüklemelerini baştan baştan yeniden başlatmak zorunda kalmadığınızdan, ağ hatası olduğunda 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 yükleme seçeneğini kullanabilirsiniz.

Devam ettirilebilir yükleme oturumu başlatma

uploadUrl edindikten sonra, devam ettirilebilir bir yükleme oturumu başlatabilirsiniz:

  1. uploadUrl için bir 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ını belirtir.
    • X-Goog-Upload-Header-Content-Type: Dosya verilerinin MIME türüne ayarlanır.
    • X-Goog-Upload-Command: start olarak ayarlandı.

  3. İsteği gönderin.

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

Aşağıdaki örnekte, yeni 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ı 4.200.000'dur. İsteğin gövdesinin boş olduğunu ve 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'sinin kaydedilmesi, devam ettirilebilir yükleme oturumunu başlatma isteğine verilen yanıtın nasıl ele alınacağını açıklar.

Devam ettirilebilir oturum URL'si kaydediliyor

Devam ettirilebilir bir yükleme oturumu başlatmak için gönderilen istek için sunucu, aşağıdaki başlık da dahil olmak üzere bir 200 OK HTTP durum koduyla yanıt verir:

  • X-Goog-Upload-URL: Kalan tüm istekler üzerinden yükleme işlemini tamamlamak için kullanılması gereken benzersiz bir URL.

Sonraki isteklerde kullanabilmek için devam ettirilebilir konum URL'sini kopyalayıp kaydedin.

Örnek: Devam ettirilebilir oturum URL'sini kaydetme

Aşağıdaki örnekte, devam ettirilebilir bir oturum URL'si ve boyut ayrıntı düzeyi gereksinimi 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

Dosya yükleniyor

Devam ettirilebilir oturumu olan bir dosyayı iki şekilde yükleyebilirsiniz:

  1. Tek bir istekte. Daha az istek gerektirdiği ve böylece daha iyi performans gösterdiği için bu yaklaşım genellikle en iyi seçenektir.
  2. Birden çok parça halinde. Bu yaklaşımı aşağıdaki durumlarda kullanın:
    • Herhangi bir tek istekte aktarılan veri miktarını azaltmanız gerekir. Tek tek istekler için sabit bir süre sınırı olduğunda bunu yapmanız gerekebilir.
    • Yükleme işleminin ilerleme durumunu gösteren özelleştirilmiş bir gösterge sağlamanız gerekir.
    • Verileri silmenin ne zaman güvenli olduğunu bilmeniz gerekir.

Tek İstek

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

  1. Devam ettirilebilir oturum URL'si için bir POST isteği oluşturun.
  2. Dosya verilerini istek gövdesine ekleyin.

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

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

  4. İsteği gönderin.

Yükleme isteği kesintiye uğrarsa veya 5xx yanıtı alırsanız Kesilen bir yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.

Birden Fazla Parça

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

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

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

    • Content-Length: Yığındaki bayt sayısına ayarlanır.
    • X-Goog-Upload-Command: upload olarak ayarlandı. Son yığın için upload, finalize olarak ayarlayın.
    • X-Goog-Upload-Offset: Baytların yazılması gereken 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 bir 5xx yanıtı alırsanız Kesintili bir yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.

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

Örnek: Dosyayı yükleme

Tek İstek

Aşağıdaki örnekte, önceki adımda elde edilen devam ettirilebilir oturum URL'si kullanılarak, 4.200.000 baytlık bir JPEG dosyasının tamamını tek bir istekte yüklemeyle ilgili 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 Parça

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

İlk grup: 

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 grup: 

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]

Kesilen bir 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'si için bir POST isteği oluşturun.
  2. X-Goog-Upload-Command cihazını query ayarlayın.
  3. İsteği gönderin.

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

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

Daha sonra, yükleme işlemine bu ofset düzeyinde devam edebilirsiniz. Birleşik bir yükleme ve sonlandırma komutu göndermediğiniz sürece sunucu tarafından sağlanan ofsette devam etmeniz gerekir. Bu durumda, ofset 0'dan 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.